Skip to content
GitLab
Menu
Projects
Groups
Snippets
Help
Help
Support
Community forum
Keyboard shortcuts
?
Submit feedback
Contribute to GitLab
Sign in / Register
Toggle navigation
Menu
Open sidebar
Wim Lewis
nettle
Commits
cb60f3c8
Commit
cb60f3c8
authored
May 05, 2014
by
Niels Möller
Browse files
Document poly1305-aes.
parent
97f60ed6
Changes
2
Hide whitespace changes
Inline
Side-by-side
ChangeLog
View file @
cb60f3c8
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>
* nettle.texinfo (DSA): Document new DSA interface.
...
...
nettle.texinfo
View file @
cb60f3c8
...
...
@@ -1947,7 +1947,7 @@ in @acronym{GCM} authentication, see
* GCM::
* CCM::
@end menu
@c FIXME: chacha-poly1305
@node CBC, CTR, Cipher modes, Cipher modes
@comment node-name, next, previous, up
...
...
@@ -2803,6 +2803,7 @@ as well.
@menu
* HMAC::
* UMAC::
* POLY1305::
@end menu
@node HMAC, UMAC, Keyed hash functions, Keyed hash functions
...
...
@@ -3023,7 +3024,7 @@ This function also resets the context for processing new messages, with
the same key.
@end deftypefun
@node UMAC, , HMAC, Keyed hash functions
@node UMAC,
POLY1305
, HMAC, Keyed hash functions
@comment node-name, next, previous, up
@subsection @acronym
{
UMAC
}
...
...
@@ -3068,8 +3069,8 @@ corresponding to the desired size.
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
context struct a bit larger than other hash functions and
@acronym
{
MAC
}
algorithms in Nettle.
context struct
quite
a bit larger than other hash functions and
@acronym
{
MAC
}
algorithms in Nettle.
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
@code
{_
set
_
nonce
}
function explicitly for each message.
@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
@comment node-name, next, previous, up
@section Key derivation Functions
...
...
Write
Preview
Supports
Markdown
0%
Try again
or
attach a new file
.
Attach a file
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Cancel
Please
register
or
sign in
to comment