Add CSPRNG

Tries to seed an AES-CTR based PRNG using the TRNG, RTC, SysTick and ADC.

It is not really a CSPRNG as revealing its state allows to compute all previous outputs (it has no forward secrecy). It also is only good up to a limited amount of randomness after seeding it. Fortuna for example does not use more than 1 MiB without reseeding such a construct. I guess that limit is set very conservative though.

I guess these two limitations (no forward secrecy and only a limited amount of strong randomness) is acceptable for us. Calls to the RNG seem to be very few and the device is usually power cycled often in comparison.

Seeding is done via a SHA256 over the following data:

• 256x 16 bytes from the TRNG. Amount of entropy is unknown.
• The current second and subsecond values from the RTC.
• Current value of the SysTick.
• 256x a 10 bit ADC reading. Maybe 1 bit of entropy per reading.

CSPRNG: https://en.wikipedia.org/wiki/Cryptographically_secure_pseudorandom_number_generator

FORTUNA: https://en.wikipedia.org/wiki/Fortuna_(PRNG)

Other potential options for a CSPRNG:

• https://github.com/smuellerDD/chacha20_drng
• https://www.silabs.com/documents/public/application-notes/AN0806.pdf

epicardium/epicardium.h

@@ -1922,13 +1922,19 @@ API(API_RTC_SCHEDULE_ALARM, int epic_rtc_schedule_alarm(uint32_t timestamp));
 API_ISR(EPIC_INT_RTC_ALARM, epic_isr_rtc_alarm);
 
 /**
- * TRNG
+ * RNG
  * ====
  */
 
 /**
  * Read random bytes from the TRNG.
  *
+ * Be aware that this function returns raw unprocessed bytes from
+ * the TRNG. They might be biased or have other kinds of imperfections.
+ *
+ * Use :c:func:`epic_csprng_read` for cryptographically safe random
+ * numbers instead.
+ *
  * :param uint8_t * dest: Destination buffer
  * :param size: Number of bytes to read.
  * :return: `0` on success or a negative value if an error occured. Possible
@@ -1938,7 +1944,20 @@ API_ISR(EPIC_INT_RTC_ALARM, epic_isr_rtc_alarm);
  */
 API(API_TRNG_READ, int epic_trng_read(uint8_t *dest, size_t size));
 
+/**
+ * Read random bytes from the CSPRNG.
+ *
+ * The random bytes returned are safe to be used for cryptography.
+ *
+ * :param uint8_t * dest: Destination buffer
+ * :param size: Number of bytes to read.
+ * :return: `0` on success or a negative value if an error occured. Possible
+ *    errors:
+ *
+ *    - ``-EFAULT``: Invalid destination address.
+ */
 API(API_CSPRNG_READ, int epic_csprng_read(uint8_t *dest, size_t size));
+
 /**
  * MAX30001
  * ========