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
Brian Smith
nettle
Commits
7d6686af
Commit
7d6686af
authored
Feb 16, 2011
by
Niels Möller
Browse files
Options
Browse Files
Download
Email Patches
Plain Diff
Fleshed out section on gcm.
Rev: nettle/nettle.texinfo:1.18
parent
1dd087d0
Changes
1
Hide whitespace changes
Inline
Side-by-side
Showing
1 changed file
with
122 additions
and
14 deletions
+122
-14
nettle.texinfo
nettle.texinfo
+122
-14
No files found.
nettle.texinfo
View file @
7d6686af
...
...
@@ -1415,7 +1415,7 @@ argument @var{ctx} on to @var{f}.
There are also some macros to help use these functions correctly.
@deffn Macro CBC
_
CTX (@var
{
context
_
type
}
, @var
{
block
_
size
}
)
Expands
in
to
Expands to
@example
@
{
context
_
type ctx;
...
...
@@ -1508,7 +1508,7 @@ a multiple of the block size.
Like for @acronym
{
CBC
}
, there are also a couple of helper macros.
@deffn Macro CTR
_
CTX (@var
{
context
_
type
}
, @var
{
block
_
size
}
)
Expands
in
to
Expands to
@example
@
{
context
_
type ctx;
...
...
@@ -1573,7 +1573,7 @@ underlying cipher. These interfaces are defined in @file{<nettle/gcm.h>}
@subsubsection General @acronym
{
GCM
}
interface
@deftp
{
Conte
c
t struct
}
{
struct gcm
_
key
}
@deftp
{
Conte
x
t struct
}
{
struct gcm
_
key
}
Message independent hash subkey, and related tables.
@end deftp
...
...
@@ -1586,23 +1586,41 @@ Holds state corresponding to a particular message.
@end defvr
@defvr Constant GCM
_
IV
_
SIZE
Recommended size of the @acronym
{
IV
}
. Other sizes are allowed.
Recommended size of the @acronym
{
IV
}
, 12
. Other sizes are allowed.
@end defvr
@deftypefun void gcm
_
set
_
key (struct gcm
_
key *@var
{
key
}
, void *@var
{
cipher
}
, nettle
_
crypt
_
func *@var
{
f
}
);
@deftypefun void gcm
_
set
_
key (struct gcm
_
key *@var
{
key
}
, void *@var
{
cipher
}
, nettle
_
crypt
_
func *@var
{
f
}
)
Initializes @var
{
key
}
. @var
{
cipher
}
gives a context struct for the
underlying cipher, which must have been previously initialized for
encryption, and @var
{
f
}
is the encryption function.
@end deftypefun
@deftypefun void gcm
_
set
_
iv (struct gcm
_
ctx *@var
{
ctx
}
, const struct gcm
_
key *@var
{
key
}
, unsigned @var
{
length
}
, const uint8
_
t *@var
{
iv
}
);
@deftypefun void gcm
_
set
_
iv (struct gcm
_
ctx *@var
{
ctx
}
, const struct gcm
_
key *@var
{
key
}
, unsigned @var
{
length
}
, const uint8
_
t *@var
{
iv
}
)
Initializes @var
{
ctx
}
using the given @acronym
{
IV
}
. The @var
{
key
}
argument is actually needed only if @var
{
length
}
differs from
@code
{
GCM
_
IV
_
SIZE
}
.
@end deftypefun
@deftypefun void gcm
_
update (struct gcm
_
ctx *@var
{
ctx
}
, const struct gcm
_
key *@var
{
key
}
, unsigned @var
{
length
}
, const uint8
_
t *@var
{
data
}
);
@deftypefun void gcm
_
update (struct gcm
_
ctx *@var
{
ctx
}
, const struct gcm
_
key *@var
{
key
}
, unsigned @var
{
length
}
, const uint8
_
t *@var
{
data
}
)
Provides associated data to be authenticated. If used, must be called
before @code
{
gcm
_
encrypt
}
or @code
{
gcm
_
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
_
encrypt (struct gcm
_
ctx *@var
{
ctx
}
, const struct gcm
_
key *@var
{
key
}
void *@var
{
cipher
}
, nettle
_
crypt
_
func *@var
{
f
}
, unsigned @var
{
length
}
, uint8
_
t *@var
{
dst
}
, const uint8
_
t *@var
{
src
}
);
@deftypefunx void gcm
_
decrypt (struct gcm
_
ctx *@var
{
ctx
}
, const struct gcm
_
key *@var
{
key
}
, void *@var
{
cipher
}
, nettle
_
crypt
_
func *@var
{
f
}
, unsigned @var
{
length
}
, uint8
_
t *@var
{
dst
}
, const uint8
_
t *@var
{
src
}
);
@deftypefun void gcm
_
encrypt (struct gcm
_
ctx *@var
{
ctx
}
, const struct gcm
_
key *@var
{
key
}
void *@var
{
cipher
}
, nettle
_
crypt
_
func *@var
{
f
}
, unsigned @var
{
length
}
, uint8
_
t *@var
{
dst
}
, const uint8
_
t *@var
{
src
}
)
@deftypefunx void gcm
_
decrypt (struct gcm
_
ctx *@var
{
ctx
}
, const struct gcm
_
key *@var
{
key
}
, void *@var
{
cipher
}
, nettle
_
crypt
_
func *@var
{
f
}
, unsigned @var
{
length
}
, uint8
_
t *@var
{
dst
}
, const uint8
_
t *@var
{
src
}
)
Encrypts or decrypts the data of a message. @var
{
cipher
}
is the context
struct for the underlying cipher and @var
{
f
}
is the encryption function.
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
_
digest (struct gcm
_
ctx *@var
{
ctx
}
, const struct gcm
_
key *@var
{
key
}
, void *@var
{
cipher
}
, nettle
_
crypt
_
func *@var
{
f
}
, unsigned @var
{
length
}
, uint8
_
t *@var
{
digest
}
);
@deftypefun void gcm
_
digest (struct gcm
_
ctx *@var
{
ctx
}
, const struct gcm
_
key *@var
{
key
}
, void *@var
{
cipher
}
, nettle
_
crypt
_
func *@var
{
f
}
, unsigned @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.
@end deftypefun
To encrypt a message using @acronym
{
GCM
}
, first initialize a context for
...
...
@@ -1612,10 +1630,100 @@ the above functions in the following order: @code{gcm_set_key},
@code
{
gcm
_
digest
}
. The decryption procedure is analogous, just calling
@code
{
gcm
_
decrypt
}
instead of @code
{
gcm
_
encrypt
}
(note that
@acronym
{
GCM
}
decryption still uses the encryption function of the
underlying block cipher). To process the next message, using the same
key, call @code
{
gcm
_
set
_
iv
}
with a new @acronym
{
iv
}
.
underlying block cipher). To process a new message, using the same key,
call @code
{
gcm
_
set
_
iv
}
with a new @acronym
{
iv
}
.
@subsubsection @acronym
{
GCM
}
helper macros
The following macros are defined.
@deffn Macro GCM
_
CTX (@var
{
context
_
type
}
)
This defines an all-in-one context struct, including the context of the
underlying cipher, the hash subkey, and the per-message state. It expands
to
@example
@
{
context
_
type cipher;
struct gcm
_
key key;
struct gcm
_
ctx gcm;
@
}
@end example
@end deffn
Example use:
@example
struct gcm
_
aes
_
ctx GCM
_
CTX(struct aes
_
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
}
)
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.
@end deffn
@deffn Macro GCM
_
SET
_
IV (@var
{
ctx
}
, @var
{
length
}
, @var
{
data
}
)
First argument is a context struct as defined by
@code
{
GCM
_
CTX
}
. @var
{
length
}
and @var
{
data
}
give the initialization
vector (@acronym
{
IV
}
).
@end deffn
@deffn Macro GCM
_
UPDATE (@var
{
ctx
}
, @var
{
length
}
, @var
{
data
}
)
Simpler way to call @code
{
gcm
_
update
}
. First argument is a context
struct as defined by @code
{
GCM
_
CTX
}
@end deffn
@deffn Macro GCM
_
ENCRYPT (@var
{
ctx
}
, @var
{
encrypt
}
, @var
{
length
}
, @var
{
dst
}
, @var
{
src
}
)
@deffnx Macro GCM
_
DECRYPT (@var
{
ctx
}
, @var
{
encrypt
}
, @var
{
length
}
, @var
{
dst
}
, @var
{
src
}
)
@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.
@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.
@deftp
{
Context struct
}
{
struct gcm
_
aes
_
ctx
}
The context struct, defined using @code
{
GCM
_
CTX
}
.
@end deftp
@deftypefun void gcm
_
aes
_
set
_
key (struct gcm
_
aes
_
ctx *@var
{
ctx
}
, unsigned @var
{
length
}
, const uint8
_
t *@var
{
key
}
)
Initializes @var
{
ctx
}
using the given key. All valid @acronym
{
AES
}
key
sizes can be used.
@end deftypefun
@deftypefun void gcm
_
aes
_
set
_
iv (struct gcm
_
aes
_
ctx *@var
{
ctx
}
, unsigned @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
}
, unsigned @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.
@end deftypefun
@deftypefun void gcm
_
aes
_
encrypt (struct gcm
_
aes
_
ctx *@var
{
ctx
}
, unsigned @var
{
length
}
, uint8
_
t *@var
{
dst
}
, const uint8
_
t *@var
{
src
}
)
@deftypefunx void gcm
_
aes
_
decrypt (struct gcm
_
aes
_
ctx *@var
{
ctx
}
, unsigned @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
_
aes
_
digest (struct gcm
_
aes
_
ctx *@var
{
ctx
}
, unsigned @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.
@end deftypefun
@c XXX
@node Keyed hash functions, Public-key algorithms, Cipher modes, Reference
...
...
@@ -1710,7 +1818,7 @@ Like for @acronym{CBC}, there are some macros to help use these
functions correctly.
@deffn Macro HMAC
_
CTX (@var
{
type
}
)
Expands
in
to
Expands to
@example
@
{
type outer;
...
...
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
