-rw-r--r-- 4413 lib25519-20221222/hdoc raw
/*

The stable lib25519 API consists of the following five functions. Other
functions defined in lib25519.h (e.g., functions used for internal tests
and benchmarks) may change.

All of these functions follow the SUPERCOP/NaCl API except that (1)
function names are lib25519-specific, (2) message lengths are long long
instead of unsigned long long, and (3) all functions except signature
verification return void instead of int.

1. X25519 key generation:

     #include "lib25519.h"

     unsigned char pk[lib25519_dh_PUBLICKEYBYTES];
     unsigned char sk[lib25519_dh_SECRETKEYBYTES];

     lib25519_dh_keypair(pk,sk);

This function randomly generates Alice's secret key sk[0], sk[1], ...,
sk[lib25519_dh_SECRETKEYBYTES-1] and Alice's corresponding public key
pk[0], pk[1], ..., pk[lib25519_dh_PUBLICKEYBYTES-1].

lib25519_dh_PUBLICKEYBYTES and lib25519_dh_SECRETKEYBYTES are guaranteed
to be 32, but callers wishing to allow easy substitution of other DH
systems should not rely on this guarantee.

2. X25519 shared-secret generation:

     #include "lib25519.h"

     unsigned char k[lib25519_dh_BYTES];
     unsigned char pk[lib25519_dh_PUBLICKEYBYTES];
     unsigned char sk[lib25519_dh_SECRETKEYBYTES];

     lib25519_dh(k,pk,sk);

This function computes the X25519 secret k[0], k[1], ...,
k[lib25519_dh_BYTES-1] shared between Alice and Bob, given Bob's public
key pk[0], pk[1], ..., pk[lib25519_dh_PUBLICKEYBYTES-1] and Alice's
secret key sk[0], sk[1], ..., sk[lib25519_dh_SECRETKEYBYTES-1].

lib25519_dh_PUBLICKEYBYTES, lib25519_dh_SECRETKEYBYTES, and
lib25519_dh_BYTES are guaranteed to be 32, but callers wishing to allow
easy substitution of other DH systems should not rely on this guarantee.

3. Ed25519 key generation:

     #include "lib25519.h"

     unsigned char pk[lib25519_sign_PUBLICKEYBYTES];
     unsigned char sk[lib25519_sign_SECRETKEYBYTES];

     lib25519_sign_keypair(pk,sk);

This function randomly generates a secret key sk[0], sk[1], ...,
sk[lib25519_sign_SECRETKEYBYTES-1] and a corresponding public key
pk[0], pk[1], ..., pk[lib25519_sign_PUBLICKEYBYTES-1].

lib25519_sign_PUBLICKEYBYTES is guaranteed to be 32, and
lib25519_sign_SECRETKEYBYTES is guaranteed to be 64, but callers wishing
to allow easy substitution of other signature systems should not rely on
these guarantees.

4. Ed25519 signing:

     #include "lib25519.h"

     const unsigned char sk[lib25519_sign_SECRETKEYBYTES];
     const unsigned char m[...]; long long mlen;
     unsigned char sm[...]; long long smlen;

     lib25519_sign(sm,&smlen,m,mlen,sk);

This function signs a message m[0], ..., m[mlen-1] using the signer's
secret key sk[0], sk[1], ..., sk[lib25519_sign_SECRETKEYBYTES-1], puts
the length of the signed message into smlen, and puts the signed message
into sm[0], sm[1], ..., sm[smlen-1].

The maximum possible length smlen is mlen+lib25519_sign_BYTES. The caller
must allocate at least mlen+lib25519_sign_BYTES for sm.

lib25519_sign_SECRETKEYBYTES is guaranteed to be 64, lib25519_sign_BYTES
is guaranteed to be 64, and signed messages are always exactly 64 bytes
longer than messages, but callers wishing to allow easy substitution of
other signature systems should not rely on these guarantees.

5. Ed25519 signature verification and message recovery:

     #include "lib25519.h"

     const unsigned char pk[lib25519_sign_PUBLICKEYBYTES];
     const unsigned char sm[...]; long long smlen;
     unsigned char m[...]; long long mlen;
     int result;

     result = lib25519_sign_open(m,&mlen,sm,smlen,pk);

This function verifies the signed message in sm[0], ..., sm[smlen-1]
using the signer's public key pk[0], pk[1], ...,
pk[lib25519_sign_PUBLICKEYBYTES-1]. This function puts the length of the
message into mlen and puts the message into m[0], m[1], ..., m[mlen-1].
It then returns 0.

The maximum possible length mlen is smlen. The caller must allocate at
least smlen bytes for m (not just some guess for the number of bytes
expected in m).

If the signature fails verification, lib25519_sign_open instead returns
-1. It also sets mlen to -1 and clears m[0], m[1], ..., m[smlen-1], but
callers should note that other signature software does not necessarily
do this; callers should always check the return value.

lib25519_sign_PUBLICKEYBYTES is guaranteed to be 32, but callers wishing
to allow easy substitution of other signature systems should not rely on
this guarantee.

*/