[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] scratch/tzz/nettle 1f72645: WIP: GnuTLS: docs
From: |
Teodor Zlatanov |
Subject: |
[Emacs-diffs] scratch/tzz/nettle 1f72645: WIP: GnuTLS: docs |
Date: |
Tue, 18 Apr 2017 16:12:30 -0400 (EDT) |
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
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Emacs-diffs] scratch/tzz/nettle 1f72645: WIP: GnuTLS: docs,
Teodor Zlatanov <=