Elliptic curve operations with the NIST P-521 curve. More...

#include <P521.h>

Static Public Member Functions
static bool	eval (uint8_t result[132], const uint8_t f[66], const uint8_t point[132])
	Evaluates the curve function. More...

static void	dh1 (uint8_t k[132], uint8_t f[66])
	Performs phase 1 of an ECDH key exchange using P-521. More...

static bool	dh2 (const uint8_t k[132], uint8_t f[66])
	Performs phase 2 of an ECDH key exchange using P-521. More...

static void	sign (uint8_t signature[132], const uint8_t privateKey[66], const void message, size_t len, Hash hash=0)
	Signs a message using a specific P-521 private key. More...

static bool	verify (const uint8_t signature[132], const uint8_t publicKey[132], const void message, size_t len, Hash hash=0)
	Verifies a signature using a specific P-521 public key. More...

static void	generatePrivateKey (uint8_t privateKey[66])
	Generates a private key for P-521 signing operations. More...

static void	derivePublicKey (uint8_t publicKey[132], const uint8_t privateKey[66])
	Derives the public key from a private key for P-521 signing operations. More...

static bool	isValidPrivateKey (const uint8_t privateKey[66])
	Validates a private key value to ensure that it is between 1 and q - 1. More...

static bool	isValidPublicKey (const uint8_t publicKey[132])
	Validates a public key to ensure that it is a valid curve point. More...

static bool	isValidCurvePoint (const uint8_t point[132])
	Validates a point to ensure that it is on the curve. More...

Detailed Description

Elliptic curve operations with the NIST P-521 curve.

This class supports both ECDH key exchange and ECDSA signatures.

Note: The public functions in this class need a substantial amount of stack space to store intermediate results while the curve function is being evaluated. About 2k of free stack space is recommended for safety.

References: NIST FIPS 186-4, RFC 6090, RFC 6979, RFC 5903

See also: Curve25519

Definition at line 30 of file P521.h.

Member Function Documentation

◆ derivePublicKey()

void P521::derivePublicKey	(	uint8_t	publicKey[132],
		const uint8_t	privateKey[66]
	)

static

Derives the public key from a private key for P-521 signing operations.

Parameters

publicKey	The public key.
privateKey	The private key, which is assumed to have been created by generatePrivateKey().

See also: generatePrivateKey(), verify()

Definition at line 497 of file P521.cpp.

◆ dh1()

void P521::dh1	(	uint8_t	k[132],
		uint8_t	f[66]
	)

static

Performs phase 1 of an ECDH key exchange using P-521.

Parameters

k	The key value to send to the other party as part of the exchange.
f	The generated secret value for this party. This must not be transmitted to any party or stored in permanent storage. It only needs to be kept in memory until dh2() is called.

The f value is generated with RNG.rand(). It is the caller's responsibility to ensure that the global random number pool has sufficient entropy to generate the 66 bytes of f safely before calling this function.

The following example demonstrates how to perform a full ECDH key exchange using dh1() and dh2():

uint8_t f[66];
uint8_t k[132];
 
// Generate the secret value "f" and the public value "k".
P521::dh1(k, f);
 
// Send "k" to the other party.
...
 
// Read the "k" value that the other party sent to us.
...
 
// Generate the shared secret in "f".
if (!P521::dh2(k, f)) {
    // The received "k" value was invalid - abort the session.
    ...
}
 
// The "f" value can now be used to generate session keys for encryption.
...

Reference: RFC 6090

See also: dh2()

Definition at line 208 of file P521.cpp.

◆ dh2()

bool P521::dh2	(	const uint8_t	k[132],
		uint8_t	f[66]
	)

static

Performs phase 2 of an ECDH key exchange using P-521.

Parameters

k	The public key value that was received from the other party as part of the exchange.
f	On entry, this is the secret value for this party that was generated by dh1(). On exit, this will be the shared secret.

Returns: Returns true if the key exchange was successful, or false if the k value is invalid.

Reference: RFC 6090

See also: dh1()

Definition at line 229 of file P521.cpp.

◆ eval()

bool P521::eval	(	uint8_t	result[132],
		const uint8_t	f[66],
		const uint8_t	point[132]
	)

static

Evaluates the curve function.

Parameters

