Skip to content
GitLab
Projects
Groups
Snippets
Help
Loading...
Help
What's new
7
Help
Support
Community forum
Keyboard shortcuts
?
Submit feedback
Contribute to GitLab
Sign in / Register
Toggle navigation
Open sidebar
Nettle
nettle
Commits
b9451863
Commit
b9451863
authored
Apr 27, 2014
by
Niels Möller
Browse files
Options
Browse Files
Download
Email Patches
Plain Diff
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
