rbg.c File Reference

RBG mechanism. More...

#include <stdint.h>
#include <string.h>
#include <ipxe/init.h>
#include <ipxe/settings.h>
#include <ipxe/uuid.h>
#include <ipxe/crypto.h>
#include <ipxe/drbg.h>
#include <ipxe/rbg.h>

Go to the source code of this file.

Functions
	FILE_LICENCE (GPL2_OR_LATER_OR_UBDL)
	FILE_SECBOOT (PERMITTED)
static int	rbg_startup (void)
	Start up RBG.
int	rbg_generate (const void *additional, size_t additional_len, int prediction_resist, void *data, size_t len)
	Generate bits using RBG.
static void	rbg_shutdown (void)
	Shut down RBG.
static void	rbg_startup_fn (void)
	RBG startup function.
static void	rbg_shutdown_fn (int booting __unused)
	RBG shutdown function.
struct startup_fn startup_rbg	__startup_fn (STARTUP_NORMAL)
	RBG startup table entry.

Variables
struct random_bit_generator	rbg
	The RBG.

Detailed Description

RBG mechanism.

This mechanism is designed to comply with ANS X9.82 Part 4 (April 2011 Draft) Section 10. This standard is unfortunately not freely available.

The chosen RBG design is that of a DRBG with a live entropy source with no conditioning function. Only a single security strength is supported. No seedfile is used since there may be no non-volatile storage available. The system UUID is used as the personalisation string.

Definition in file rbg.c.

Function Documentation

FILE_LICENCE()

FILE_LICENCE

(

GPL2_OR_LATER_OR_UBDL

)

FILE_SECBOOT()

FILE_SECBOOT

(

PERMITTED

)

rbg_startup()

int rbg_startup ( void )

static

Start up RBG.

Return values

rc	Return status code

This is the RBG_Startup function defined in ANS X9.82 Part 4 (April 2011 Draft) Section 9.1.2.2.

Definition at line 74 of file rbg.c.

                                {
        union uuid uuid;
        int len;
        int rc;
 
        /* Record that startup has been attempted (even if unsuccessful) */
        rbg.started = 1;
 
        /* Try to obtain system UUID for use as personalisation
         * string, in accordance with ANS X9.82 Part 3-2007 Section
         * 8.5.2.  If no UUID is available, proceed without a
         * personalisation string.
         */
        if ( ( len = fetch_uuid_setting ( NULL, &uuid_setting, &uuid ) ) < 0 ) {
                rc = len;
                DBGC ( &rbg, "RBG could not fetch personalisation string: "
                       "%s\n", strerror ( rc ) );
                len = 0;
        }
 
        /* Instantiate DRBG */
        if ( ( rc = drbg_instantiate ( &rbg.state, &uuid, len ) ) != 0 ) {
                DBGC ( &rbg, "RBG could not instantiate DRBG: %s\n",
                       strerror ( rc ) );
                return rc;
        }
 
        return 0;
}

References DBGC, drbg_instantiate(), fetch_uuid_setting(), len, NULL, rbg, rc, and strerror().

Referenced by rbg_generate(), and rbg_startup_fn().

rbg_generate()

int rbg_generate	(	const void *	additional,
		size_t	additional_len,
		int	prediction_resist,
		void *	data,
		size_t	len )

Generate bits using RBG.

Parameters

additional	Additional input
additional_len	Length of additional input
prediction_resist	Prediction resistance is required
data	Output buffer
len	Length of output buffer

Return values

rc	Return status code

This is the RBG_Generate function defined in ANS X9.82 Part 4 (April 2011 Draft) Section 9.1.2.2.

Definition at line 117 of file rbg.c.

                                                                   {
 
        /* Attempt startup, if not already attempted */
        if ( ! rbg.started )
                rbg_startup();
 
        /* Generate bits.  The DRBG will itself return an error if it
         * is not valid (e.g. due to an instantiation failure).
         */
        return drbg_generate ( &rbg.state, additional, additional_len,
                               prediction_resist, data, len );
}

References additional, data, drbg_generate(), len, rbg, and rbg_startup().

Referenced by get_random_nz(), tls_generate_random(), and wpa_handle_1_of_4().

rbg_shutdown()

void rbg_shutdown ( void )

static

Shut down RBG.

Definition at line 135 of file rbg.c.

                                  {
 
        /* Uninstantiate DRBG */
        drbg_uninstantiate ( &rbg.state );
 
        /* Clear startup attempted flag */
        rbg.started = 0;
}

References drbg_uninstantiate(), and rbg.

Referenced by rbg_shutdown_fn().

rbg_startup_fn()

void rbg_startup_fn ( void )

static

RBG startup function.

Definition at line 145 of file rbg.c.

                                    {
 
        /* Start up RBG (if not already started on demand).  There is
         * no way to report an error at this stage, but a failed
         * startup will result in an invalid DRBG that refuses to
         * generate bits.
         */
        if ( ! rbg.started )
                rbg_startup();
}

References rbg, and rbg_startup().

Referenced by __startup_fn().

rbg_shutdown_fn()

void rbg_shutdown_fn ( int booting __unused )

static

RBG shutdown function.

Definition at line 157 of file rbg.c.

                                                     {
 
        /* Shut down RBG */
        rbg_shutdown();
}

References __unused, and rbg_shutdown().

Referenced by __startup_fn().

__startup_fn()

struct startup_fn startup_rbg __startup_fn

(

STARTUP_NORMAL

)

RBG startup table entry.

References __startup_fn, rbg_shutdown_fn(), rbg_startup_fn(), and STARTUP_NORMAL.

Variable Documentation

rbg

struct random_bit_generator rbg

The RBG.

Definition at line 64 of file rbg.c.

Referenced by rbg_generate(), rbg_shutdown(), rbg_startup(), and rbg_startup_fn().