[Emacs-diffs] scratch/tzz/nettle 1f72645: WIP: GnuTLS: docs

[Teodor Zlatanov]

branch: scratch/tzz/nettle
commit 1f726452f3949dabcaebbf7ad9e9744a1c80091e
Author: Ted Zlatanov <address@hidden>
Commit: Ted Zlatanov <address@hidden>

    WIP: GnuTLS: docs
---
 doc/lispref/text.texi | 178 ++++++++++++++++++++++++++++++++++++++++++++++++++
 etc/NEWS              |   6 ++
 2 files changed, 184 insertions(+)

diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index 9696c73..6a06364 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -57,6 +57,8 @@ the character after point.
 * Decompression::    Dealing with compressed data.
 * Base 64::          Conversion to or from base 64 encoding.
 * Checksum/Hash::    Computing cryptographic hashes.
+* GnuTLS Crypto::    Cryptographic digests, hashes,
+                     and ciphers imported from GnuTLS.
 * Parsing HTML/XML:: Parsing HTML and XML.
 * Atomic Changes::   Installing several buffer changes atomically.
 * Change Hooks::     Supplying functions to be run when text is changed.
@@ -4494,6 +4496,182 @@ It should be somewhat more efficient on larger buffers 
than
 @c according to what we find useful.
 @end defun
 
