GnuTLS HMAC and symmetric cipher support

    * etc/NEWS: Add news for new feature.

    * doc/lispref/text.texi (GnuTLS Cryptography): Add
    documentation.

    * configure.ac: Add macros HAVE_GNUTLS3_DIGEST,
    HAVE_GNUTLS3_CIPHER, HAVE_GNUTLS3_AEAD, HAVE_GNUTLS3_HMAC.

    * src/fns.c (Fsecure_hash_algorithms): Add function to list
    supported `secure-hash' algorithms.
    (extract_data_from_object): Add data extraction function that
    can operate on buffers and strings.
    (secure_hash): Use it.
    (Fsecure_hash): Mention `secure-hash-algorithms'.

    * src/gnutls.h: Include gnutls/crypto.h.

    * src/gnutls.c (Fgnutls_ciphers, gnutls_symmetric_aead)
    (gnutls_symmetric, Fgnutls_symmetric_encrypt, Fgnutls_symmetric_decrypt)
    (Fgnutls_macs, Fgnutls_digests, Fgnutls_hash_mac, Fgnutls_hash_digest)
    (Fgnutls_available_p): Implement GnuTLS cryptographic integration.

    * test/lisp/net/gnutls-tests.el: Add tests.

1 files changed, 195 insertions, 0 deletions

diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index 9696c73c484..fd6ddc98fed 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -57,6 +57,7 @@ the character after point.
 * Decompression::    Dealing with compressed data.
 * Base 64::          Conversion to or from base 64 encoding.
 * Checksum/Hash::    Computing cryptographic hashes.
+* GnuTLS Cryptography:: Cryptographic algorithms 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.
@@ -4436,6 +4437,11 @@ similar theoretical weakness also exists in SHA-1.  Therefore, for
 security-related applications you should use the other hash types,
 such as SHA-2.
 
+@defun secure-hash-algorithms
+This function returns a list of symbols representing algorithms that
+@code{secure-hash} can use.
+@end defun
+
 @defun secure-hash algorithm object &optional start end binary
 This function returns a hash for @var{object}.  The argument
 @var{algorithm} is a symbol stating which hash to compute: one of
@@ -4494,6 +4500,195 @@ It should be somewhat more efficient on larger buffers than
 @c according to what we find useful.
 @end defun
 
