EdDSA

HACL Packages provides the Ed25519 instantiation of EdDSA, i.e., EdDSA signing and verification on the edwards25519 curve.

Two APIs are exposed: A (simple) “One-Shot” API to sign/verify a single message and a (more efficient) “Precomputed” API to sign multiple messages under the same (precomputed) key.

API Reference

void Hacl_Ed25519_secret_to_public(uint8_t *public_key, uint8_t *private_key)

Compute the public key from the private key.

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

One-Shot

Example

#define HACL_SIGNATURE_ED25519_SECRETKEY_LEN 32
#define HACL_SIGNATURE_ED25519_SECRETKEY_PRECOMP_LEN 96
#define HACL_SIGNATURE_ED25519_PUBLICKEY_LEN 32
#define HACL_SIGNATURE_ED25519_SIGNATURE_LEN 64

// In this example, we create a signature key pair, sign a message, and
// verify the generated signature.

// First, we create a signature key pair.
// Note: HACL does not have a random number generator yet:
//
//         https://github.com/hacl-star/hacl-star/issues/26
//
//       The `generate_random` function is only used as an
//       example, and you must bring your own random.
// 1) Create a secret key.
uint8_t sk[HACL_SIGNATURE_ED25519_SECRETKEY_LEN];
generate_random(sk, HACL_SIGNATURE_ED25519_SECRETKEY_LEN);

// 2) Derive a public key from the secret key.
uint8_t pk[HACL_SIGNATURE_ED25519_PUBLICKEY_LEN];
Hacl_Ed25519_secret_to_public(pk, sk);

// Then, we can sign a message.
// 1) Create a message and allocate memory for the signature.
uint8_t msg[123];
generate_random(msg, 123);

uint8_t signature[HACL_SIGNATURE_ED25519_SIGNATURE_LEN];

// 2) Sign the message with the private key.
Hacl_Ed25519_sign(signature, sk, 123, msg);

// Finally, we can verify the signature we just created by using the public
// key.
bool result = Hacl_Ed25519_verify(pk, 123, msg, signature);

if (result) {
  printf("Yay, signature was valid!");
} else {
  printf("Naaay, that should not have happened with the code above.");
}

void Hacl_Ed25519_sign(uint8_t *signature, uint8_t *private_key, uint32_t msg_len, uint8_t *msg)

Create an Ed25519 signature.

The outparam signature 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 argument msg points to msg_len bytes of valid memory, i.e., uint8_t[msg_len].

The function first calls expand_keys and then invokes sign_expanded.

If one needs to sign several messages under the same private key, it is more efficient to call expand_keys only once and sign_expanded multiple times, for each message.

bool Hacl_Ed25519_verify(uint8_t *public_key, uint32_t msg_len, uint8_t *msg, uint8_t *signature)

Verify an Ed25519 signature.

The function returns true if the signature is valid and false otherwise.

The argument public_key points to 32 bytes of valid memory, i.e., uint8_t[32]. The argument msg points to msg_len bytes of valid memory, i.e., uint8_t[msg_len]. The argument signature points to 64 bytes of valid memory, i.e., uint8_t[64].

Precomputed

Example

#define HACL_SIGNATURE_ED25519_SECRETKEY_LEN 32
#define HACL_SIGNATURE_ED25519_SECRETKEY_PRECOMP_LEN 96
#define HACL_SIGNATURE_ED25519_PUBLICKEY_LEN 32
#define HACL_SIGNATURE_ED25519_SIGNATURE_LEN 64

// In this example, we use the precomputed API to create multiple signatures
// more efficiently.

// First, we create our signature private key.
// Note: HACL does not have a random number generator yet:
//
//         https://github.com/hacl-star/hacl-star/issues/26
//
//       The `generate_random` function is only used as an
//       example, and you must bring your own random.
uint8_t sk[HACL_SIGNATURE_ED25519_SECRETKEY_LEN];
generate_random(sk, HACL_SIGNATURE_ED25519_SECRETKEY_LEN);

// Then, we precompute an intermediate key that will be used for signing.
uint8_t sk_exp[HACL_SIGNATURE_ED25519_SECRETKEY_PRECOMP_LEN];
Hacl_Ed25519_expand_keys(sk_exp, sk);

// Finally, we use the precomputed key to sign (multiple) messages.
uint8_t msg_1[1337];
generate_random(msg_1, 1337);
uint8_t msg_2[42];
generate_random(msg_2, 42);

uint8_t signature_1[HACL_SIGNATURE_ED25519_SIGNATURE_LEN];
uint8_t signature_2[HACL_SIGNATURE_ED25519_SIGNATURE_LEN];

Hacl_Ed25519_sign_expanded(signature_1, sk_exp, 1337, msg_1);
Hacl_Ed25519_sign_expanded(signature_2, sk_exp, 42, msg_2);

void Hacl_Ed25519_expand_keys(uint8_t *expanded_keys, uint8_t *private_key)

Compute the expanded keys for an Ed25519 signature.

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

If one needs to sign several messages under the same private key, it is more efficient to call expand_keys only once and sign_expanded multiple times, for each message.

void Hacl_Ed25519_sign_expanded(uint8_t *signature, uint8_t *expanded_keys, uint32_t msg_len, uint8_t *msg)

Create an Ed25519 signature with the (precomputed) expanded keys.

The outparam signature points to 64 bytes of valid memory, i.e., uint8_t[64]. The argument expanded_keys points to 96 bytes of valid memory, i.e., uint8_t[96]. The argument msg points to msg_len bytes of valid memory, i.e., uint8_t[msg_len].

The argument expanded_keys is obtained through expand_keys.

If one needs to sign several messages under the same private key, it is more efficient to call expand_keys only once and sign_expanded multiple times, for each message.