ffdhe.c

Go to the documentation of this file.

/*
 * Copyright (C) 2026 Michael Brown <mbrown@fensystems.co.uk>.
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License as
 * published by the Free Software Foundation; either version 2 of the
 * License, or any later version.
 *
 * This program is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
 * 02110-1301, USA.
 *
 * You can also choose to distribute this program under the terms of
 * the Unmodified Binary Distribution Licence (as given in the file
 * COPYING.UBDL), provided that you have satisfied its requirements.
 */
 
FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL );
FILE_SECBOOT ( PERMITTED );
 
/** @file
 *
 * Finite Field Diffie-Hellman Ephemeral key exchange
 *
 * RFC 7919 defines a family of finite fields all constructed from the
 * natural logarithm constant "e".
 *
 * We choose to support only up to ffdhe4096, since this is sufficient
 * to exceed the security strength of our RNG (128 bits).
 *
 * Support for ffdhe6144 and ffdhe8192 could trivially be added by
 * simply extending the "euler" constant and adding the relevant
 * FFDHE_GROUP() declarations.  Doing so would approximately double
 * the space requirements for both read-only data (from 0.5kB to 1kB)
 * and for uninitialised data (from 3.5kB to 7kB).
 *
 * RFC 3526 defines an almost identical family of finite fields all
 * constructed from the constant "pi", which may be used by older TLS
 * servers.
 */
 
#include <assert.h>
#include <stdint.h>
#include <stdlib.h>
#include <string.h>
#include <errno.h>
#include <ipxe/ffdhe.h>
 
/** Maximum length of FFDHE prime modulus */
#define FFDHE_LEN 512
 
/** Maximum length of group constant portion of FFDHE prime modulus */
#define FFDHE_CONSTANT_LEN \
        ( FFDHE_LEN - 8 /* high */ - 4 /* lsb32 */ - 8 /* low */ )
 
/** An FFDHE prime modulus */
#define ffdhe_modulus_t( len )                                            \
        struct {                                                          \
                uint64_t high;                                            \
                uint8_t constant[ len + FFDHE_CONSTANT_LEN - FFDHE_LEN ]; \
                uint32_t lsb32;                                           \
                uint64_t low;                                             \
        } __attribute__ (( packed ))
 
