P-256

Key-agreement over the P-256 NIST curve.

For key-conversion functions related to P-256 see the P-256 ECDSA section.

API Reference

Example

#define HACL_DH_P256_SECRETKEY_LEN 32
#define HACL_DH_P256_PUBLICKEY_LEN 64
#define HACL_DH_P256_SHARED_LEN 64

// Alice and Bob want to agree on a shared secret via X25519.

// Thus, Alice needs a secret and public key ...
uint8_t alice_sk[HACL_DH_P256_SECRETKEY_LEN];
uint8_t alice_pk[HACL_DH_P256_PUBLICKEY_LEN];
// Note: This function is not in HACL*.
//       You need to bring your own random.
generate_p256_keypair(alice_sk, alice_pk);

// ... and Bob does as well.
uint8_t bob_sk[HACL_DH_P256_SECRETKEY_LEN];
uint8_t bob_pk[HACL_DH_P256_PUBLICKEY_LEN];
// Note: This function is not in HACL*.
//       You need to bring your own random.
generate_p256_keypair(bob_sk, bob_pk);

// Now, Alice and Bob exchange their public keys so that
// Alice can compute her shared secret as ...
uint8_t shared_alice[HACL_DH_P256_SHARED_LEN];
bool res_alice = Hacl_P256_dh_responder(shared_alice, bob_pk, alice_sk);

// ... and Bob can compute his shared secret as ...
uint8_t shared_bob[HACL_DH_P256_SHARED_LEN];
bool res_bob = Hacl_P256_dh_responder(shared_bob, alice_pk, bob_sk);

// Now, both Alice and Bob should share the same secret value, i.e.,
//
//     `shared_alice` == `shared_bob`
//
// ... and can use this to derive, e.g., an encryption key.

bool Hacl_P256_dh_initiator(uint8_t *public_key, uint8_t *private_key)

Compute the public key from the private key.

The function returns true if a private key is valid and false otherwise.

The outparam public_key points to 64 bytes of valid memory, i.e., uint8_t[64]. The argument private_key points to 32 bytes of valid memory, i.e., uint8_t[32].

The private key is valid: • 0 < private_key < the order of the curve.

bool Hacl_P256_dh_responder(uint8_t *shared_secret, uint8_t *their_pubkey, uint8_t *private_key)

Execute the diffie-hellmann key exchange.

The function returns true for successful creation of an ECDH shared secret and false otherwise.

The outparam shared_secret points to 64 bytes of valid memory, i.e., uint8_t[64]. The argument their_pubkey points to 64 bytes of valid memory, i.e., uint8_t[64]. The argument private_key points to 32 bytes of valid memory, i.e., uint8_t[32].

The function also checks whether private_key and their_pubkey are valid.