Document sntrup761 support.

diff --git a/ChangeLog b/ChangeLog
index 75200742e6f0c00e1070d1247164d0114a09f2e2..274c5392118c9750f145476f01e14922b64dbe01 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -41,6 +41,9 @@
        (kem_alg_list): New algorithm list.
        (main): Benchmark both signature and kem algorithms.
 
+       * nettle.texinfo (Key-Encapsulation mechanisms): Document
+       sntrup761.
+
 2026-05-03  Niels Möller  <nisse@lysator.liu.se>
 
        * testsuite/testutils.c (test_random_seed, test_get_seed): New functions.

diff --git a/nettle.texinfo b/nettle.texinfo
index 3edbd4a6bdb9df4795cb88cee37aa0ffbae0e668..95df37cd8c27888c8f7ca551c996e13e8b274e34 100644 (file)
--- a/nettle.texinfo
+++ b/nettle.texinfo
@@ -84,6 +84,7 @@ Reference
 * Keyed hash functions::
 * Key derivation functions::
 * Public-key algorithms::
+* Key-Encapsulation mechanisms::
 * Randomness::
 * ASCII encoding::
 * Miscellaneous functions::
@@ -376,6 +377,7 @@ This chapter describes all the Nettle functions, grouped by family.
 * Keyed hash functions::
 * Key derivation functions::
 * Public-key algorithms::
+* Key-Encapsulation mechanisms::
 * Randomness::
 * ASCII encoding::
 * Miscellaneous functions::
@@ -5908,6 +5910,54 @@ Verifies a message using the provided public key. Returns 1 if the
 signature is valid, otherwise 0.
 @end deftypefun
 
+@node Key-Encapsulation mechanisms
+@section Key-Encapsulation mechanisms
+
+@cindex Key-Encapsulation mechanisms
+@cindex KEM
+@cindex sntrup
+
+Key-Encapsulation mechanisms allows a sender to take a public key as
+input and produce (encapsulate) a session key wrapped in ciphertext, and
+the receiver to extract (decapsulate) the session key using its private
+key.
+
+Nettle supports the Streamlined NTRU Prime algorithm @code{sntrup761}.
+
+Nettle defines sntrup761 in @file{<nettle/sntrup.h>}.
+
+@defvr Constant SNTRUP761_PRIVATE_KEY_SIZE
+The size (1763 bytes) of the sntrup761 secret key.
+@end defvr
+
+@defvr Constant SNTRUP761_PUBLIC_KEY_SIZE
+The size (1158 bytes) of the sntrup761 secret key.
+@end defvr
+
+@defvr Constant SNTRUP761_CIPHER_SIZE
+The size (1039 bytes) of the sntrup761 ciphertext.
+@end defvr
+
+@defvr Constant SNTRUP_SESSION_KEY_SIZE
+The size (32 bytes) of the sntrup output session key.
+@end defvr
+
+@deftypefun void sntrup761_generate_keypair (uint8_t *@var{pk}, uint8_t *@var{sk}, void *@var{random_ctx}, nettle_random_func *@var{random});
+Generate a sntrup761 public key @var{pk} and private key @var{sk}, using
+randomness-generator @var{random} with context @var{random_ctx}.
+@end deftypefun
+
+@deftypefun void sntrup761_encap (const uint8_t *@var{pk}, uint8_t *@var{k}, uint8_t *@var{c}, void *@var{random_ctx}, nettle_random_func *@var{random});
+Generate a session key @var{k} and encapsulate it into ciphertext
+@var{c} for the recipient with public-key @var{pk}, using
+randomness-generator @var{random} with context @var{random_ctx}.
+@end deftypefun
+
+@deftypefun void sntrup761_decap (const uint8_t *@var{sk}, uint8_t *@var{k}, const uint8_t *@var{c});
+Decapsulate session key @var{k} from ciphertext @var{c} using the
+private key @var{sk}.
+@end deftypefun
+
 @node Randomness
 @section Randomness