/** Euler's constant ("e") */
static const uint8_t euler[] = {
        0xad, 0xf8, 0x54, 0x58, 0xa2, 0xbb, 0x4a, 0x9a, 0xaf, 0xdc, 0x56,
        0x20, 0x27, 0x3d, 0x3c, 0xf1, 0xd8, 0xb9, 0xc5, 0x83, 0xce, 0x2d,
        0x36, 0x95, 0xa9, 0xe1, 0x36, 0x41, 0x14, 0x64, 0x33, 0xfb, 0xcc,
        0x93, 0x9d, 0xce, 0x24, 0x9b, 0x3e, 0xf9, 0x7d, 0x2f, 0xe3, 0x63,
        0x63, 0x0c, 0x75, 0xd8, 0xf6, 0x81, 0xb2, 0x02, 0xae, 0xc4, 0x61,
        0x7a, 0xd3, 0xdf, 0x1e, 0xd5, 0xd5, 0xfd, 0x65, 0x61, 0x24, 0x33,
        0xf5, 0x1f, 0x5f, 0x06, 0x6e, 0xd0, 0x85, 0x63, 0x65, 0x55, 0x3d,
        0xed, 0x1a, 0xf3, 0xb5, 0x57, 0x13, 0x5e, 0x7f, 0x57, 0xc9, 0x35,
        0x98, 0x4f, 0x0c, 0x70, 0xe0, 0xe6, 0x8b, 0x77, 0xe2, 0xa6, 0x89,
        0xda, 0xf3, 0xef, 0xe8, 0x72, 0x1d, 0xf1, 0x58, 0xa1, 0x36, 0xad,
        0xe7, 0x35, 0x30, 0xac, 0xca, 0x4f, 0x48, 0x3a, 0x79, 0x7a, 0xbc,
        0x0a, 0xb1, 0x82, 0xb3, 0x24, 0xfb, 0x61, 0xd1, 0x08, 0xa9, 0x4b,
        0xb2, 0xc8, 0xe3, 0xfb, 0xb9, 0x6a, 0xda, 0xb7, 0x60, 0xd7, 0xf4,
        0x68, 0x1d, 0x4f, 0x42, 0xa3, 0xde, 0x39, 0x4d, 0xf4, 0xae, 0x56,
        0xed, 0xe7, 0x63, 0x72, 0xbb, 0x19, 0x0b, 0x07, 0xa7, 0xc8, 0xee,
        0x0a, 0x6d, 0x70, 0x9e, 0x02, 0xfc, 0xe1, 0xcd, 0xf7, 0xe2, 0xec,
        0xc0, 0x34, 0x04, 0xcd, 0x28, 0x34, 0x2f, 0x61, 0x91, 0x72, 0xfe,
        0x9c, 0xe9, 0x85, 0x83, 0xff, 0x8e, 0x4f, 0x12, 0x32, 0xee, 0xf2,
        0x81, 0x83, 0xc3, 0xfe, 0x3b, 0x1b, 0x4c, 0x6f, 0xad, 0x73, 0x3b,
        0xb5, 0xfc, 0xbc, 0x2e, 0xc2, 0x20, 0x05, 0xc5, 0x8e, 0xf1, 0x83,
        0x7d, 0x16, 0x83, 0xb2, 0xc6, 0xf3, 0x4a, 0x26, 0xc1, 0xb2, 0xef,
        0xfa, 0x88, 0x6b, 0x42, 0x38, 0x61, 0x1f, 0xcf, 0xdc, 0xde, 0x35,
        0x5b, 0x3b, 0x65, 0x19, 0x03, 0x5b, 0xbc, 0x34, 0xf4, 0xde, 0xf9,
        0x9c, 0x02, 0x38, 0x61, 0xb4, 0x6f, 0xc9, 0xd6, 0xe6, 0xc9, 0x07,
        0x7a, 0xd9, 0x1d, 0x26, 0x91, 0xf7, 0xf7, 0xee, 0x59, 0x8c, 0xb0,
        0xfa, 0xc1, 0x86, 0xd9, 0x1c, 0xae, 0xfe, 0x13, 0x09, 0x85, 0x13,
        0x92, 0x70, 0xb4, 0x13, 0x0c, 0x93, 0xbc, 0x43, 0x79, 0x44, 0xf4,
        0xfd, 0x44, 0x52, 0xe2, 0xd7, 0x4d, 0xd3, 0x64, 0xf2, 0xe2, 0x1e,
        0x71, 0xf5, 0x4b, 0xff, 0x5c, 0xae, 0x82, 0xab, 0x9c, 0x9d, 0xf6,
        0x9e, 0xe8, 0x6d, 0x2b, 0xc5, 0x22, 0x36, 0x3a, 0x0d, 0xab, 0xc5,
        0x21, 0x97, 0x9b, 0x0d, 0xea, 0xda, 0x1d, 0xbf, 0x9a, 0x42, 0xd5,
        0xc4, 0x48, 0x4e, 0x0a, 0xbc, 0xd0, 0x6b, 0xfa, 0x53, 0xdd, 0xef,
        0x3c, 0x1b, 0x20, 0xee, 0x3f, 0xd5, 0x9d, 0x7c, 0x25, 0xe4, 0x1d,
        0x2b, 0x66, 0x9e, 0x1e, 0xf1, 0x6e, 0x6f, 0x52, 0xc3, 0x16, 0x4d,
        0xf4, 0xfb, 0x79, 0x30, 0xe9, 0xe4, 0xe5, 0x88, 0x57, 0xb6, 0xac,
        0x7d, 0x5f, 0x42, 0xd6, 0x9f, 0x6d, 0x18, 0x77, 0x63, 0xcf, 0x1d,
        0x55, 0x03, 0x40, 0x04, 0x87, 0xf5, 0x5b, 0xa5, 0x7e, 0x31, 0xcc,
        0x7a, 0x71, 0x35, 0xc8, 0x86, 0xef, 0xb4, 0x31, 0x8a, 0xed, 0x6a,
        0x1e, 0x01, 0x2d, 0x9e, 0x68, 0x32, 0xa9, 0x07, 0x60, 0x0a, 0x91,
        0x81, 0x30, 0xc4, 0x6d, 0xc7, 0x78, 0xf9, 0x71, 0xad, 0x00, 0x38,
        0x09, 0x29, 0x99, 0xa3, 0x33, 0xcb, 0x8b, 0x7a, 0x1a, 0x1d, 0xb9,
        0x3d, 0x71, 0x40, 0x00, 0x3c, 0x2a, 0x4e, 0xce, 0xa9, 0xf9, 0x8d,
        0x0a, 0xcc, 0x0a, 0x82, 0x91, 0xcd, 0xce, 0xc9, 0x7d, 0xcf, 0x8e,
        0xc9, 0xb5, 0x5a, 0x7f, 0x88, 0xa4, 0x6b, 0x4d, 0xb5, 0xa8, 0x51,
        0xf4, 0x41, 0x82, 0xe1, 0xc6, 0x8a, 0x00, 0x7e
};
 
