efi_rng.c File Reference

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>

Go to the source code of this file.

Macros
#define	EFIRNG_LEN   32
	Minimum number of bytes to request from RNG.
#define	EFIRNG_MAX_RETRY   16
	Maximum number of times to attempting requesting data from RNG.

Functions
	FILE_LICENCE (GPL2_OR_LATER_OR_UBDL)
	FILE_SECBOOT (PERMITTED)
struct entropy_source efirng_entropy	__entropy_source (ENTROPY_NORMAL)
	EFI random number generator protocol entropy source.
	EFI_REQUEST_PROTOCOL (EFI_RNG_PROTOCOL, &efirng)
static int	efirng_enable (void)
	Enable entropy gathering.
static int	efirng_get_noise (noise_sample_t *noise)
	Get noise sample from RNG protocol.

Variables
static EFI_RNG_PROTOCOL *	efirng
	Random number generator protocol.

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 56 of file efi_rng.c.

Referenced by efirng_get_noise().

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 65 of file efi_rng.c.

Referenced by efirng_get_noise().

Function Documentation

FILE_LICENCE()

FILE_LICENCE

(

GPL2_OR_LATER_OR_UBDL

)

FILE_SECBOOT()

FILE_SECBOOT

(

PERMITTED

)

__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.

References __entropy_source, and ENTROPY_NORMAL.

EFI_REQUEST_PROTOCOL()

EFI_REQUEST_PROTOCOL	(	EFI_RNG_PROTOCOL	,
		&	efirng )

References efirng.

efirng_enable()

int efirng_enable ( void )

static

Enable entropy gathering.

Return values

rc	Return status code

Definition at line 72 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()

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 96 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;
}

References assert, crc32_le(), DBGC, EEFI, efirng, EFIRNG_LEN, EFIRNG_MAX_RETRY, NULL, rc, and strerror().

Variable Documentation

efirng

EFI_RNG_PROTOCOL* efirng

static

Random number generator protocol.

Definition at line 42 of file efi_rng.c.

Referenced by EFI_REQUEST_PROTOCOL(), efirng_enable(), and efirng_get_noise().