ggentropy

A string formatting library for C++
Log | Files | Refs | README

README.md (2096B)

      1 # ggentropy
      2 
      3 [![Appveyor](https://ci.appveyor.com/api/projects/status/xjeb72qltn1l0r3v?svg=true)](https://ci.appveyor.com/project/mikejsavage/ggentropy) on Windows/macOS/Linux
      4 
      5 ggentropy is a liberally licensed and cross platform entropy library.
      6 You can use it to generate cryptographically secure random numbers, safe
      7 for use as nonces and keys in cryptographic operations.
      8 
      9 ggentropy supports Windows, Apple platforms, Linux, FreeBSD, OpenBSD and
     10 NetBSD.
     11 
     12 
     13 ## Version history
     14 
     15 - __v1.0 19th Jul 2021__:
     16   - Use `arc4random_buf` on Apple platforms
     17   - Drop `/dev/urandom` fallback on Linux because all versions that
     18     require it have been EOL for years
     19   - Drop Solaris support
     20 
     21 
     22 ## Usage
     23 
     24 ggentropy has one function:
     25 
     26 ```cpp
     27 bool ggentropy( void * buf, size_t n );
     28 ```
     29 
     30 which writes `n` bytes of crytographically secure random data to `buf`.
     31 It returns true on success and false on failure. Some platforms place a
     32 length restriction on `n`, so the library will exit on all platforms if
     33 `n` is greater than 256.
     34 
     35 Basic usage looks like this:
     36 
     37 ```cpp
     38 #include <stdio.h>
     39 #include <stdint.h>
     40 #include <inttypes.h>
     41 #include "ggentropy.h"
     42 
     43 int main() {
     44 	uint8_t entropy[ 16 ];
     45 	if( !ggentropy( entropy, sizeof( entropy ) ) )
     46 		return 1;
     47 
     48 	for( size_t i = 0; i < sizeof( entropy ); i++ ) {
     49 		printf( "%02" PRIx8, entropy[ i ] );
     50 	}
     51 	printf( "\n" );
     52 
     53 	return 0;
     54 }
     55 ```
     56 
     57 `ggentropy` can fail. In long lived programs you should use it to seed a
     58 userspace cryptographically secure psuedo-random number generator once
     59 at program startup and use that for all future cryptographically secure
     60 random data. For example, you can encrypt a stream of zeroes using a key
     61 chosen by ggentropy, and use the output of the cipher as a random number
     62 source.
     63 
     64 
     65 ## Implementation details
     66 
     67 ggentropy uses the following functionality:
     68 
     69 | OS | Implementation |
     70 | - | - |
     71 | Windows | [BCryptGenRandom](https://docs.microsoft.com/en-us/windows/win32/api/bcrypt/nf-bcrypt-bcryptgenrandom) |
     72 | Linux | [getrandom](https://lwn.net/Articles/606141/) |
     73 | macOS/iOS/BSD | [arc4random_buf](https://man.openbsd.org/arc4random_buf) |