/** Constant "pi" */
static const uint8_t pi[] = {
        0xc9, 0x0f, 0xda, 0xa2, 0x21, 0x68, 0xc2, 0x34, 0xc4, 0xc6, 0x62,
        0x8b, 0x80, 0xdc, 0x1c, 0xd1, 0x29, 0x02, 0x4e, 0x08, 0x8a, 0x67,
        0xcc, 0x74, 0x02, 0x0b, 0xbe, 0xa6, 0x3b, 0x13, 0x9b, 0x22, 0x51,
        0x4a, 0x08, 0x79, 0x8e, 0x34, 0x04, 0xdd, 0xef, 0x95, 0x19, 0xb3,
        0xcd, 0x3a, 0x43, 0x1b, 0x30, 0x2b, 0x0a, 0x6d, 0xf2, 0x5f, 0x14,
        0x37, 0x4f, 0xe1, 0x35, 0x6d, 0x6d, 0x51, 0xc2, 0x45, 0xe4, 0x85,
        0xb5, 0x76, 0x62, 0x5e, 0x7e, 0xc6, 0xf4, 0x4c, 0x42, 0xe9, 0xa6,
        0x37, 0xed, 0x6b, 0x0b, 0xff, 0x5c, 0xb6, 0xf4, 0x06, 0xb7, 0xed,
        0xee, 0x38, 0x6b, 0xfb, 0x5a, 0x89, 0x9f, 0xa5, 0xae, 0x9f, 0x24,
        0x11, 0x7c, 0x4b, 0x1f, 0xe6, 0x49, 0x28, 0x66, 0x51, 0xec, 0xe4,
        0x5b, 0x3d, 0xc2, 0x00, 0x7c, 0xb8, 0xa1, 0x63, 0xbf, 0x05, 0x98,
        0xda, 0x48, 0x36, 0x1c, 0x55, 0xd3, 0x9a, 0x69, 0x16, 0x3f, 0xa8,
        0xfd, 0x24, 0xcf, 0x5f, 0x83, 0x65, 0x5d, 0x23, 0xdc, 0xa3, 0xad,
        0x96, 0x1c, 0x62, 0xf3, 0x56, 0x20, 0x85, 0x52, 0xbb, 0x9e, 0xd5,
        0x29, 0x07, 0x70, 0x96, 0x96, 0x6d, 0x67, 0x0c, 0x35, 0x4e, 0x4a,
        0xbc, 0x98, 0x04, 0xf1, 0x74, 0x6c, 0x08, 0xca, 0x18, 0x21, 0x7c,
        0x32, 0x90, 0x5e, 0x46, 0x2e, 0x36, 0xce, 0x3b, 0xe3, 0x9e, 0x77,
        0x2c, 0x18, 0x0e, 0x86, 0x03, 0x9b, 0x27, 0x83, 0xa2, 0xec, 0x07,
        0xa2, 0x8f, 0xb5, 0xc5, 0x5d, 0xf0, 0x6f, 0x4c, 0x52, 0xc9, 0xde,
        0x2b, 0xcb, 0xf6, 0x95, 0x58, 0x17, 0x18, 0x39, 0x95, 0x49, 0x7c,
        0xea, 0x95, 0x6a, 0xe5, 0x15, 0xd2, 0x26, 0x18, 0x98, 0xfa, 0x05,
        0x10, 0x15, 0x72, 0x8e, 0x5a, 0x8a, 0xaa, 0xc4, 0x2d, 0xad, 0x33,
        0x17, 0x0d, 0x04, 0x50, 0x7a, 0x33, 0xa8, 0x55, 0x21, 0xab, 0xdf,
        0x1c, 0xba, 0x64, 0xec, 0xfb, 0x85, 0x04, 0x58, 0xdb, 0xef, 0x0a,
        0x8a, 0xea, 0x71, 0x57, 0x5d, 0x06, 0x0c, 0x7d, 0xb3, 0x97, 0x0f,
        0x85, 0xa6, 0xe1, 0xe4, 0xc7, 0xab, 0xf5, 0xae, 0x8c, 0xdb, 0x09,
        0x33, 0xd7, 0x1e, 0x8c, 0x94, 0xe0, 0x4a, 0x25, 0x61, 0x9d, 0xce,
        0xe3, 0xd2, 0x26, 0x1a, 0xd2, 0xee, 0x6b, 0xf1, 0x2f, 0xfa, 0x06,
        0xd9, 0x8a, 0x08, 0x64, 0xd8, 0x76, 0x02, 0x73, 0x3e, 0xc8, 0x6a,
        0x64, 0x52, 0x1f, 0x2b, 0x18, 0x17, 0x7b, 0x20, 0x0c, 0xbb, 0xe1,
        0x17, 0x57, 0x7a, 0x61, 0x5d, 0x6c, 0x77, 0x09, 0x88, 0xc0, 0xba,
        0xd9, 0x46, 0xe2, 0x08, 0xe2, 0x4f, 0xa0, 0x74, 0xe5, 0xab, 0x31,
        0x43, 0xdb, 0x5b, 0xfc, 0xe0, 0xfd, 0x10, 0x8e, 0x4b, 0x82, 0xd1,
        0x20, 0xa9, 0x21, 0x08, 0x01, 0x1a, 0x72, 0x3c, 0x12, 0xa7, 0x87,
        0xe6, 0xd7, 0x88, 0x71, 0x9a, 0x10, 0xbd, 0xba, 0x5b, 0x26, 0x99,
        0xc3, 0x27, 0x18, 0x6a, 0xf4, 0xe2, 0x3c, 0x1a, 0x94, 0x68, 0x34,
        0xb6, 0x15, 0x0b, 0xda, 0x25, 0x83, 0xe9, 0xca, 0x2a, 0xd4, 0x4c,
        0xe8, 0xdb, 0xbb, 0xc2, 0xdb, 0x04, 0xde, 0x8e, 0xf9, 0x2e, 0x8e,
        0xfc, 0x14, 0x1f, 0xbe, 0xca, 0xa6, 0x28, 0x7c, 0x59, 0x47, 0x4e,
        0x6b, 0xc0, 0x5d, 0x99, 0xb2, 0x96, 0x4f, 0xa0, 0x90, 0xc3, 0xa2,
        0x23, 0x3b, 0xa1, 0x86, 0x51, 0x5b, 0xe7, 0xed, 0x1f, 0x61, 0x29,
        0x70, 0xce, 0xe2, 0xd7, 0xaf, 0xb8, 0x1b, 0xdd, 0x76, 0x21, 0x70,
        0x48, 0x1c, 0xd0, 0x06, 0x91, 0x27, 0xd5, 0xb0, 0x5a, 0xa9, 0x93,
        0xb4, 0xea, 0x98, 0x8d, 0x8f, 0xdd, 0xc1, 0x86, 0xff, 0xb7, 0xdc,
        0x90, 0xa6, 0xc0, 0x8f, 0x4d, 0xf4, 0x35, 0xc9
};
 
