-rw-r--r-- 5935 lib25519-20240321/doc/man/lib25519.3 raw
.\" Automatically generated by Pandoc 2.17.1.1
.\"
.\" Define V font for inline verbatim, using C font in formats
.\" that render this, and otherwise B font.
.ie "\f[CB]x\f[]"x" \{\
. ftr V B
. ftr VI BI
. ftr VB B
. ftr VBI BI
.\}
.el \{\
. ftr V CR
. ftr VI CI
. ftr VB CB
. ftr VBI CBI
.\}
.TH "lib25519" "3" "" "" ""
.hy
.SS NAME
.PP
lib25519 - C API for the lib25519 implementation of the X25519 and
Ed25519 cryptosystems
.SS SYNOPSIS
.PP
Using lib25519:
.IP
.nf
\f[C]
#include <lib25519.h>
\f[R]
.fi
.PP
Link with \f[V]-l25519\f[R].
.PP
X25519 key generation:
.IP
.nf
\f[C]
unsigned char pk[lib25519_dh_PUBLICKEYBYTES];
unsigned char sk[lib25519_dh_SECRETKEYBYTES];

lib25519_dh_keypair(pk,sk);
\f[R]
.fi
.PP
X25519 shared-secret generation:
.IP
.nf
\f[C]
unsigned char k[lib25519_dh_BYTES];
const unsigned char pk[lib25519_dh_PUBLICKEYBYTES];
const unsigned char sk[lib25519_dh_SECRETKEYBYTES];

lib25519_dh(k,pk,sk);
\f[R]
.fi
.PP
Ed25519 key generation:
.IP
.nf
\f[C]
unsigned char pk[lib25519_sign_PUBLICKEYBYTES];
unsigned char sk[lib25519_sign_SECRETKEYBYTES];