address@hidden GnuTLS Crypto
address@hidden GnuTLS Crypto
address@hidden MD5 checksum
address@hidden SHA hash
address@hidden hash, cryptographic
address@hidden cryptographic hash
address@hidden AEAD cipher
address@hidden cipher, AEAD
address@hidden symmetric cipher
address@hidden cipher, symmetric
+
+If compiled with GnuTLS (TODO: without autoconf macros, we have to
+require 3.4) Emacs offers built-in cryptographic support. Following
+the GnuTLS API terminology, the available tools are digests, MACs,
+symmetric ciphers, and AEAD ciphers.
+
address@hidden gnutls-digests
+This function returns the alist of the GnuTLS digest algorithms.
+
+Each entry has a key which represents the algorithm, followed by a
+plist with internal details about the algorithm. The plist will have
address@hidden:type gnutls-digest-algorithm} and also will have the key
address@hidden:digest-algorithm-length 64} to indicate the size, in bytes, of
+the resulting digest.
+
+There is a name parallel between GnuTLS MAC and digest algorithms but
+they are separate things internally and should not be mixed.
address@hidden defun
+
address@hidden gnutls-hash-digest digest-method input
+The @var{digest-method} can be the whole plist from
address@hidden, or just the symbol key, or a string with the
+name of that symbol.
+
+The @var{input} can be a string or a buffer or a list in the format
address@hidden(BUFFER-OR-STRING START END CODING-SYSTEM NOERROR)} where only
+the first element is required.
+
+In the list form of @var{input}
+you can specify a buffer or a string, an optional range to be
+extracted, and an optional coding system. The last optional item,
address@hidden, overrides the normal error when the text can't be
+encoded using the specified or chosen coding system.  When
address@hidden is address@hidden, this function silently uses
address@hidden coding instead. This is similar to how @code{md5} and
address@hidden operate but the arguments are packed in a list.
+
+This function returns nil on error, and signals a Lisp error if the
address@hidden or @var{input} are invalid. On success, it returns
+a binary string.
address@hidden defun
+
address@hidden gnutls-macs
+This function returns the alist of the GnuTLS MAC algorithms.
+
+Each entry has a key which represents the algorithm, followed by a
+plist with internal details about the algorithm. The plist will have
address@hidden:type gnutls-mac-algorithm} and also will have the keys
address@hidden:mac-algorithm-length} @code{:mac-algorithm-keysize}
address@hidden:mac-algorithm-noncesize} to indicate the size, in bytes, of the
+resulting hash, the key, and the nonce respectively.
+
+The nonce is currently unused and only some MACs support it.
+
+There is a name parallel between GnuTLS MAC and digest algorithms but
+they are separate things internally and should not be mixed.
address@hidden defun
+
address@hidden gnutls-hash-mac hash-method key input
+The @var{hash-method} can be the whole plist from
address@hidden, or just the symbol key, or a string with the
+name of that symbol.
+
+The @var{key} can be a string or a buffer or a list in the format
address@hidden(BUFFER-OR-STRING START END CODING-SYSTEM NOERROR)} where only
+the first element is required. The @var{key} will be wiped after use
+if it's a string.
+
+The @var{input} can be a string or a buffer or a list in the format
address@hidden(BUFFER-OR-STRING START END CODING-SYSTEM NOERROR)} where only
+the first element is required.
+
+In the list form of @var{key} and @var{input}
+you can specify a buffer or a string, an optional range to be
+extracted, and an optional coding system. The last optional item,
address@hidden, overrides the normal error when the text can't be
+encoded using the specified or chosen coding system.  When
address@hidden is address@hidden, this function silently uses
address@hidden coding instead. This is similar to how @code{md5} and
address@hidden operate but the arguments are packed in a list.
+
+This function returns nil on error, and signals a Lisp error if the
address@hidden or @var{key} or @var{input} are invalid.  On
+success, it returns a binary string.
address@hidden defun
+
address@hidden gnutls-ciphers
+This function returns the alist of the GnuTLS ciphers.
+
+Each entry has a key which represents the cipher, followed by a plist
+with internal details about the algorithm. The plist will have
address@hidden:type gnutls-symmetric-cipher} and also will have the keys
address@hidden:cipher-aead-capable} set to @code{nil} or @code{t} to indicate
+AEAD capability; and @code{:cipher-tagsize} @code{:cipher-blocksize}
address@hidden:cipher-keysize} @code{:cipher-ivsize} to indicate the size, in
+bytes, of the tag, block size of the resulting data, the key, and the
+IV respectively.
address@hidden defun
+
address@hidden gnutls-symmetric-encrypt cipher key iv input &optional aead_auth
+The @var{cipher} can be the whole plist from
address@hidden, or just the symbol key, or a string with the
+name of that symbol.
+
+The @var{key} can be a string or a buffer or a list in the format
address@hidden(BUFFER-OR-STRING START END CODING-SYSTEM NOERROR)} where only
+the first element is required. The @var{key} will be wiped after use
+if it's a string.
+
+The @var{iv} and @var{input} and the optional @var{aead_auth} can be a
+string or a buffer or a list in the format @var{(BUFFER-OR-STRING
+START END CODING-SYSTEM NOERROR)} where only the first element is
+required.
+
+In the list form of @var{key}, @var{iv}, @var{input}, and the optional 
@var{aead_auth}
+you can specify a buffer or a string, an optional range to be
+extracted, and an optional coding system. The last optional item,
address@hidden, overrides the normal error when the text can't be
+encoded using the specified or chosen coding system.  When
address@hidden is address@hidden, this function silently uses
address@hidden coding instead. This is similar to how @code{md5} and
address@hidden operate but the arguments are packed in a list.
+
address@hidden is only checked with AEAD ciphers, that is, ciphers whose
+plist has @code{:cipher-aead-capable t}. Otherwise it's ignored.
+
+This function returns nil on error, and signals a Lisp error if the
address@hidden or @var{key}, @var{iv}, or @var{input} are invalid, or if
address@hidden was specified with an AEAD cipher and was invalid.  On
+success, it returns an encrypted binary string.
address@hidden defun
+
address@hidden gnutls-symmetric-decrypt cipher key iv input &optional aead_auth
+The @var{cipher} can be the whole plist from
address@hidden, or just the symbol key, or a string with the
+name of that symbol.
+
+The @var{key} can be a string or a buffer or a list in the format
address@hidden(BUFFER-OR-STRING START END CODING-SYSTEM NOERROR)} where only
+the first element is required. The @var{key} will be wiped after use
+if it's a string.
+
+The @var{iv} and @var{input} and the optional @var{aead_auth} can be a
+string or a buffer or a list in the format @var{(BUFFER-OR-STRING
+START END CODING-SYSTEM NOERROR)} where only the first element is
+required.
+
+In the list form of @var{key}, @var{iv}, @var{input}, and the optional 
@var{aead_auth}
+you can specify a buffer or a string, an optional range to be
+extracted, and an optional coding system. The last optional item,
address@hidden, overrides the normal error when the text can't be
+encoded using the specified or chosen coding system.  When
address@hidden is address@hidden, this function silently uses
address@hidden coding instead. This is similar to how @code{md5} and
address@hidden operate but the arguments are packed in a list.
+
address@hidden is only checked with AEAD ciphers, that is, ciphers whose
+plist has @code{:cipher-aead-capable t}. Otherwise it's ignored.
+
+This function returns nil on decryption error, and signals a Lisp
+error if the @var{cipher} or @var{key}, @var{iv}, or @var{input} are
+invalid, or if @var{aead_auth} was specified with an AEAD cipher and
+was invalid.  On success, it returns the original string that was
+passed to @code{gnutls-symmetric-encrypt}.
address@hidden defun
+
 @node Parsing HTML/XML
 @section Parsing HTML and XML
 @cindex parsing html
diff --git a/etc/NEWS b/etc/NEWS
index 799a2b3..b3af61b 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -879,6 +879,12 @@ instead of its first.
 * Lisp Changes in Emacs 26.1
 
 +++
+** Emacs now exposes the GnuTLS cryptographic API with the functions
+'gnutls-macs' and 'gnutls-hash-mac'; 'gnutls-digests' and
+'gnutls-hash-digest'; 'gnutls-ciphers' and 'gnutls-symmetric-encrypt'
+and 'gnutls-symmetric-decrypt'.
+
++++
 ** Emacs now supports records for user-defined types, via the new
 functions 'make-record', 'record', and 'recordp'.  Records are now
 used internally to represent cl-defstruct and defclass instances, for