From f6e6b5380315a561a79e0fe38e9fc77e1d1a9fce Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Niels=20M=C3=B6ller?= <nisse@lysator.liu.se>
Date: Sat, 11 Nov 2017 09:55:55 +0100
Subject: [PATCH] Update manual
---
ChangeLog | 8 ++++++
nettle.texinfo | 76 ++++++++++++++++++++++++++++----------------------
2 files changed, 51 insertions(+), 33 deletions(-)
diff --git a/ChangeLog b/ChangeLog
index ed98960f..cad5744a 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,11 @@
+2017-11-11 Niels Möller <nisse@lysator.liu.se>
+
+ * nettle.texinfo: Document nettle_get_hashes, nettle_get_ciphers
+ and nettle_get_aeads, and replace nettle_secp_256r1 by
+ nettle_get_secp_256r1. Update version numbers. Delete ancient
+ setting of ispell-skip-region-alist as an emacs file-local
+ variable.
+
2017-11-08 Niels Möller <nisse@lysator.liu.se>
* ecc-curve.h (nettle_secp_192r1, nettle_secp_224r1)
diff --git a/nettle.texinfo b/nettle.texinfo
index 23eed335..aa374449 100644
--- a/nettle.texinfo
+++ b/nettle.texinfo
@@ -7,14 +7,14 @@
@syncodeindex fn cp
@c %**end of header
-@set UPDATED-FOR 3.2
+@set UPDATED-FOR 3.4
@set AUTHOR Niels Möller
@copying
This manual is for the Nettle library (version @value{UPDATED-FOR}), a
low-level cryptographic library.
-Originally written 2001 by @value{AUTHOR}, updated 2015.
+Originally written 2001 by @value{AUTHOR}, updated 2017.
@quotation
This manual is placed in the public domain. You may freely copy it, in
@@ -1009,6 +1009,7 @@ This function also resets the context in the same way as
@subsection The @code{struct nettle_hash} abstraction
@cindex nettle_hash
@cindex nettle_hashes
+@cindex nettle_get_hashes
Nettle includes a struct including information about the supported hash
functions. It is defined in @file{<nettle/nettle-meta.h>}, and is used
@@ -1039,10 +1040,19 @@ These are all the hash functions that Nettle implements.
Nettle also exports a list of all these hashes.
-@deftypevr {Constant Array} {struct nettle_hash **} nettle_hashes
+@deftypefun const struct nettle_hash **nettle_get_hashes(void)
+Returns a NULL-terminated list of pointers to supported hash functions.
This list can be used to dynamically enumerate or search the supported
-algorithms. NULL-terminated.
-@end deftypevr
+algorithms.
+@end deftypefun
+
+@deffn Macro nettle_hashes
+A macro expanding to a call to nettle_get_hashes, so that one could
+write, e.g., @code{nettle_hashes[0]->name} for the name of the first
+hash function on the list. In earlier versions, this was not a macro but
+the actual array of pointers. However, referring directly to the array
+makes the array size leak into the ABI in some cases.
+@end deffn
@node Cipher functions, Cipher modes, Hash functions, Reference
@comment node-name, next, previous, up
@@ -1826,6 +1836,7 @@ Analogous to @code{twofish_encrypt}
@subsection The @code{struct nettle_cipher} abstraction
@cindex nettle_cipher
@cindex nettle_ciphers
+@cindex nettle_get_ciphers
Nettle includes a struct including information about some of the more
regular cipher functions. It can be useful for applications that need a
@@ -1870,10 +1881,16 @@ ones without weak keys or other oddities.
Nettle also exports a list of all these ciphers without weak keys or
other oddities.
-@deftypevr {Constant Array} {struct nettle_cipher **} nettle_ciphers
+@deftypefun const struct nettle_cipher **nettle_get_ciphers(void)
+Returns a NULL-terminated list of pointers to supported block ciphers.
This list can be used to dynamically enumerate or search the supported
-algorithms. NULL-terminated.
-@end deftypevr
+algorithms.
+@end deftypefun
+
+@deffn Macro nettle_ciphers
+A macro expanding to a call to nettle_get_ciphers. In earlier versions,
+this was not a macro but the actual array of pointers.
+@end deffn
@node Cipher modes, Authenticated encryption, Cipher functions, Reference
@comment node-name, next, previous, up
@@ -2975,6 +2992,7 @@ smaller than @code{CHACHA_POLY1305_DIGEST_SIZE}, only the first
@subsection The @code{struct nettle_aead} abstraction
@cindex nettle_aead
@cindex nettle_aeads
+@cindex nettle_get_aeads
Nettle includes a struct including information about the supported hash
functions. It is defined in @file{<nettle/nettle-meta.h>}.
@@ -2998,10 +3016,16 @@ message size is specified in advance makes it incompatible with the
Nettle also exports a list of all these constructions.
-@deftypevr {Constant Array} {struct nettle_aead **} nettle_aeads
-This list can be used to dynamically enumerate or search the supported
-algorithms. NULL-terminated.
-@end deftypevr
+@deftypefun const struct nettle_aead **nettle_get_aeads(void)
+Returns a NULL-terminated list of pointers to supported algorithms.This
+list can be used to dynamically enumerate or search the supported
+algorithms.
+@end deftypefun
+
+@deffn Macro nettle_aeads
+A macro expanding to a call to nettle_get_aeads. In earlier versions,
+this was not a macro but the actual array of pointers.
+@end deffn
@node Keyed hash functions, Key derivation functions, Authenticated encryption, Reference
@comment node-name, next, previous, up
@@ -4337,12 +4361,12 @@ x^3 - 3 x + b @pmod{p}}, i.e., the points have coordinates @math{(x,y)},
both considered as integers modulo a specified prime @math{p}. Curves
are represented as a @code{struct ecc_curve}. It also supports
curve25519, which uses a different form of curve. Supported curves are
-declared in @file{<nettle/ecc-curve.h>}, e.g., @code{nettle_secp_256r1}
-for a standardized curve using the 256-bit prime @math{p = 2^{256} -
-2^{224} + 2^{192} + 2^{96} - 1}. The contents of these structs is not
-visible to nettle users. The ``bitsize of the curve'' is used as a
-shorthand for the bitsize of the curve's prime @math{p}, e.g., 256 bits
-for @code{nettle_secp_256r1}.
+declared in @file{<nettle/ecc-curve.h>}, e.g., call
+@code{nettle_get_secp_256r1} for a standardized curve using the 256-bit
+prime @math{p = 2^{256} - 2^{224} + 2^{192} + 2^{96} - 1}. The contents
+of these structs is not visible to nettle users. The ``bitsize of the
+curve'' is used as a shorthand for the bitsize of the curve's prime
+@math{p}, e.g., 256 bits for the SECP 256R1 curve.
@menu
* Side-channel silence::
@@ -4473,7 +4497,7 @@ signature for the message digest @var{digest} (of @var{length} octets).
Returns 1 if the signature is valid, otherwise 0.
@end deftypefun
-Finally, to generation of new an ECDSA key pairs
+Finally, generating a new ECDSA key pair:
@deftypefun void ecdsa_generate_keypair (struct ecc_point *@var{pub}, struct ecc_scalar *@var{key}, void *@var{random_ctx}, nettle_random_func *@var{random});
@var{pub} and @var{key} is where the resulting key pair is stored. The
@@ -5254,20 +5278,6 @@ option to be able to build with BSD make.
Local Variables:
ispell-local-dictionary: "american"
-ispell-skip-region-alist: (
- (ispell-words-keyword forward-line)
- ("^@example" . "^@end.*example")
- ("^@ignore" . "^@end.*ignore")
- ("^@\\(end\\|syncodeindex\\|vskip\\|\\(un\\)?macro\\|node\\|deftp\\) .*$")
- ("^@\\(printindex\\|set\\) .*$")
- ("^@def.*$")
- ;; Allows one level of nested braces in the argument
- ("@\\(uref\\|value\\|badspell\\|code\\|file\\|var\\|url\\){[^{}]*\\({[^{}]*}[^{}]*\\)*}")
- ("@[a-z]+[{ ]")
- ("@[a-z]+$")
- ("\input texinfo.*$")
- ("ispell-ignore" . "ispell-end-ignore")
- ("^Local Variables:$" . "^End:$"))
End:
@c LocalWords: cryptographics crypto LSH GNUPG API GPL LGPL aes rijndael ller
--
GitLab