Commit cb60f3c8 authored by Niels Möller's avatar Niels Möller
Browse files

Document poly1305-aes.

parent 97f60ed6
2014-05-05 Niels Möller <nisse@lysator.liu.se>
* nettle.texinfo (POLY1305): Document poly1305-aes.
2014-05-04 Niels Möller <nisse@lysator.liu.se> 2014-05-04 Niels Möller <nisse@lysator.liu.se>
* nettle.texinfo (DSA): Document new DSA interface. * nettle.texinfo (DSA): Document new DSA interface.
......
...@@ -1947,7 +1947,7 @@ in @acronym{GCM} authentication, see ...@@ -1947,7 +1947,7 @@ in @acronym{GCM} authentication, see
* GCM:: * GCM::
* CCM:: * CCM::
@end menu @end menu
@c FIXME: chacha-poly1305
@node CBC, CTR, Cipher modes, Cipher modes @node CBC, CTR, Cipher modes, Cipher modes
@comment node-name, next, previous, up @comment node-name, next, previous, up
...@@ -2803,6 +2803,7 @@ as well. ...@@ -2803,6 +2803,7 @@ as well.
@menu @menu
* HMAC:: * HMAC::
* UMAC:: * UMAC::
* POLY1305::
@end menu @end menu
@node HMAC, UMAC, Keyed hash functions, Keyed hash functions @node HMAC, UMAC, Keyed hash functions, Keyed hash functions
...@@ -3023,7 +3024,7 @@ This function also resets the context for processing new messages, with ...@@ -3023,7 +3024,7 @@ This function also resets the context for processing new messages, with
the same key. the same key.
@end deftypefun @end deftypefun
@node UMAC, , HMAC, Keyed hash functions @node UMAC, POLY1305 , HMAC, Keyed hash functions
@comment node-name, next, previous, up @comment node-name, next, previous, up
@subsection @acronym{UMAC} @subsection @acronym{UMAC}
...@@ -3068,8 +3069,8 @@ corresponding to the desired size. ...@@ -3068,8 +3069,8 @@ corresponding to the desired size.
The internal block size of @acronym{UMAC} is 1024 octets, and it also The internal block size of @acronym{UMAC} is 1024 octets, and it also
generates more than 1024 bytes of subkeys. This makes the size of the generates more than 1024 bytes of subkeys. This makes the size of the
context struct a bit larger than other hash functions and @acronym{MAC} context struct quite a bit larger than other hash functions and
algorithms in Nettle. @acronym{MAC} algorithms in Nettle.
Nettle defines @acronym{UMAC} in @file{<nettle/umac.h>}. Nettle defines @acronym{UMAC} in @file{<nettle/umac.h>}.
...@@ -3144,6 +3145,72 @@ as described above, the new value is used unless you call the ...@@ -3144,6 +3145,72 @@ as described above, the new value is used unless you call the
@code{_set_nonce} function explicitly for each message. @code{_set_nonce} function explicitly for each message.
@end deftypefun @end deftypefun
@node POLY1305,, UMAC, Keyed hash functions
@comment node-name, next, previous, up
@subsection Poly1305
Poly1305-AES is a message authentication code designed by D. J.
Bernstein. It treats the message as a polynomial modulo the prime number
@math{2^130 - 5}.
The key, 256 bits, consists of two parts, where the first half is an
@acronym{AES}-128 key, and the second half specifies the point where the
polynomial is evaluated. Of the latter half, 22 bits are set to zero, to
enable high-performance implementation, leaving 106 bits for specifying
an evaluation point @code{r}. For each message, one must also provide a
128-bit nonce. The nonce is encrypted using the @acronym{AES} key, and
that's the only thing @acronym{AES} is used for.
The message is split into 128-bit chunks (with final chunk possibly
being shorter), each read as a little-endian integer. Each chunk has a
one-bit appended at the high end. The resulting integers are treated as
polynomial coefficients modulo @math{2^130 - 5}, and the polynomial is
evaluated at the point @code{r}. Finally, this value is reduced modulo
@math{2^128}, and added (also modulo @math{2^128}) to the encrypted
nonce, to produce an 128-bit authenticator for the message. See
@uref{http://cr.yp.to/mac/poly1305-20050329.pdf} for further details.
@ FIXME: Refer to chacha-poly1305
Clearly, variants using a different cipher than @acronym{AES} could be
defined. Nettle defines Poly1305 in @file{nettle/poly1305.h}.
@defvr Constant POLY1305_AES_KEY_SIZE
Key size, 32 octets.
@end defvr
@defvr Constant POLY1305_AES_DIGEST_SIZE
Size of the digest or ``authenticator'', 16 octets.
@end defvr
@defvr Constant POLY1305_AES_NONCE_SIZE
Nonce size, 16 octets.
@end defvr
@deftp {Context struct} {struct poly1305_aes_ctx}
The poly1305-aes context struct.
@end deftp
@deftypefun void poly1305_aes_set_key (struct poly1305_aes_ctx *@var{ctx}, const uint8_t *@var{key})
Initialize the context struct. Also sets the nonce to zero.
@end deftypefun
@deftypefun void poly1305_aes_set_nonce (struct poly1305_aes_ctx *@var{ctx}, const uint8_t *@var{nonce})
Sets the nonce. Calling this function is optional, since the nonce is
incremented automatically for each message.
@end deftypefun
@deftypefun void poly1305_aes_update (struct poly1305_aes_ctx *@var{ctx}, size_t @var{length}, const uint8_t *@var{data})
Process more data.
@end deftypefun
@deftypefun void poly1305_aes_digest (struct poly1305_aes_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{digest})
Extracts the digest. If @var{length} is smaller than
@code{POLY1305_AES_DIGEST_SIZE}, only the first @var{length} octets are
written. Also increments the nonce, and prepares the context for
processing a new message.
@end deftypefun
@node Key derivation functions, Public-key algorithms, Keyed hash functions, Reference @node Key derivation functions, Public-key algorithms, Keyed hash functions, Reference
@comment node-name, next, previous, up @comment node-name, next, previous, up
@section Key derivation Functions @section Key derivation Functions
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment