EFI random number generator protocol entropy source. More...

#include <errno.h>
#include <ipxe/entropy.h>
#include <ipxe/crc32.h>
#include <ipxe/efi/efi.h>
#include <ipxe/efi/Protocol/Rng.h>

Macros
#define	EFIRNG_LEN 32
	Minimum number of bytes to request from RNG. More...

#define	EFIRNG_MAX_RETRY 16
	Maximum number of times to attempting requesting data from RNG. More...

Functions
	FILE_LICENCE (GPL2_OR_LATER_OR_UBDL)

struct entropy_source efirng_entropy	__entropy_source (ENTROPY_NORMAL)
	EFI random number generator protocol entropy source. More...

	EFI_REQUEST_PROTOCOL (EFI_RNG_PROTOCOL, &efirng)

static int	efirng_enable (void)
	Enable entropy gathering. More...

static int	efirng_get_noise (noise_sample_t *noise)
	Get noise sample from RNG protocol. More...

Variables
static EFI_RNG_PROTOCOL *	efirng
	Random number generator protocol. More...

Detailed Description

EFI random number generator protocol entropy source.

Definition in file efi_rng.c.

Macro Definition Documentation

◆ EFIRNG_LEN

#define EFIRNG_LEN 32

Minimum number of bytes to request from RNG.

The UEFI spec states (for no apparently good reason) that "When a Deterministic Random Bit Generator (DRBG) is used on the output of a (raw) entropy source, its security level must be at least 256 bits." The EDK2 codebase (mis)interprets this to mean that the call to GetRNG() should fail if given a buffer less than 32 bytes.

Incidentally, nothing in the EFI RNG protocol provides any way to report the actual amount of entropy returned by GetRNG().

Definition at line 55 of file efi_rng.c.

◆ EFIRNG_MAX_RETRY

#define EFIRNG_MAX_RETRY 16

Maximum number of times to attempting requesting data from RNG.

The UEFI spec allows GetRNG() to return EFI_NOT_READY, which is not a particularly helpful error status since there is nothing that can sensibly be done except to retry immediately. We retry failed calls to GetRNG() (for any reason) up to this number of times.

Definition at line 64 of file efi_rng.c.

Function Documentation

◆ FILE_LICENCE()

FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL )

◆ __entropy_source()

struct entropy_source rtc_entropy __entropy_source ( ENTROPY_NORMAL )

Initial value:

= {
        .name = "efirng",
        .enable = efirng_enable,
        .get_noise = efirng_get_noise,
}

EFI random number generator protocol entropy source.

RTC entropy source.

◆ EFI_REQUEST_PROTOCOL()

EFI_REQUEST_PROTOCOL	(	EFI_RNG_PROTOCOL	,
		&	efirng
	)

◆ efirng_enable()

static int efirng_enable ( void )

static

Enable entropy gathering.

Return values

rc	Return status code

Definition at line 71 of file efi_rng.c.

                                   {
 
         /* Check for RNG protocol support */
         if ( ! efirng ) {
                 DBGC ( &efirng, "EFIRNG has no RNG protocol\n" );
                 return -ENOTSUP;
         }
 
         /* Nothing in the EFI specification provides any clue as to
          * how much entropy will be returned by GetRNG().  Make a
          * totally uninformed (and conservative guess) that each
          * sample will contain at least one bit of entropy.
          */
         entropy_init ( &efirng_entropy, MIN_ENTROPY ( 1.0 ) );
 
         return 0;
 }

References DBGC, efirng, ENOTSUP, entropy_init(), and MIN_ENTROPY.

◆ efirng_get_noise()

static int efirng_get_noise ( noise_sample_t * noise )

static

Get noise sample from RNG protocol.

Return values

noise	Noise sample
rc	Return status code

Definition at line 95 of file efi_rng.c.

                                                       {
         uint8_t buf[EFIRNG_LEN];
         unsigned int i;
         EFI_STATUS efirc;
         int rc;
 
         /* Sanity check */
         assert ( efirng != NULL );
 
         /* Get random bytes, retrying if needed */
         for ( i = 0 ; i < EFIRNG_MAX_RETRY ; i++ ) {
 
                 /* Get the minimum allowed number of random bytes */
                 if ( ( efirc = efirng->GetRNG ( efirng, NULL, sizeof ( buf ),
                                                 buf ) ) != 0 ) {
                         rc = -EEFI ( efirc );
                         continue;
                 }
 
                 /* Reduce random bytes to a single noise sample.  This
                  * seems like overkill, but we have no way of knowing
                  * how much entropy is actually present in the bytes
                  * returned by the RNG protocol.
                  */
                 *noise = crc32_le ( 0, buf, sizeof ( buf ) );
                 return 0;
         }
 
         DBGC ( &efirng, "ENTROPY could not read from RNG: %s\n",
                strerror ( rc ) );
         return rc;
 }