/**
 * Calculate FFDHE result
 *
 * @v group             FFDHE group
 * @v public            Base public value, or NULL to use generator
 * @v private           Private exponent
 * @v shared            Shared result to fill in
 * @ret rc              Return status code
 */
static int ffdhe ( struct ffdhe_group *group, const void *public,
                   const void *private, void *shared ) {
        unsigned int expsize = group->expsize;
        unsigned int size = group->size;
        size_t explen = group->explen;
        size_t len = group->len;
        bigint_t ( expsize ) exponent;
        bigint_t ( size ) *modulus;
        bigint_t ( size ) *base;
        bigint_t ( size ) *result;
        ffdhe_modulus_t ( len ) *raw;
        struct {
                typeof ( *modulus ) modulus;
                typeof ( *base ) base;
                typeof ( *result ) result;
                uint8_t mod_exp[ bigint_mod_exp_tmp_len ( modulus ) ];
        } *tmp;
        static const uint8_t two[1] = { 2 };
        int rc;
 
        /* Sanity checks */
        static_assert ( sizeof ( euler ) == FFDHE_CONSTANT_LEN );
        static_assert ( sizeof ( pi ) == FFDHE_CONSTANT_LEN );
 
        /* Allocate temporary space */
        tmp = malloc ( sizeof ( *tmp ) );
        if ( ! tmp ) {
                rc = -ENOMEM;
                goto err_alloc;
        }
        modulus = &tmp->modulus;
        base = &tmp->base;
        result = &tmp->result;
 
        /* Construct modulus (using base as temporary buffer) */
        assert ( sizeof ( *raw ) <= sizeof ( *base ) );
        raw = ( ( void * ) base );
        memset ( raw, 0xff, sizeof ( *raw ) );
        memcpy ( raw->constant, group->constant, sizeof ( raw->constant ) );
        raw->lsb32 = group->lsb32;
        bigint_init ( modulus, raw, len );
        DBGC ( group, "FFDHE %s mod: %s\n",
               group->name, bigint_ntoa ( modulus ) );
 
        /* Construct base */
        if ( public ) {
                bigint_init ( base, public, len );
        } else {
                bigint_init ( base, two, sizeof ( two ) );
        }
        DBGC ( group, "FFDHE %s %s: %s\n", group->name,
               ( public ? "pub" : "gen" ), bigint_ntoa ( base ) );
 
        /* Construct exponent */
        bigint_init ( &exponent, private, explen );
        DBGC ( group, "FFDHE %s exp: %s\n",
               group->name, bigint_ntoa ( &exponent ) );
 
        /* Calculate result */
        bigint_mod_exp ( base, modulus, &exponent, result, tmp->mod_exp );
        DBGC ( group, "FFDHE %s %s: %s\n", group->name,
               ( public ? "shr" : "pub" ), bigint_ntoa ( result ) );
        bigint_done ( result, shared, len );
 
        /* Validate result */
        bigint_init ( base, two, sizeof ( two ) );
        if ( ! bigint_is_geq ( result, base ) ) {
                /* Result is 0 or 1 */
                DBGC ( group, "FFDHE %s invalid result\n", group->name );
                rc = -EPERM;
                goto err_result;
        }
        bigint_add ( base, result );
        if ( ! bigint_is_geq ( modulus, result ) ) {
                /* Result is p-1 */
                DBGC ( group, "FFDHE %s invalid result\n", group->name );
                rc = -EPERM;
                goto err_result;
        }
 
        /* Success */
        rc = 0;
 
 err_result:
        zfree ( tmp );
 err_alloc:
        return rc;
}
 