result	The result of applying the curve function, which consists of the x and y values of the result point encoded in big-endian order.
f	The scalar value to multiply by point to create the result. This is assumed to be be a 521-bit number in big-endian order.
point	The curve point to multiply consisting of the x and y values encoded in big-endian order. If point is NULL, then the generator Gx and Gy values for the curve will be used instead.

Returns: Returns true if f * point could be evaluated, or false if point is not a point on the curve.

This function provides access to the raw curve operation for testing purposes. Normally an application would use a higher-level function like dh1(), dh2(), sign(), or verify().

See also: dh1(), sign()

Definition at line 135 of file P521.cpp.

◆ generatePrivateKey()

void P521::generatePrivateKey ( uint8_t privateKey[66] )

static

Generates a private key for P-521 signing operations.

Parameters

privateKey The resulting private key.

The private key is generated with RNG.rand(). It is the caller's responsibility to ensure that the global random number pool has sufficient entropy to generate the 521 bits of the key safely before calling this function.

See also: derivePublicKey(), sign()

Definition at line 466 of file P521.cpp.

◆ isValidCurvePoint()

bool P521::isValidCurvePoint ( const uint8_t point[132] )

inlinestatic

Validates a point to ensure that it is on the curve.

Parameters

point The point to validate.

Returns: Returns true if point is valid and on the curve, false if not.

This is a convenience function that calls isValidPublicKey() as the two operations are equivalent.

Definition at line 51 of file P521.h.

◆ isValidPrivateKey()

bool P521::isValidPrivateKey ( const uint8_t privateKey[66] )

static

Validates a private key value to ensure that it is between 1 and q - 1.

Parameters

privateKey The private key value to validate.

Returns: Returns true if privateKey is valid, false if not.

See also: isValidPublicKey()

Definition at line 524 of file P521.cpp.

◆ isValidPublicKey()

bool P521::isValidPublicKey ( const uint8_t publicKey[132] )

static

Validates a public key to ensure that it is a valid curve point.

Parameters

publicKey The public key value to validate.

Returns: Returns true if publicKey is valid, false if not.

See also: isValidPrivateKey()

Definition at line 564 of file P521.cpp.

◆ sign()

void P521::sign	(	uint8_t	signature[132],
		const uint8_t	privateKey[66],
		const void *	message,
		size_t	len,
		Hash *	hash = `0`
	)

static

Signs a message using a specific P-521 private key.

Parameters

signature	The signature value.
privateKey	The private key to use to sign the message.
message	Points to the message to be signed.
len	The length of the message to be signed.
hash	The hash algorithm to use to hash the message before signing. If hash is NULL, then the message is assumed to already be a hash value from some previous process.

This function generates deterministic ECDSA signatures according to RFC 6979. The hash function is used to generate the k value for the signature. If hash is NULL, then SHA512 is used. The hash object must be capable of HMAC mode.

The length of the hashed message must be less than or equal to 64 bytes in size. Longer messages will be truncated to 64 bytes.

References: RFC 6090, RFC 6979

See also: verify(), generatePrivateKey()

Definition at line 276 of file P521.cpp.

◆ verify()

bool P521::verify	(	const uint8_t	signature[132],
		const uint8_t	publicKey[132],
		const void *	message,
		size_t	len,
		Hash *	hash = `0`
	)

static

Verifies a signature using a specific P-521 public key.

Parameters

signature	The signature value to be verified.
publicKey	The public key to use to verify the signature.
message	The message whose signature is to be verified.
len	The length of the message to be verified.
hash	The hash algorithm to use to hash the message before verification. If hash is NULL, then the message is assumed to already be a hash value from some previous process.

The length of the hashed message must be less than or equal to 64 bytes in size. Longer messages will be truncated to 64 bytes.

Returns: Returns true if the signature is valid for message; or false if the publicKey or signature is not valid.

See also: sign()

Definition at line 373 of file P521.cpp.

The documentation for this class was generated from the following files:

Static Public Member Functions

Detailed Description

Member Function Documentation

◆ derivePublicKey()

◆ dh1()

◆ dh2()

◆ eval()

◆ generatePrivateKey()

◆ isValidCurvePoint()

◆ isValidPrivateKey()

◆ isValidPublicKey()

◆ sign()

◆ verify()