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

#include <stdint.h>
#include <errno.h>
#include <ipxe/ffdhe.h>

/** Euler's number ("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
};

/** FFDHE non-Euler length */
#define FFDHE_PAD_LEN ( 8 /* high */ + 4 /* lsb32 */ + 8 /* low */ )

/** An FFDHE prime modulus */
#define ffdhe_modulus_t( len )						\
	struct {							\
		uint64_t high;						\
		uint8_t euler[ len - FFDHE_PAD_LEN ];			\
		uint32_t lsb32;						\
		uint64_t low;						\
	} __attribute__ (( packed ))

/** Maximum length of big integer values */
#define FFDHE_LEN ( sizeof ( euler ) + FFDHE_PAD_LEN )

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

	/* Construct modulus */
	assert ( sizeof ( *tmp ) == len );
	memset ( tmp, 0xff, sizeof ( *tmp ) );
	memcpy ( tmp->euler, euler, sizeof ( tmp->euler ) );
	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;
}

/* Supported groups */
FFDHE_GROUP ( ffdhe2048, ffdhe2048_algorithm, 2048, 225, 0x61285c97 );
FFDHE_GROUP ( ffdhe3072, ffdhe3072_algorithm, 3072, 275, 0x66c62e37 );
FFDHE_GROUP ( ffdhe4096, ffdhe4096_algorithm, 4096, 325, 0x5e655f6a );