Skip to content
GitLab
Projects
Groups
Snippets
/
Help
Help
Support
Community forum
Keyboard shortcuts
?
Submit feedback
Contribute to GitLab
Sign in / Register
Toggle navigation
Menu
Open sidebar
Dmitry Baryshkov
nettle
Commits
7d6686af
Commit
7d6686af
authored
Feb 16, 2011
by
Niels Möller
Browse files
Fleshed out section on gcm.
Rev: nettle/nettle.texinfo:1.18
parent
1dd087d0
Changes
1
Hide whitespace changes
Inline
Side-by-side
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
Supports
Markdown
0%
Try again
or
attach a new 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
