ggentropy

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

README.md (1694B)


      1 # ggentropy
      2 
      3 ggentropy is a liberally licensed, cross platform, entropy library for
      4 C++. You can use it to generate cryptographically secure random numbers,
      5 safe for use as nonces and keys in cryptographic operations.
      6 
      7 ggentropy supports Windows, MacOS, Linux and OpenBSD.
      8 
      9 
     10 ## Usage
     11 
     12 ggentropy has one function:
     13 
     14 ```cpp
     15 bool ggentropy( void * buf, size_t n );
     16 ```
     17 
     18 which writes `n` bytes of crytographically secure random data to `buf`.
     19 It returns true on success and false on failure. Some platforms place a
     20 length restriction on `n`, so the library will exit on all platforms if
     21 `n` is greater than 256.
     22 
     23 Basic usage looks like this:
     24 
     25 ```cpp
     26 #include <stdio.h>
     27 #include <stdint.h>
     28 #include <inttypes.h>
     29 #include "ggentropy.h"
     30 
     31 int main() {
     32 	uint8_t entropy[ 16 ];
     33 	if( !ggentropy( entropy, sizeof( entropy ) ) )
     34 		return 1;
     35 
     36 	for( size_t i = 0; i < sizeof( entropy ); i++ ) {
     37 		printf( "%02" PRIx8, entropy[ i ] );
     38 	}
     39 	printf( "\n" );
     40 
     41 	return 0;
     42 }
     43 ```
     44 
     45 `ggentropy` can fail. In long lived programs you should use it to seed a
     46 userspace cryptographically secure psuedo-random number generator once
     47 at program startup and use that for all future cryptographically secure
     48 random data. For example, you can encrypt a stream of zeroes using a key
     49 chosen by ggentropy, and use the output of the cipher as a random number
     50 source.
     51 
     52 
     53 ## Implementation details
     54 
     55 ggentropy uses the following functionality:
     56 
     57 - Windows: [CryptGenRandom](https://docs.microsoft.com/en-us/windows/win32/api/wincrypt/nf-wincrypt-cryptgenrandom)
     58 - MacOS: /dev/urandom
     59 - Linux: [getrandom](https://lwn.net/Articles/606141/) with a fallback to /dev/urandom
     60 - OpenBSD: [arc4random_buf](https://man.openbsd.org/arc4random_buf)