xeddsa.h
Formats
The library follows following standards for serialization formats:
Curve25519/Ed25519 private keys: 32 bytes scalar value. No specific format. Clamped before every use as per RFC 7748, section 5 “The X25519 and X448 Functions”.
Curve25519/Ed25519 seeds: 32 bytes. No specific format. The private key is derived from the seed using SHA-512 as per RFC 8032, section 3.2 “Keys”.
Curve25519 public keys: 32 bytes, the little-endian encoding of the u coordinate as per RFC 7748, section 5 “The X25519 and X448 Functions”.
Ed25519 public keys: 32 bytes, the little-endian encoding of the y coordinate with the sign bit of the x coordinate stored in the most significant bit as per RFC 8032, section 3.2 “Keys”.
Ed25519 signatures: 64 bytes, following the format defined in RFC 8032, section 3.3 “Sign”.
API
Functions
-
void INTERFACE ed25519_priv_sign(uint8_t*, const uint8_t*, const uint8_t*, const uint32_t, const uint8_t*)
Sign a message using a Curve25519/Ed25519 private key.
- Parameters:
sig – (out): An Ed25519-compatible signature of
msg
.priv – (in): The Curve25519/Ed25519 private key to sign with.
msg – (in): The message to sign.
msg_size – (in): Size of the message to sign, in bytes.
nonce – (in): 64 bytes of secure random data.
-
void INTERFACE ed25519_seed_sign(uint8_t*, const uint8_t*, const uint8_t*, const uint32_t)
Sign a message using a Curve25519/Ed25519 seed.
- Parameters:
sig – (out): An Ed25519-compatible signature of
msg
.seed – (in): The Curve25519/Ed25519 seed to sign with.
msg – (in): The message to sign.
msg_size – (in): Size of the message to sign, in bytes.
-
int INTERFACE ed25519_verify(const uint8_t*, const uint8_t*, const uint8_t*, const uint32_t)
Verify an Ed25519 signature.
- Parameters:
sig – (in): An Ed25519-compatible signature of
msg
.ed25519_pub – (in): The Ed25519 public key to verify the signature with.
msg – (in): The message.
msg_size – (in): Size of the message, in bytes.
- Returns:
0 in case of success, -1 if the verification fails.
-
void INTERFACE curve25519_pub_to_ed25519_pub(uint8_t*, const uint8_t*, const bool)
Convert a Curve25519 public key into an Ed25519 public key.
- Parameters:
ed25519_pub – (out): The Ed25519 public key corresponding to the Curve25519 public key.
curve25519_pub – (in): The Curve25519 public key to convert into its Ed25519 equivalent.
set_sign_bit – Whether to set the sign bit of the output Ed25519 public key.
-
int INTERFACE ed25519_pub_to_curve25519_pub(uint8_t*, const uint8_t*)
Convert an Ed25519 public key into a Curve25519 public key. Re-export of libsodiums/ref10s
crypto_sign_ed25519_pk_to_curve25519
function for convenience.- Parameters:
curve25519_pub – (out): The Curve25519 public key corresponding to the Ed25519 public key.
ed25519_pub – (in): The Ed25519 public key to convert into its Curve25519 equivalent.
- Returns:
0 on success, -1 if the public key was rejected due to suboptimal security propierties.
-
void INTERFACE priv_to_curve25519_pub(uint8_t*, const uint8_t*)
Derive the Curve25519 public key from a Curve25519/Ed25519 private key.
- Parameters:
curve25519_pub – (out): The Curve25519 public key.
priv – (in): The Curve25519/Ed25519 private key.
-
void INTERFACE priv_to_ed25519_pub(uint8_t*, const uint8_t*)
Derive the Ed25519 public key from a Curve25519/Ed25519 private key.
- Parameters:
ed25519_pub – (out): The Ed25519 public key.
priv – (in): The Curve25519/Ed25519 private key.
-
void INTERFACE seed_to_ed25519_pub(uint8_t*, const uint8_t*)
Derive the Ed25519 public key from a Curve25519/Ed25519 seed.
- Parameters:
ed25519_pub – (out): The Ed25519 public key.
seed – (in): The Curve25519/Ed25519 seed.
-
void INTERFACE priv_force_sign(uint8_t*, const uint8_t*, const bool)
Negate a Curve25519/Ed25519 private key if necessary, such that the corresponding Ed25519 public key has the sign bit set (or not set) as requested.
- Parameters:
priv_out – (out): The adjusted Curve25519/Ed25519 private key.
priv_in – (in): The original Curve25519/Ed25519 private key.
set_sign_bit – Whether the goal is for the sign bit to be set on the Ed25519 public key corresponding to the adjusted Curve25519/Ed25519 private key.
-
void INTERFACE seed_to_priv(uint8_t*, const uint8_t*)
Derive the Curve25519/Ed25519 private key from a Curve25519/Ed25519 seed. Re-export of libsodiums/ref10s
crypto_sign_ed25519_sk_to_curve25519
function for convenience.- Parameters:
priv – (out): The Curve25519/Ed25519 private key derived from the seed.
seed – (in): The Curve25519/Ed25519 seed.
-
int INTERFACE x25519(uint8_t*, const uint8_t*, const uint8_t*)
Perform Diffie-Hellman key agreement on Curve25519, also known as X25519. Re-export of libsodiums/ref10s
crypto_scalarmult_curve25519
function for convenience.- Parameters:
shared_secret – (out): The shared secret.
priv – (in): The private key partaking in the key agreement.
curve25519_pub – (in): The public key partaking in the key agreement.
- Returns:
0 in case of success, -1 if the public key was rejected due to suboptimal security propierties or if the shared secret consists of only zeros.
-
int INTERFACE xeddsa_init()
Initializes the library and its dependencies. Has to be called at least once before using and of the other functions. Can be called multiple times, even from different threads.
- Returns:
0 if the library was initialized, 1 if the library was already initialized and -1 in case of an error.