src/crypto/ffdhe.c

/*
 * 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 <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
};

/** Maximum number of elements in big integer values */
#define FFDHE_SIZE bigint_required_size ( FFDHE_LEN )

/** Maximally sized big integer */
typedef bigint_t ( FFDHE_SIZE ) ffdhe_t;

/** Temporary storage */
static struct {
	/** Prime modulus */
	ffdhe_t modulus;
	/** Base */
	ffdhe_t base;
	/** Result */
	ffdhe_t result;
	/** Temporary working space */
	union {
		uint8_t mod_exp[ bigint_mod_exp_tmp_len ( (ffdhe_t *) NULL ) ];
		uint8_t raw[FFDHE_LEN];
	} tmp;
} ffdhe_temp;

/**
 * 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;
	ffdhe_modulus_t ( len ) *tmp = ( ( void * ) &ffdhe_temp.tmp );
	bigint_t ( size ) *modulus = ( ( void * ) &ffdhe_temp.modulus );
	bigint_t ( size ) *base = ( ( void * ) &ffdhe_temp.base );
	bigint_t ( size ) *result = ( ( void * ) &ffdhe_temp.result );
	bigint_t ( expsize ) exponent;
	static const uint8_t two[1] = { 2 };

	/* Sanity checks */
	static_assert ( sizeof ( euler ) == FFDHE_CONSTANT_LEN );
	static_assert ( sizeof ( pi ) == FFDHE_CONSTANT_LEN );

	/* Construct modulus */
	assert ( sizeof ( *tmp ) == len );
	memset ( tmp, 0xff, sizeof ( *tmp ) );
	memcpy ( tmp->constant, group->constant, sizeof ( tmp->constant ) );
	tmp->lsb32 = group->lsb32;
	bigint_init ( modulus, tmp, 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, &ffdhe_temp.tmp );
	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 );
		return -EPERM;
	}
	bigint_add ( base, result );
	if ( ! bigint_is_geq ( modulus, result ) ) {
		/* Result is p-1 */
		DBGC ( group, "FFDHE %s invalid result\n", group->name );
		return -EPERM;
	}

	return 0;
}

/**
 * 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 );