lib25519_sign_keypair(pk,sk);
\f[R]
.fi
.PP
Ed25519 signature generation:
.IP
.nf
\f[C]
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);
\f[R]
.fi
.PP
Ed25519 signature verification and message recovery:
.IP
.nf
\f[C]
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);
\f[R]
.fi
.SS DESCRIPTION
.PP
lib25519 is an implementation of the X25519 encryption system and the
Ed25519 signature system.
The stable C API for lib25519 consists of the five functions listed
above.
.PP
All of these functions follow the SUPERCOP/NaCl APIs for
DH (https://bench.cr.yp.to/call-dh.html) and
signatures (https://bench.cr.yp.to/call-sign.html) except that
.IP \[bu] 2
the function names are lib25519-specific instead of \f[V]crypto_*\f[R],
.IP \[bu] 2
message lengths are \f[V]long long\f[R] instead of
\f[V]unsigned long long\f[R], and
.IP \[bu] 2
all functions except signature verification return \f[V]void\f[R]
instead of \f[V]int\f[R].
.SS X25519 KEY GENERATION
.PP
\f[V]lib25519_dh_keypair(pk,sk)\f[R] randomly generates Alice\[cq]s
secret key \f[V]sk[0], sk[1], ..., sk[lib25519_dh_SECRETKEYBYTES-1]\f[R]
and Alice\[cq]s corresponding public key
\f[V]pk[0], pk[1], ..., pk[lib25519_dh_PUBLICKEYBYTES-1]\f[R].
.PP
\f[V]lib25519_dh_PUBLICKEYBYTES\f[R] and
\f[V]lib25519_dh_SECRETKEYBYTES\f[R] are guaranteed to be 32, but
callers wishing to allow easy substitution of other DH systems should
not rely on this guarantee.
.SS X25519 SHARED-SECRET GENERATION
.PP
\f[V]lib25519_dh(k,pk,sk)\f[R] computes the X25519 secret
\f[V]k[0], k[1], ..., k[lib25519_dh_BYTES-1]\f[R] shared between Alice
and Bob, given Bob\[cq]s public key
\f[V]pk[0], pk[1], ..., pk[lib25519_dh_PUBLICKEYBYTES-1]\f[R] and
Alice\[cq]s secret key
\f[V]sk[0], sk[1], ..., sk[lib25519_dh_SECRETKEYBYTES-1]\f[R].
.PP
\f[V]lib25519_dh_PUBLICKEYBYTES\f[R],
\f[V]lib25519_dh_SECRETKEYBYTES\f[R], and \f[V]lib25519_dh_BYTES\f[R]
are guaranteed to be 32, but callers wishing to allow easy substitution
of other DH systems should not rely on this guarantee.
.SS ED25519 KEY GENERATION
.PP
\f[V]lib25519_sign_keypair(pk,sk)\f[R] randomly generates a secret key
\f[V]sk[0], sk[1], ..., sk[lib25519_sign_SECRETKEYBYTES-1]\f[R] and a
corresponding public key
\f[V]pk[0], pk[1], ..., pk[lib25519_sign_PUBLICKEYBYTES-1]\f[R].
.PP
\f[V]lib25519_sign_PUBLICKEYBYTES\f[R] is guaranteed to be 32, and
\f[V]lib25519_sign_SECRETKEYBYTES\f[R] is guaranteed to be 64, but
callers wishing to allow easy substitution of other signature systems
should not rely on these guarantees.
.SS ED25519 SIGNATURE GENERATION
.PP
\f[V]lib25519_sign(sm,&smlen,m,mlen,sk)\f[R] signs a message
\f[V]m[0], ..., m[mlen-1]\f[R] using the signer\[cq]s secret key
\f[V]sk[0], sk[1], ..., sk[lib25519_sign_SECRETKEYBYTES-1]\f[R], puts
the length of the signed message into \f[V]smlen\f[R], and puts the
signed message into \f[V]sm[0], sm[1], ..., sm[smlen-1]\f[R].
.PP
The maximum possible length \f[V]smlen\f[R] is
\f[V]mlen+lib25519_sign_BYTES\f[R].
The caller must allocate at least \f[V]mlen+lib25519_sign_BYTES\f[R] for
\f[V]sm\f[R].
.PP
\f[V]lib25519_sign_SECRETKEYBYTES\f[R] is guaranteed to be 64,
\f[V]lib25519_sign_BYTES\f[R] 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.
.SS ED25519 SIGNATURE VERIFICATION AND MESSAGE RECOVERY
.PP
\f[V]lib25519_sign_open(m,&mlen,sm,smlen,pk)\f[R] verifies the signed
message in \f[V]sm[0], ..., sm[smlen-1]\f[R] using the signer\[cq]s
public key
\f[V]pk[0], pk[1], ..., pk[lib25519_sign_PUBLICKEYBYTES-1]\f[R].
This function puts the length of the message into \f[V]mlen\f[R] and
puts the message into \f[V]m[0], m[1], ..., m[mlen-1]\f[R].
It then returns \f[V]0\f[R].
.PP
The maximum possible length \f[V]mlen\f[R] is \f[V]smlen\f[R].
The caller must allocate at least \f[V]smlen\f[R] bytes for \f[V]m\f[R]
(not just some guess for the number of bytes expected in \f[V]m\f[R]).
.PP
If the signature fails verification, \f[V]lib25519_sign_open\f[R]
instead returns \f[V]-1\f[R].
It also sets \f[V]mlen\f[R] to \f[V]-1\f[R] and clears
\f[V]m[0], m[1], ..., m[smlen-1]\f[R], but callers should note that
other signature software does not necessarily do this; callers should
always check the return value.
.PP
\f[V]lib25519_sign_PUBLICKEYBYTES\f[R] is guaranteed to be 32, but
callers wishing to allow easy substitution of other signature systems
should not rely on this guarantee.
.SS SEE ALSO
.PP
\f[B]x25519-cli\f[R](1), \f[B]ed25519-cli\f[R](1),
\f[B]randombytes\f[R](3)