Skip to content
GitLab
Menu
Projects
Groups
Snippets
Loading...
Help
Help
Support
Community forum
Keyboard shortcuts
?
Submit feedback
Contribute to GitLab
Sign in / Register
Toggle navigation
Menu
Open sidebar
Nettle
nettle
Commits
b9451863
Commit
b9451863
authored
Apr 27, 2014
by
Niels Möller
Browse files
Updated GCM documentation.
parent
47b66061
Changes
2
Hide whitespace changes
Inline
Side-by-side
Showing
2 changed files
with
102 additions
and
22 deletions
+102
-22
ChangeLog
ChangeLog
+2
-0
nettle.texinfo
nettle.texinfo
+100
-22
No files found.
ChangeLog
View file @
b9451863
2014-04-27 Niels Möller <nisse@lysator.liu.se>
* nettle.texinfo (Cipher modes): Subsection on AEAD constructions.
(GCM): Update GCM documentation, including functions for
gcm_aes128, gcm_camellia128, ...
2014-04-26 Niels Möller <nisse@lysator.liu.se>
...
...
nettle.texinfo
View file @
b9451863
...
...
@@ -2253,8 +2253,8 @@ In particular, don't use @acronym{GCM} with short authentication tags.
Nettle's support for @acronym
{
GCM
}
consists of a low-level general
interface, some convenience macros, and specific functions for
@acronym
{
GCM
}
using @acronym
{
AES
}
as the underlying cipher.
These
interfaces are defined in @file
{
<nettle/gcm.h>
}
@acronym
{
GCM
}
using @acronym
{
AES
}
or Camellia
as the underlying cipher.
These
interfaces are defined in @file
{
<nettle/gcm.h>
}
@subsubsection General @acronym
{
GCM
}
interface
...
...
@@ -2332,25 +2332,25 @@ underlying cipher, the hash sub-key, and the per-message state. It expands
to
@example
@
{
context
_
type cipher;
struct gcm
_
key key;
struct gcm
_
ctx gcm;
context
_
type cipher;
@
}
@end example
@end deffn
Example use:
@example
struct gcm
_
aes
_
ctx GCM
_
CTX(struct aes
_
ctx);
struct gcm
_
aes
128
_
ctx GCM
_
CTX(struct aes
128
_
ctx);
@end example
The following macros operate on context structs of this form.
@deffn Macro GCM
_
SET
_
KEY (@var
{
ctx
}
, @var
{
set
_
key
}
, @var
{
encrypt
}
, @var
{
length
}
, @var
{
data
}
)
@deffn Macro GCM
_
SET
_
KEY (@var
{
ctx
}
, @var
{
set
_
key
}
, @var
{
encrypt
}
, @var
{
key
}
)
First argument, @var
{
ctx
}
, is a context struct as defined
by @code
{
GCM
_
CTX
}
. @var
{
set
_
key
}
and @var
{
encrypt
}
are functions for
setting the encryption key and for encrypting data using the underlying
cipher.
@var
{
length
}
and @var
{
data
}
give the key.
cipher.
@end deffn
@deffn Macro GCM
_
SET
_
IV (@var
{
ctx
}
, @var
{
length
}
, @var
{
data
}
)
...
...
@@ -2369,48 +2369,126 @@ struct as defined by @code{GCM_CTX}
@deffnx Macro GCM
_
DIGEST (@var
{
ctx
}
, @var
{
encrypt
}
, @var
{
length
}
, @var
{
digest
}
)
Simpler way to call @code
{
gcm
_
encrypt
}
, @code
{
gcm
_
decrypt
}
or
@code
{
gcm
_
digest
}
. First argument is a context struct as defined by
@code
{
GCM
_
CTX
}
. Second argument, @var
{
encrypt
}
, is
a pointer to the
encryption
function of the underlying cipher.
@code
{
GCM
_
CTX
}
. Second argument, @var
{
encrypt
}
, is
the encryption
function of the underlying cipher.
@end deffn
@subsubsection @acronym
{
GCM
}
-@acronym
{
AES
}
interface
The following functions implement the common case of @acronym
{
GCM
}
using
@acronym
{
AES
}
as the underlying cipher.
@acronym
{
AES
}
as the underlying cipher. The variants with a specific
@acronym
{
AES
}
flavor are recommended, while the fucntinos using
@code
{
struct gcm
_
aes
_
ctx
}
are kept for compatibility with older versiosn
of Nettle.
@deftp
{
Context struct
}
{
struct gcm
_
aes128
_
ctx
}
@deftpx
{
Context struct
}
{
struct gcm
_
aes192
_
ctx
}
@deftpx
{
Context struct
}
{
struct gcm
_
aes256
_
ctx
}
Context structs, defined using @code
{
GCM
_
CTX
}
.
@end deftp
@deftp
{
Context struct
}
{
struct gcm
_
aes
_
ctx
}
Th
e context struct,
defined using @code
{
GCM
_
CTX
}
.
Alternativ
e context struct,
usign the old @acronym
{
AES
}
interface
.
@end deftp
@deftypefun void gcm
_
aes128
_
set
_
key (struct gcm
_
aes128
_
ctx *@var
{
ctx
}
, const uint8
_
t *@var
{
key
}
)
@deftypefunx void gcm
_
aes192
_
set
_
key (struct gcm
_
aes192
_
ctx *@var
{
ctx
}
, const uint8
_
t *@var
{
key
}
)
@deftypefunx void gcm
_
aes256
_
set
_
key (struct gcm
_
aes256
_
ctx *@var
{
ctx
}
, const uint8
_
t *@var
{
key
}
)
Initializes @var
{
ctx
}
using the given key.
@end deftypefun
@deftypefun void gcm
_
aes
_
set
_
key (struct gcm
_
aes
_
ctx *@var
{
ctx
}
, size
_
t @var
{
length
}
, const uint8
_
t *@var
{
key
}
)
Initializes @var
{
ctx
}
using the given key. All valid @acronym
{
AES
}
key
sizes can be used.
Corresponding function, using the old @acronym
{
AES
}
interface. All valid
@acronym
{
AES
}
key
sizes can be used.
@end deftypefun
@deftypefun void gcm
_
aes
_
set
_
iv (struct gcm
_
aes
_
ctx *@var
{
ctx
}
, size
_
t @var
{
length
}
, const uint8
_
t *@var
{
iv
}
)
@deftypefun void gcm
_
aes128
_
set
_
iv (struct gcm
_
aes128
_
ctx *@var
{
ctx
}
, size
_
t @var
{
length
}
, const uint8
_
t *@var
{
iv
}
)
@deftypefunx void gcm
_
aes192
_
set
_
iv (struct gcm
_
aes192
_
ctx *@var
{
ctx
}
, size
_
t @var
{
length
}
, const uint8
_
t *@var
{
iv
}
)
@deftypefunx void gcm
_
aes256
_
set
_
iv (struct gcm
_
aes256
_
ctx *@var
{
ctx
}
, size
_
t @var
{
length
}
, const uint8
_
t *@var
{
iv
}
)
@deftypefunx void gcm
_
aes
_
set
_
iv (struct gcm
_
aes
_
ctx *@var
{
ctx
}
, size
_
t @var
{
length
}
, const uint8
_
t *@var
{
iv
}
)
Initializes the per-message state, using the given @acronym
{
IV
}
.
@end deftypefun
@deftypefun void gcm
_
aes
_
update (struct gcm
_
aes
_
ctx *@var
{
ctx
}
, size
_
t @var
{
length
}
, const uint8
_
t *@var
{
data
}
)
@deftypefun void gcm
_
aes128
_
update (struct gcm
_
aes128
_
ctx *@var
{
ctx
}
, size
_
t @var
{
length
}
, const uint8
_
t *@var
{
data
}
)
@deftypefunx void gcm
_
aes192
_
update (struct gcm
_
aes192
_
ctx *@var
{
ctx
}
, size
_
t @var
{
length
}
, const uint8
_
t *@var
{
data
}
)
@deftypefunx void gcm
_
aes256
_
update (struct gcm
_
aes256
_
ctx *@var
{
ctx
}
, size
_
t @var
{
length
}
, const uint8
_
t *@var
{
data
}
)
@deftypefunx void gcm
_
aes
_
update (struct gcm
_
aes
_
ctx *@var
{
ctx
}
, size
_
t @var
{
length
}
, const uint8
_
t *@var
{
data
}
)
Provides associated data to be authenticated. If used, must be called
before @code
{
gcm
_
aes
_
encrypt
}
or @code
{
gcm
_
aes
_
decrypt
}
. All but the
last call
for each message @emph
{
must
}
use a length that is a multiple
of the
block size.
before @code
{
gcm
_
aes
_
encrypt
}
or @code
{
gcm
_
aes
_
decrypt
}
. All but the
last call
for each message @emph
{
must
}
use a length that is a multiple
of the
block size.
@end deftypefun
@deftypefun void gcm
_
aes
_
encrypt (struct gcm
_
aes
_
ctx *@var
{
ctx
}
, size
_
t @var
{
length
}
, uint8
_
t *@var
{
dst
}
, const uint8
_
t *@var
{
src
}
)
@deftypefun void gcm
_
aes128
_
encrypt (struct gcm
_
aes128
_
ctx *@var
{
ctx
}
, size
_
t @var
{
length
}
, uint8
_
t *@var
{
dst
}
, const uint8
_
t *@var
{
src
}
)
@deftypefunx void gcm
_
aes192
_
encrypt (struct gcm
_
aes192
_
ctx *@var
{
ctx
}
, size
_
t @var
{
length
}
, uint8
_
t *@var
{
dst
}
, const uint8
_
t *@var
{
src
}
)
@deftypefunx void gcm
_
aes256
_
encrypt (struct gcm
_
aes256
_
ctx *@var
{
ctx
}
, size
_
t @var
{
length
}
, uint8
_
t *@var
{
dst
}
, const uint8
_
t *@var
{
src
}
)
@deftypefunx void gcm
_
aes
_
encrypt (struct gcm
_
aes
_
ctx *@var
{
ctx
}
, size
_
t @var
{
length
}
, uint8
_
t *@var
{
dst
}
, const uint8
_
t *@var
{
src
}
)
@deftypefunx void gcm
_
aes128
_
decrypt (struct gcm
_
aes128
_
ctx *@var
{
ctx
}
, size
_
t @var
{
length
}
, uint8
_
t *@var
{
dst
}
, const uint8
_
t *@var
{
src
}
)
@deftypefunx void gcm
_
aes192
_
decrypt (struct gcm
_
aes192
_
ctx *@var
{
ctx
}
, size
_
t @var
{
length
}
, uint8
_
t *@var
{
dst
}
, const uint8
_
t *@var
{
src
}
)
Encrypts or decrypts the data of a message. All but the last call for
@deftypefunx void gcm
_
aes256
_
decrypt (struct gcm
_
aes256
_
ctx *@var
{
ctx
}
, size
_
t @var
{
length
}
, uint8
_
t *@var
{
dst
}
, const uint8
_
t *@var
{
src
}
)
@deftypefunx void gcm
_
aes
_
decrypt (struct gcm
_
aes
_
ctx *@var
{
ctx
}
, size
_
t @var
{
length
}
, uint8
_
t *@var
{
dst
}
, const uint8
_
t *@var
{
src
}
)
Encrypts or decrypts the data of a message. All but the last call for
each message @emph
{
must
}
use a length that is a multiple of the block
size.
@end deftypefun
@deftypefun void gcm
_
aes128
_
digest (struct gcm
_
aes128
_
ctx *@var
{
ctx
}
, size
_
t @var
{
length
}
, uint8
_
t *@var
{
digest
}
)
@deftypefunx void gcm
_
aes192
_
digest (struct gcm
_
aes192
_
ctx *@var
{
ctx
}
, size
_
t @var
{
length
}
, uint8
_
t *@var
{
digest
}
)
@deftypefunx void gcm
_
aes256
_
digest (struct gcm
_
aes256
_
ctx *@var
{
ctx
}
, size
_
t @var
{
length
}
, uint8
_
t *@var
{
digest
}
)
@deftypefunx void gcm
_
aes
_
digest (struct gcm
_
aes
_
ctx *@var
{
ctx
}
, size
_
t @var
{
length
}
, uint8
_
t *@var
{
digest
}
)
Extracts the message digest (also known ``authentication tag''). This is
the final operation when processing a message. It's strongly recommended
that @var
{
length
}
is @code
{
GCM
_
DIGEST
_
SIZE
}
, but if you provide a smaller
value, only the first @var
{
length
}
octets of the digest are written.
@end deftypefun
@deftypefun void gcm
_
aes
_
digest (struct gcm
_
aes
_
ctx *@var
{
ctx
}
, size
_
t @var
{
length
}
, uint8
_
t *@var
{
digest
}
)
@subsubsection @acronym
{
GCM
}
-Camellia interface
The following functions implement the case of @acronym
{
GCM
}
using
Camellia as the underlying cipher.
@deftp
{
Context struct
}
{
struct gcm
_
camellia128
_
ctx
}
@deftpx
{
Context struct
}
{
struct gcm
_
camellia256
_
ctx
}
Context structs, defined using @code
{
GCM
_
CTX
}
.
@end deftp
@deftypefun void gcm
_
camellia128
_
set
_
key (struct gcm
_
camellia128
_
ctx *@var
{
ctx
}
, const uint8
_
t *@var
{
key
}
)
@deftypefunx void gcm
_
camellia256
_
set
_
key (struct gcm
_
camellia256
_
ctx *@var
{
ctx
}
, const uint8
_
t *@var
{
key
}
)
Initializes @var
{
ctx
}
using the given key.
@end deftypefun
@deftypefun void gcm
_
camellia128
_
set
_
iv (struct gcm
_
camellia128
_
ctx *@var
{
ctx
}
, size
_
t @var
{
length
}
, const uint8
_
t *@var
{
iv
}
)
@deftypefunx void gcm
_
camellia256
_
set
_
iv (struct gcm
_
camellia256
_
ctx *@var
{
ctx
}
, size
_
t @var
{
length
}
, const uint8
_
t *@var
{
iv
}
)
Initializes the per-message state, using the given @acronym
{
IV
}
.
@end deftypefun
@deftypefun void gcm
_
camellia128
_
update (struct gcm
_
camellia128
_
ctx *@var
{
ctx
}
, size
_
t @var
{
length
}
, const uint8
_
t *@var
{
data
}
)
@deftypefunx void gcm
_
camellia256
_
update (struct gcm
_
camellia256
_
ctx *@var
{
ctx
}
, size
_
t @var
{
length
}
, const uint8
_
t *@var
{
data
}
)
Provides associated data to be authenticated. If used, must be called
before @code
{
gcm
_
camellia
_
encrypt
}
or @code
{
gcm
_
camellia
_
decrypt
}
. All but the
last call for each message @emph
{
must
}
use a length that is a multiple
of the block size.
@end deftypefun
@deftypefun void gcm
_
camellia128
_
encrypt (struct gcm
_
camellia128
_
ctx *@var
{
ctx
}
, size
_
t @var
{
length
}
, uint8
_
t *@var
{
dst
}
, const uint8
_
t *@var
{
src
}
)
@deftypefunx void gcm
_
camellia256
_
encrypt (struct gcm
_
camellia256
_
ctx *@var
{
ctx
}
, size
_
t @var
{
length
}
, uint8
_
t *@var
{
dst
}
, const uint8
_
t *@var
{
src
}
)
@deftypefunx void gcm
_
camellia128
_
decrypt (struct gcm
_
camellia128
_
ctx *@var
{
ctx
}
, size
_
t @var
{
length
}
, uint8
_
t *@var
{
dst
}
, const uint8
_
t *@var
{
src
}
)
Encrypts or decrypts the data of a message. All but the last call for
@deftypefunx void gcm
_
camellia256
_
decrypt (struct gcm
_
camellia256
_
ctx *@var
{
ctx
}
, size
_
t @var
{
length
}
, uint8
_
t *@var
{
dst
}
, const uint8
_
t *@var
{
src
}
)
Encrypts or decrypts the data of a message. All but the last call for
each message @emph
{
must
}
use a length that is a multiple of the block
size.
@end deftypefun
@deftypefun void gcm
_
camellia128
_
digest (struct gcm
_
camellia128
_
ctx *@var
{
ctx
}
, size
_
t @var
{
length
}
, uint8
_
t *@var
{
digest
}
)
@deftypefunx void gcm
_
camellia192
_
digest (struct gcm
_
camellia192
_
ctx *@var
{
ctx
}
, size
_
t @var
{
length
}
, uint8
_
t *@var
{
digest
}
)
@deftypefunx void gcm
_
camellia256
_
digest (struct gcm
_
camellia256
_
ctx *@var
{
ctx
}
, size
_
t @var
{
length
}
, uint8
_
t *@var
{
digest
}
)
@deftypefunx void gcm
_
camellia
_
digest (struct gcm
_
camellia
_
ctx *@var
{
ctx
}
, size
_
t @var
{
length
}
, uint8
_
t *@var
{
digest
}
)
Extracts the message digest (also known ``authentication tag''). This is
the final operation when processing a message.
@var
{
length
}
is usually
equal to
@code
{
GCM
_
BLOCK
_
SIZE
}
, but if you provide a smaller
value,
only the first @var
{
length
}
octets of the digest are written.
the final operation when processing a message.
It's strongly recommended
that @var
{
length
}
is
@code
{
GCM
_
DIGEST
_
SIZE
}
, but if you provide a smaller
value,
only the first @var
{
length
}
octets of the digest are written.
@end deftypefun
@node CCM, , GCM, Cipher modes
...
...
Write
Preview
Markdown
is supported
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