/**
 * Share public key
 *
 * @v exchange          Key exchange algorithm
 * @v private           Private key
 * @v public            Public key to fill in
 * @ret rc              Return status code
 */
int ffdhe_share ( struct exchange_algorithm *exchange, const void *private,
                  void *public ) {
        struct ffdhe_group *group = exchange->priv;
 
        return ffdhe ( group, NULL, private, public );
}
 
/**
 * Agree shared secret
 *
 * @v exchange          Key exchange algorithm
 * @v private           Private key
 * @v partner           Partner public key
 * @v shared            Shared secret to fill in
 * @ret rc              Return status code
 */
int ffdhe_agree ( struct exchange_algorithm *exchange, const void *private,
                  const void *partner, void *shared ) {
        struct ffdhe_group *group = exchange->priv;
 
        return ffdhe ( group, partner, private, shared );
}
 
/**
 * Check group parameters
 *
 * @v exchange          Key exchange algorithm
 * @v dh_p              Prime modulus
 * @v dh_p_len          Length of prime modulus
 * @v dh_g              Generator
 * @v dh_g_len          Length of generator
 * @ret match           Field parameters are correct for this group
 *
 * Leading zeros in the modulus and generator will be tolerated.
 */
int ffdhe_has_params ( struct exchange_algorithm *exchange,
                       const void *dh_p, size_t dh_p_len,
                       const void *dh_g, size_t dh_g_len ) {
        struct ffdhe_group *group = exchange->priv;
        const ffdhe_modulus_t ( group->len ) *modulus;
        const uint8_t *generator;
 
        /* Sanity check */
        assert ( is_ffdhe ( exchange ) );
 
        /* Strip leading zeros from modulus and check length */
        while ( dh_p_len && ( ! *( ( uint8_t * ) dh_p ) ) ) {
                dh_p++;
                dh_p_len--;
        }
        if ( dh_p_len != sizeof ( *modulus ) )
                return 0;
        modulus = dh_p;
 
        /* Strip leading zeros from generator and check length */
        while ( dh_g_len && ( ! *( ( uint8_t * ) dh_g ) ) ) {
                dh_g++;
                dh_g_len--;
        }
        if ( dh_g_len != sizeof ( *generator ) )
                return 0;
        generator = dh_g;
 
        /* Check values */
        return ( ( modulus->high == ~( ( uint64_t ) 0 ) ) &&
                 ( memcmp ( modulus->constant, group->constant,
                            sizeof ( modulus->constant ) ) == 0 ) &&
                 ( modulus->lsb32 == group->lsb32 ) &&
                 ( modulus->low == ~( ( uint64_t ) 0 ) ) &&
                 ( *generator == 2 ) );
}
 
/* Supported groups */
FFDHE_GROUP ( ffdhe2048, ffdhe2048_algorithm, euler, 2048, 225, 0x61285c97 );
FFDHE_GROUP ( ffdhe3072, ffdhe3072_algorithm, euler, 3072, 275, 0x66c62e37 );
FFDHE_GROUP ( ffdhe4096, ffdhe4096_algorithm, euler, 4096, 325, 0x5e655f6a );
FFDHE_GROUP ( modp2048, modp2048_algorithm, pi, 2048, 230, 0x8aacaa68 );
FFDHE_GROUP ( modp3072, modp3072_algorithm, pi, 3072, 279, 0xa93ad2ca );
FFDHE_GROUP ( modp4096, modp4096_algorithm, pi, 4096, 328, 0x34063199 );