// Written in the D programming language. /+ CSPRNG library prototype. This code has not been audited. Do not use for cryptographic purposes. The terms $(I entropy) and $(I entropy sources) here do refer to cryptographically-safe random numbers and higher-level generators of such — typically powered by an entropy pool provided by the operating system. An example of similar usage of said terminology would be the `getentropy()` function provided by $(LINK2 https://man.freebsd.org/cgi/man.cgi?query=getentropy&apropos=0&sektion=3&manpath=FreeBSD+14.2-RELEASE&arch=default&format=html, FreeBSD). This library does not interact with any actual low-level entropy sources by itself. Instead it interfaces with system-provided CSPRNGs that are typically seeded through aforementioned entropy sources by the operating system as needed. See_also: $(LINK https://blog.cr.yp.to/20140205-entropy.html), $(LINK https://cr.yp.to/talks/2014.10.18/slides-djb-20141018-a4.pdf) License: $(HTTP www.boost.org/LICENSE_1_0.txt, Boost License 1.0). Authors: Elias Batek Source: $(PHOBOSSRC std/internal/entropy.d) +/module std.internal.entropy; import std.meta; version (OSX) version = Darwin;else version (iOS) version = Darwin;else version (TVOS) version = Darwin;else version (WatchOS) version = Darwin; // Self-test: Detect potentially unsuitable default entropy source.@safe unittest{ auto buffer = new ubyte[](32); forceEntropySource(defaultEntropySource); const result = getEntropy(buffer); assert( !result.isUnavailable, "The default entropy source for the target platform" ~ " is unavailable on this machine. Please consider" ~ " patching it to accommodate to your environment." ); assert(result.isOK);} // Self-test: Detect faulty implementation.@system unittest{ forceEntropySource(defaultEntropySource); bool test() @system { static immutable pattern = 0xDEAD_BEEF_1337_0000; long number = pattern; const result = getEntropy(&number, number.sizeof); assert(result.isOK); return number != pattern; } size_t timesFailed = 0; foreach (n; 0 .. 3) if (!test()) ++timesFailed; assert( timesFailed <= 1, "Suspicious random data: Potential security issue or really unlucky; please retry." );} // Self-test: Detect faulty implementation.@safe unittest{ forceEntropySource(defaultEntropySource); bool test() @safe { ubyte[32] data; data[] = 0; const result = getEntropy(data[]); assert(result.isOK); size_t zeros = 0; foreach (b; data) if (b == 0) ++zeros; enum threshold = 24; return zeros < threshold; } size_t timesFailed = 0; foreach (n; 0 .. 3) if (!test()) ++timesFailed; assert( timesFailed <= 1, "Suspicious random data: Potential security issue or really unlucky; please retry." );} @nogc nothrow: // Flagship function/++ Retrieves random data from an applicable system CSPRNG. Params: buffer = An output buffer to store the retrieved entropy in. The length of it will determine the amount of random data to be obtained. This function (and all overloads) always attempt to fill the entire buffer. Therefore, they can block, spin or report an error. Returns: An `EntropyResult` that either reports success or the type of error that has occurred. In case of an error, the data in `buffer` MUST NOT be used. The recommended way to check for success is through the `isOK()` helper function. +/EntropyResult getEntropy(scope void[] buffer) @safe{ return getEntropyImpl(buffer);} ///@safe unittest{ int[4] bytes; if (getEntropy(cast(void[]) bytes).isOK) { // Success; data in `bytes` may be used. } assert((cast(void[]) bytes).length == bytes.sizeof);} // Convenience overload/// dittoEntropyResult getEntropy(scope ubyte[] buffer) @safe{ return getEntropy(cast(void[]) buffer);} ///@safe unittest{ ubyte[16] bytes; if (getEntropy(bytes).isOK) { // Success; data in `bytes` may be used. }} // Convenience wrapper/// ditto/++ Retrieves random data from an applicable system CSPRNG. Params: buffer = An output buffer to store the retrieved entropy in. length = Length of the provided `buffer`. Specifying a wrong value here, will lead to memory corruption. Returns: An `EntropyResult` that either reports success or the type of error that has occurred. In case of an error, the data in `buffer` MUST NOT be used. The recommended way to check for success is through the `isOK()` helper function. +/EntropyResult getEntropy(scope void* buffer, size_t length) @system{ return getEntropy(buffer[0 .. length]);} ///@system unittest{ ubyte[16] bytes; if (getEntropy(cast(void*) bytes.ptr, bytes.length).isOK) { // Success; data in `bytes` may be used. }} ///@system unittest{ int number = void; if (getEntropy(&number, number.sizeof).isOK) { // Success; value of `number` may be used. }} /++ Manually set the entropy source to use for the current thread. As a rule of thumb, this SHOULD NOT be done. It might be useful in cases where the default entropy source — as chosen by the maintainer of the used compiler package — is unavailable on a system. Usually, `EntropySource.tryAll` will be the most reasonable option in such cases. Params: source = The requested default entropy source to use for the current thread. Examples: --- // Using `forceEntropySource` almost always is a bad idea. // As a rule of thumb, this SHOULD NOT be done. forceEntropySource(EntropySource.none); --- +/void forceEntropySource(EntropySource source) @safe{ _entropySource = source;} // (In-)Convenience wrapper/++ Retrieves random data from the requested entropy source. In general, it’s a $(B bad idea) to let users pick sources themselves. A sane option should be used by default instead. This overload only exists because its used by Phobos. See_also: Use `forceEntropySource` instead. Params: buffer = An output buffer to store the retrieved entropy in. The length of it will determine the amount of entropy to be obtained. length = Length of the provided `buffer`. Specifying a wrong value here, will lead to memory corruption. source = The entropy source to use for the operation. Returns: An `EntropyResult` that either reports success or the type of error that has occurred. In case of an error, the data in `buffer` MUST NOT be used. The recommended way to check for success is through the `isOK()` helper function. +/EntropyResult getEntropy(scope void* buffer, size_t length, EntropySource source) @system{ const sourcePrevious = _entropySource; scope (exit) _entropySource = sourcePrevious; _entropySource = source; return getEntropy(buffer[0 .. length]);} ///@system unittest{ ubyte[4] bytes; // `EntropySource.none` always fails. assert(!getEntropy(bytes.ptr, bytes.length, EntropySource.none).isOK);} /++ A CSPRNG suitable to retrieve cryptographically-secure random data from. (No actual low-level entropy sources are provided on purpose.) +/enum EntropySource{ /// Implements a $(I hunting) strategy for finding an entropy source that /// is available at runtime. /// /// Try supported sources one-by-one until one is available. /// This exists to enable the use of this the entropy library /// in a backwards compatibility way. /// /// It is recommended against using this in places that do not strictly /// have to to meet compatibility requirements. /// Like any kind of crypto-agility, this approach may suffer from /// practical issues. /// /// See_also: /// While the following article focuses on cipher agility in protocols, /// it elaborates why agility can lead to problems: /// $(LINK https://web.archive.org/web/20191102211148/https://paragonie.com/blog/2019/10/against-agility-in-cryptography-protocols) tryAll = -1, /// Always fail. none = 0, /// `/dev/urandom` charDevURandom = 1, /// `/dev/random` charDevRandom = 2, /// `getrandom` syscall or wrapper getrandom = 3, /// `arc4random` arc4random = 4, // `getentropy` getentropy = 5, /// Windows legacy CryptoAPI cryptGenRandom = 6, /// Windows Cryptography API: Next Generation (“BCrypt”) bcryptGenRandom = 7,} ///enum EntropyStatus{ /// success ok = 0, /// catch-all error unknownError = 1, /// An entropy source was unavailable. unavailable, /// A dependency providing the entropy source turned out unavailable. unavailableLibrary, /// The requested entropy source is not supported on this platform. unavailablePlatform, /// Could not retrieve entropy from the selected source. readError,} /++ Status report returned by `getEntropy` functions. Use the `isOK` helper function to test for success. +/struct EntropyResult{ /// EntropyStatus status; /// EntropySource source; /++ Returns: A human-readable status message. +/ string toString() const @nogc nothrow pure @safe { if (status == EntropyStatus.ok) return "getEntropy(): OK."; if (source == EntropySource.none) { if (status == EntropyStatus.unavailable) return "getEntropy(): Error - No suitable entropy source was available."; } else if (source == EntropySource.getrandom) { if (status == EntropyStatus.unavailableLibrary) return "getEntropy(): `dlopen(\"libc\")` failed."; if (status == EntropyStatus.unavailable) return "getEntropy(): `dlsym(\"libc\", \"getrandom\")` failed."; if (status == EntropyStatus.readError) return "getEntropy(): `getrandom()` failed."; } else if (source == EntropySource.getentropy) { if (status == EntropyStatus.readError) return "getEntropy(): `getentropy()` failed."; } else if (source == EntropySource.charDevURandom) { if (status == EntropyStatus.unavailable) return "getEntropy(): `/dev/urandom` is unavailable."; if (status == EntropyStatus.readError) return "getEntropy(): Reading from `/dev/urandom` failed."; } else if (source == EntropySource.charDevURandom) { if (status == EntropyStatus.unavailable) return "getEntropy(): `/dev/random` is unavailable."; if (status == EntropyStatus.readError) return "getEntropy(): Reading from `/dev/random` failed."; } else if (source == EntropySource.bcryptGenRandom) { if (status == EntropyStatus.unavailableLibrary) return "getEntropy(): `LoadLibraryA(\"Bcrypt.dll\")` failed."; if (status == EntropyStatus.unavailable) return "getEntropy(): `GetProcAddress(hBcrypt , \"BCryptGenRandom\")` failed."; if (status == EntropyStatus.readError) return "getEntropy(): `BCryptGenRandom()` failed."; } // generic errors { if (status == EntropyStatus.unavailable || status == EntropyStatus.unavailableLibrary) return "getEntropy(): An entropy source was unavailable."; if (status == EntropyStatus.unavailablePlatform) return "getEntropy(): The requested entropy source is not supported on this platform."; if (status == EntropyStatus.readError) return "getEntropy(): Could not retrieve entropy from the selected source."; return "getEntropy(): An unknown error occurred."; } }} ///@safe unittest{ ubyte[4] data; EntropyResult result = getEntropy(data[]); if (result.isOK) { // Success; data in `bytes` may be used. } else { // Failure if (result.isUnavailable) { // System’s entropy source was unavailable. } // Call `toString` to obtain a user-readable error message. assert(result.toString() !is null); assert(result.toString().length > 0); }} /++ Determines whether an `EntropyResult` reports the success of an operation. Params: value = test subject Returns: `true` on success +/pragma(inline, true) bool isOK(const EntropyResult value) pure @safe{ return value.status == EntropyStatus.ok;} /++ Determines whether an `EntropyResult` reports the unvailability of the requested entropy source. Params: value = test subject Returns: `true` if entropy source requested to use with the operation was unavailable. +/pragma(inline, true) bool isUnavailable(const EntropyResult value) pure @safe{ return ( value.status == EntropyStatus.unavailable || value.status == EntropyStatus.unavailableLibrary || value.status == EntropyStatus.unavailablePlatform );} package(std):Lines 1–500 of 918. Load more
// Written in the D programming language. /+ CSPRNG library prototype. This code has not been audited. Do not use for cryptographic purposes. The terms $(I entropy) and $(I entropy sources) here do refer to cryptographically-safe random numbers and higher-level generators of such — typically powered by an entropy pool provided by the operating system. An example of similar usage of said terminology would be the `getentropy()` function provided by $(LINK2 https://man.freebsd.org/cgi/man.cgi?query=getentropy&apropos=0&sektion=3&manpath=FreeBSD+14.2-RELEASE&arch=default&format=html, FreeBSD). This library does not interact with any actual low-level entropy sources by itself. Instead it interfaces with system-provided CSPRNGs that are typically seeded through aforementioned entropy sources by the operating system as needed. See_also: $(LINK https://blog.cr.yp.to/20140205-entropy.html), $(LINK https://cr.yp.to/talks/2014.10.18/slides-djb-20141018-a4.pdf) License: $(HTTP www.boost.org/LICENSE_1_0.txt, Boost License 1.0). Authors: Elias Batek Source: $(PHOBOSSRC std/internal/entropy.d) +/ module std.internal.entropy; import std.meta; version (OSX) version = Darwin; else version (iOS) version = Darwin; else version (TVOS) version = Darwin; else version (WatchOS) version = Darwin; // Self-test: Detect potentially unsuitable default entropy source. @safe unittest { auto buffer = new ubyte[](32); forceEntropySource(defaultEntropySource); const result = getEntropy(buffer); assert( !result.isUnavailable, "The default entropy source for the target platform" ~ " is unavailable on this machine. Please consider" ~ " patching it to accommodate to your environment." ); assert(result.isOK); } // Self-test: Detect faulty implementation. @system unittest { forceEntropySource(defaultEntropySource); bool test() @system { static immutable pattern = 0xDEAD_BEEF_1337_0000; long number = pattern; const result = getEntropy(&number, number.sizeof); assert(result.isOK); return number != pattern; } size_t timesFailed = 0; foreach (n; 0 .. 3) if (!test()) ++timesFailed; assert( timesFailed <= 1, "Suspicious random data: Potential security issue or really unlucky; please retry." ); } // Self-test: Detect faulty implementation. @safe unittest { forceEntropySource(defaultEntropySource); bool test() @safe { ubyte[32] data; data[] = 0; const result = getEntropy(data[]); assert(result.isOK); size_t zeros = 0; foreach (b; data) if (b == 0) ++zeros; enum threshold = 24; return zeros < threshold; } size_t timesFailed = 0; foreach (n; 0 .. 3) if (!test()) ++timesFailed; assert( timesFailed <= 1, "Suspicious random data: Potential security issue or really unlucky; please retry." ); } @nogc nothrow: // Flagship function /++ Retrieves random data from an applicable system CSPRNG. Params: buffer = An output buffer to store the retrieved entropy in. The length of it will determine the amount of random data to be obtained. This function (and all overloads) always attempt to fill the entire buffer. Therefore, they can block, spin or report an error. Returns: An `EntropyResult` that either reports success or the type of error that has occurred. In case of an error, the data in `buffer` MUST NOT be used. The recommended way to check for success is through the `isOK()` helper function. +/ EntropyResult getEntropy(scope void[] buffer) @safe { return getEntropyImpl(buffer); } /// @safe unittest { int[4] bytes; if (getEntropy(cast(void[]) bytes).isOK) { // Success; data in `bytes` may be used. } assert((cast(void[]) bytes).length == bytes.sizeof); } // Convenience overload /// ditto EntropyResult getEntropy(scope ubyte[] buffer) @safe { return getEntropy(cast(void[]) buffer); } /// @safe unittest { ubyte[16] bytes; if (getEntropy(bytes).isOK) { // Success; data in `bytes` may be used. } } // Convenience wrapper /// ditto /++ Retrieves random data from an applicable system CSPRNG. Params: buffer = An output buffer to store the retrieved entropy in. length = Length of the provided `buffer`. Specifying a wrong value here, will lead to memory corruption. Returns: An `EntropyResult` that either reports success or the type of error that has occurred. In case of an error, the data in `buffer` MUST NOT be used. The recommended way to check for success is through the `isOK()` helper function. +/ EntropyResult getEntropy(scope void* buffer, size_t length) @system { return getEntropy(buffer[0 .. length]); } /// @system unittest { ubyte[16] bytes; if (getEntropy(cast(void*) bytes.ptr, bytes.length).isOK) { // Success; data in `bytes` may be used. } } /// @system unittest { int number = void; if (getEntropy(&number, number.sizeof).isOK) { // Success; value of `number` may be used. } } /++ Manually set the entropy source to use for the current thread. As a rule of thumb, this SHOULD NOT be done. It might be useful in cases where the default entropy source — as chosen by the maintainer of the used compiler package — is unavailable on a system. Usually, `EntropySource.tryAll` will be the most reasonable option in such cases. Params: source = The requested default entropy source to use for the current thread. Examples: --- // Using `forceEntropySource` almost always is a bad idea. // As a rule of thumb, this SHOULD NOT be done. forceEntropySource(EntropySource.none); --- +/ void forceEntropySource(EntropySource source) @safe { _entropySource = source; } // (In-)Convenience wrapper /++ Retrieves random data from the requested entropy source. In general, it’s a $(B bad idea) to let users pick sources themselves. A sane option should be used by default instead. This overload only exists because its used by Phobos. See_also: Use `forceEntropySource` instead. Params: buffer = An output buffer to store the retrieved entropy in. The length of it will determine the amount of entropy to be obtained. length = Length of the provided `buffer`. Specifying a wrong value here, will lead to memory corruption. source = The entropy source to use for the operation. Returns: An `EntropyResult` that either reports success or the type of error that has occurred. In case of an error, the data in `buffer` MUST NOT be used. The recommended way to check for success is through the `isOK()` helper function. +/ EntropyResult getEntropy(scope void* buffer, size_t length, EntropySource source) @system { const sourcePrevious = _entropySource; scope (exit) _entropySource = sourcePrevious; _entropySource = source; return getEntropy(buffer[0 .. length]); } /// @system unittest { ubyte[4] bytes; // `EntropySource.none` always fails. assert(!getEntropy(bytes.ptr, bytes.length, EntropySource.none).isOK); } /++ A CSPRNG suitable to retrieve cryptographically-secure random data from. (No actual low-level entropy sources are provided on purpose.) +/ enum EntropySource { /// Implements a $(I hunting) strategy for finding an entropy source that /// is available at runtime. /// /// Try supported sources one-by-one until one is available. /// This exists to enable the use of this the entropy library /// in a backwards compatibility way. /// /// It is recommended against using this in places that do not strictly /// have to to meet compatibility requirements. /// Like any kind of crypto-agility, this approach may suffer from /// practical issues. /// /// See_also: /// While the following article focuses on cipher agility in protocols, /// it elaborates why agility can lead to problems: /// $(LINK https://web.archive.org/web/20191102211148/https://paragonie.com/blog/2019/10/against-agility-in-cryptography-protocols) tryAll = -1, /// Always fail. none = 0, /// `/dev/urandom` charDevURandom = 1, /// `/dev/random` charDevRandom = 2, /// `getrandom` syscall or wrapper getrandom = 3, /// `arc4random` arc4random = 4, // `getentropy` getentropy = 5, /// Windows legacy CryptoAPI cryptGenRandom = 6, /// Windows Cryptography API: Next Generation (“BCrypt”) bcryptGenRandom = 7, } /// enum EntropyStatus { /// success ok = 0, /// catch-all error unknownError = 1, /// An entropy source was unavailable. unavailable, /// A dependency providing the entropy source turned out unavailable. unavailableLibrary, /// The requested entropy source is not supported on this platform. unavailablePlatform, /// Could not retrieve entropy from the selected source. readError, } /++ Status report returned by `getEntropy` functions. Use the `isOK` helper function to test for success. +/ struct EntropyResult { /// EntropyStatus status; /// EntropySource source; /++ Returns: A human-readable status message. +/ string toString() const @nogc nothrow pure @safe { if (status == EntropyStatus.ok) return "getEntropy(): OK."; if (source == EntropySource.none) { if (status == EntropyStatus.unavailable) return "getEntropy(): Error - No suitable entropy source was available."; } else if (source == EntropySource.getrandom) { if (status == EntropyStatus.unavailableLibrary) return "getEntropy(): `dlopen(\"libc\")` failed."; if (status == EntropyStatus.unavailable) return "getEntropy(): `dlsym(\"libc\", \"getrandom\")` failed."; if (status == EntropyStatus.readError) return "getEntropy(): `getrandom()` failed."; } else if (source == EntropySource.getentropy) { if (status == EntropyStatus.readError) return "getEntropy(): `getentropy()` failed."; } else if (source == EntropySource.charDevURandom) { if (status == EntropyStatus.unavailable) return "getEntropy(): `/dev/urandom` is unavailable."; if (status == EntropyStatus.readError) return "getEntropy(): Reading from `/dev/urandom` failed."; } else if (source == EntropySource.charDevURandom) { if (status == EntropyStatus.unavailable) return "getEntropy(): `/dev/random` is unavailable."; if (status == EntropyStatus.readError) return "getEntropy(): Reading from `/dev/random` failed."; } else if (source == EntropySource.bcryptGenRandom) { if (status == EntropyStatus.unavailableLibrary) return "getEntropy(): `LoadLibraryA(\"Bcrypt.dll\")` failed."; if (status == EntropyStatus.unavailable) return "getEntropy(): `GetProcAddress(hBcrypt , \"BCryptGenRandom\")` failed."; if (status == EntropyStatus.readError) return "getEntropy(): `BCryptGenRandom()` failed."; } // generic errors { if (status == EntropyStatus.unavailable || status == EntropyStatus.unavailableLibrary) return "getEntropy(): An entropy source was unavailable."; if (status == EntropyStatus.unavailablePlatform) return "getEntropy(): The requested entropy source is not supported on this platform."; if (status == EntropyStatus.readError) return "getEntropy(): Could not retrieve entropy from the selected source."; return "getEntropy(): An unknown error occurred."; } } } /// @safe unittest { ubyte[4] data; EntropyResult result = getEntropy(data[]); if (result.isOK) { // Success; data in `bytes` may be used. } else { // Failure if (result.isUnavailable) { // System’s entropy source was unavailable. } // Call `toString` to obtain a user-readable error message. assert(result.toString() !is null); assert(result.toString().length > 0); } } /++ Determines whether an `EntropyResult` reports the success of an operation. Params: value = test subject Returns: `true` on success +/ pragma(inline, true) bool isOK(const EntropyResult value) pure @safe { return value.status == EntropyStatus.ok; } /++ Determines whether an `EntropyResult` reports the unvailability of the requested entropy source. Params: value = test subject Returns: `true` if entropy source requested to use with the operation was unavailable. +/ pragma(inline, true) bool isUnavailable(const EntropyResult value) pure @safe { return ( value.status == EntropyStatus.unavailable || value.status == EntropyStatus.unavailableLibrary || value.status == EntropyStatus.unavailablePlatform ); } package(std):