Why do you want to add entropy source?

Good entropy is the fundamental basis for good cryptography and SSL or TLS. If your entropy is weak or predictable, a strong adversary can break your security.

So you want to have at least one, but preferably multiple sources of good or reasonable entropy.

For that purpose mbed TLS provides the entropy collector. The entropy collector takes entropy from multiple sources and combines it into a single entropy source for use.

Default entropy sources

If you take the stock mbed TLS, the entropy collector tries to use what the platform you run can provide. For Linux and UNIX-like systems, this is /dev/urandom, for Windows this is CryptGenRandom of the CryptoAPI. These are considered strong entropy sources.

If you have MBEDTLS_TIMING_C enabled, the entropy collector will also add the mbedtls_timing_hardclock() value. This is only a little entropy, but every bit helps.

If you have MBEDTLS_HAVEGE_C enabled, the HAVEGE RNG is also used. Warning: Be aware that the HAVEGE random generator is considered reasonable, but not good! So please do not base your full entropy on this.

Adding own sources

When you run mbed TLS on a different platform, such as an embedded platform you will have to add platform-specific or application-specific entropy sources.

To add a source to the entropy collector, you can use mbedtls_entropy_add_source(). It will require you to provide a callback (f_source) that can be called whenever the entropy pool tries to gather entropy, the data (p_source) that you need with your callback and a threshold. This threshold indicates the minimum number of bytes the entropy pool should wait on from this callback before releasing entropy. So choose this value wisely. Choosing a value that is higher than your callback can provide and you will block entropy collection.

Starting with the 2.0 branch, you will also need to indicate if this source is strong or not. For example, /dev/urandom and CryptGenRandom() are strong, if your platform has a hardware RNG it is a strong source, but the mbedtls_timing_hardclock() value and HAVEGE are weak. The entropy module will refuse to deliver entropy unless it has at least one strong source.

Entropy source failed

When collecting entropy for a request, the entropy pool will do a maximum of 256 polls to each entropy source to retrieve entropy from them. If the threshold value for a source is higher than the entropy it can deliver in those 256 polls, you will receive an error!

Limited sources

If you have an entropy source that only provides some limited entropy, but not on every poll, it can be wise to select a threshold value of 0. With a zero-threshold, it will not cause the entropy pool to return an error if it cannot provide any entropy in 256 calls.

Seed files

In addition to platform specific sources, such as timing of network packets, keyboard input, etc, you can also use a seed file to produce entropy for your system. The advantage of a seed file is that you can generate it on a high-entropy system and then update and use it on your low-entropy system. Warning: you must make sure the seed file is unique per device.

Did this help?