+@node GnuTLS Cryptography
+@section GnuTLS Cryptography
+@cindex MD5 checksum
+@cindex SHA hash
+@cindex hash, cryptographic
+@cindex cryptographic hash
+@cindex AEAD cipher
+@cindex cipher, AEAD
+@cindex symmetric cipher
+@cindex cipher, symmetric
+
+If compiled with GnuTLS, Emacs offers built-in cryptographic support.
+Following the GnuTLS API terminology, the available tools are digests,
+MACs, symmetric ciphers, and AEAD ciphers.
+
+The terms used herein, such as IV (Initialization Vector), require
+some familiarity with cryptography and will not be defined in detail.
+Please consult @uref{https://www.gnutls.org/} for specific
+documentation which may help you understand the terminology and
+structure of the GnuTLS library.
+
+@node Format of GnuTLS Cryptography Inputs
+@subsection Format of GnuTLS Cryptography Inputs
+@cindex format of gnutls cryptography inputs
+@cindex gnutls cryptography inputs format
+
+The inputs to GnuTLS cryptographic functions can be specified in
+several ways, both as primitive Emacs Lisp types or as lists.
+
+The list form is currently similar to how @code{md5} and
+@code{secure-hash} operate.
+
+@table @code
+@item @var{buffer}
+Simply passing a buffer as input means the whole buffer should be used.
+
+@item @var{string}
+A string as input will be used directly.  It may be modified by the
+function (unlike most other Emacs Lisp functions) to reduce the chance
+of exposing sensitive data after the function does its work.
+
+@item (@var{buffer-or-string} @var{start} @var{end} @var{coding-system} @var{noerror})
+This specifies a buffer or a string as described above, but an
+optional range can be specified with @var{start} and @var{end}.
+
+In addition an optional @var{coding-system} can be specified if needed.
+
+The last optional item, @var{noerror}, overrides the normal error when
+the text can't be encoded using the specified or chosen coding system.
+When @var{noerror} is non-@code{nil}, this function silently uses
+@code{raw-text} coding instead.
+
+@item (@code{iv-auto} @var{length})
+This will generate an IV (Initialization Vector) of the specified
+length using the GnuTLS @code{GNUTLS_RND_NONCE} generator and pass it
+to the function.  This ensures that the IV is unpredictable and
+unlikely to be reused in the same session.  The actual value of the IV
+is returned by the function as described below.
+
+@end table
+
+@node GnuTLS Cryptographic Functions
+@subsection GnuTLS Cryptographic Functions
+@cindex gnutls cryptographic functions
+
+@defun 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
+@code{:type gnutls-digest-algorithm} and also will have the key
+@code{: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.
+@end defun
+
+@defun gnutls-hash-digest digest-method input
+The @var{digest-method} can be the whole plist from
+@code{gnutls-digests}, or just the symbol key, or a string with the
+name of that symbol.
+
+The @var{input} can be specified as a buffer or string or in other
+ways (@pxref{Format of GnuTLS Cryptography Inputs}).
+
+This function returns @code{nil} on error, and signals a Lisp error if
+the @var{digest-method} or @var{input} are invalid.  On success, it
+returns a list of a binary string (the output) and the IV used.
+@end defun
+
+@defun 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
+@code{:type gnutls-mac-algorithm} and also will have the keys
+@code{:mac-algorithm-length} @code{:mac-algorithm-keysize}
+@code{: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.
+@end defun
+
+@defun gnutls-hash-mac hash-method key input
+The @var{hash-method} can be the whole plist from
+@code{gnutls-macs}, or just the symbol key, or a string with the
+name of that symbol.
+
+The @var{key} can be specified as a buffer or string or in other ways
+(@pxref{Format of GnuTLS Cryptography Inputs}).  The @var{key} will be
+wiped after use if it's a string.
+
+The @var{input} can be specified as a buffer or string or in other
+ways (@pxref{Format of GnuTLS Cryptography Inputs}).
+
+This function returns @code{nil} on error, and signals a Lisp error if
+the @var{hash-method} or @var{key} or @var{input} are invalid.
+
+On success, it returns a list of a binary string (the output) and the
+IV used.
+@end defun
+
+@defun 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
+@code{:type gnutls-symmetric-cipher} and also will have the keys
+@code{:cipher-aead-capable} set to @code{nil} or @code{t} to indicate
+AEAD capability; and @code{:cipher-tagsize} @code{:cipher-blocksize}
+@code{: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.
+@end defun
+
+@defun gnutls-symmetric-encrypt cipher key iv input &optional aead_auth
+The @var{cipher} can be the whole plist from
+@code{gnutls-ciphers}, or just the symbol key, or a string with the
+name of that symbol.
+
+The @var{key} can be specified as a buffer or string or in other ways
+(@pxref{Format of GnuTLS Cryptography Inputs}).  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
+specified as a buffer or string or in other ways (@pxref{Format of
+GnuTLS Cryptography Inputs}).
+
+@var{aead_auth} is only checked with AEAD ciphers, that is, ciphers whose
+plist has @code{:cipher-aead-capable t}.  Otherwise it's ignored.
+
+This function returns @code{nil} on 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 a list of a binary string (the output) and the
+IV used.
+@end defun
+
+@defun gnutls-symmetric-decrypt cipher key iv input &optional aead_auth
+The @var{cipher} can be the whole plist from
+@code{gnutls-ciphers}, or just the symbol key, or a string with the
+name of that symbol.
+
+The @var{key} can be specified as a buffer or string or in other ways
+(@pxref{Format of GnuTLS Cryptography Inputs}).  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
+specified as a buffer or string or in other ways (@pxref{Format of
+GnuTLS Cryptography Inputs}).
+
+@var{aead_auth} is only checked with AEAD ciphers, that is, ciphers whose
+plist has @code{:cipher-aead-capable t}.  Otherwise it's ignored.
+
+This function returns @code{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 a list of a binary string (the output) and the
+IV used.
+@end defun
+
 @node Parsing HTML/XML
 @section Parsing HTML and XML
 @cindex parsing html