# 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.

Variables

const unsigned XEDDSA_VERSION_MAJOR

const unsigned XEDDSA_VERSION_MINOR

const unsigned XEDDSA_VERSION_REVISION