Arduino Cryptography Library
Static Public Member Functions | List of all members
P521 Class Reference

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
publicKeyThe public key.
privateKeyThe 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
kThe key value to send to the other party as part of the exchange.
fThe 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.
...
static bool dh2(const uint8_t k[132], uint8_t f[66])
Performs phase 2 of an ECDH key exchange using P-521.
Definition: P521.cpp:229
static void dh1(uint8_t k[132], uint8_t f[66])
Performs phase 1 of an ECDH key exchange using P-521.
Definition: P521.cpp:208

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
kThe public key value that was received from the other party as part of the exchange.
fOn 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
resultThe result of applying the curve function, which consists of the x and y values of the result point encoded in big-endian order.
fThe scalar value to multiply by point to create the result. This is assumed to be be a 521-bit number in big-endian order.
pointThe 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
privateKeyThe 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
pointThe 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
privateKeyThe 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
publicKeyThe 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
signatureThe signature value.
privateKeyThe private key to use to sign the message.
messagePoints to the message to be signed.
lenThe length of the message to be signed.
hashThe 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
signatureThe signature value to be verified.
publicKeyThe public key to use to verify the signature.
messageThe message whose signature is to be verified.
lenThe length of the message to be verified.
hashThe 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: