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
Wim Lewis
nettle
Commits
e3e12607
Commit
e3e12607
authored
Apr 25, 2014
by
Owen Kirby
Committed by
Niels Möller
Apr 25, 2014
Browse files
Options
Browse Files
Download
Email Patches
Plain Diff
CCM documentation.
parent
268bc83d
Changes
2
Show whitespace changes
Inline
Side-by-side
Showing
2 changed files
with
244 additions
and
1 deletion
+244
-1
ChangeLog
ChangeLog
+3
-0
nettle.texinfo
nettle.texinfo
+241
-1
No files found.
ChangeLog
View file @
e3e12607
2014-04-25 Niels Möller <nisse@lysator.liu.se>
* nettle.texinfo (CCM): Documentation for CCM mode, contributed by
Owen Kirby.
* testsuite/ccm-test.c (test_cipher_ccm): And tests.
* ccm.c (ccm_decrypt_message): Change length argument, should now
...
...
nettle.texinfo
View file @
e3e12607
...
...
@@ -88,6 +88,7 @@ Cipher modes
* CBC::
* CTR::
* GCM::
* CCM::
Public-key algorithms
...
...
@@ -1816,6 +1817,7 @@ signature to authenticate the message.
* CBC::
* CTR::
* GCM::
* CCM::
@end menu
...
...
@@ -1988,7 +1990,7 @@ last three arguments define the source and destination area for the
operation.
@end deffn
@node GCM,
, CTR, Cipher modes
@node GCM,
CCM
, CTR, Cipher modes
@comment node-name, next, previous, up
@subsection Galois counter mode
...
...
@@ -2181,7 +2183,245 @@ 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
@node CCM, , GCM, Cipher modes
@comment node-name, next, previous, up
@subsection Counter with CBC-MAC mode
@cindex Counter with CBC-MAC Mode
@cindex CCM Mode
CCM mode is the combination of counter mode with message authentication
based on cipher block chaining. It is constructed on top of a block
cipher which must have a block size of 128 bits. @acronym
{
CCM
}
mode is
recommended by NIST in
@uref
{
http://csrc.nist.gov/publications/nistpubs/800-38C/SP800-38C
_
updated-July20
_
2007.pdf,
NIST Special Publication 800-38C
}
. Nettle's support for CCM consists of
a low-level general interface, a message encryption and authentication
interface, and specific functions for CCM using AES as the underlying
block cipher. These interfaces are defined in @file
{
<nettle/ccm.h>
}
The inputs to @acronym
{
CCM
}
are:
@itemize
@item
A key, which can be used for many messages.
@item
A parameter @var
{
L
}
which determines the size of the nonce and the maximum
length of message data which can be processed by @acronym
{
CCM
}
.
@item
A tag length, which must be a multiple of 4 bytes up to a maximum of one block.
@item
A nonce which @emph
{
must
}
be unique for each message.
@item
Optional authenticated data, which is to be included in the message
authentication, but not encrypted.
@item
The plaintext. May be empty.
@end itemize
The outputs from @acronym
{
CCM
}
are:
@itemize
@item
The ciphertext of the same length as the plaintext.
@item
An encrypted authentication tag, up to one block on length.
@end itemize
@c FIXME: Focus on the nonce size, set by the caller.
The parameter @var
{
L
}
determines the size of the counter that is used
for the message length, such that the maximum message length in bytes is
given by @code
{
maxlength = (1 << L) - 1
}
. However increasing @var
{
L
}
also restricts the size of the nonce such that @code
{
noncelength =
CCM
_
BLOCK
_
SIZE - 1 - L
}
, and throughout this interface the parameter
@var
{
L
}
is provided implicitly by the nonce length.
@acronym
{
CCM
}
mode encryption operates as follows:
@itemize
@item The nonce and message length are concatenated to create
@code
{
B
_
0 = flags | nonce | mlength
}
@item The authenticated data and plaintext is formatted into the string
@code
{
B = L(adata) | adata | padding | plaintext | padding
}
with
@code
{
padding
}
being the shortest string of zero bytes such that the
length of the string is a multiple of the block size, and
@code
{
L(adata)
}
is an encoding of the length of @code
{
adata
}
.
@item The string @code
{
B
}
is separated into blocks @code
{
B
_
1
}
...
@code
{
B
_
n
}
@item The authentication tag @code
{
T
}
is calculated as
@code
{
T=0, for i=0 to n, do T = E
_
k(B
_
i XOR T)
}
@item An initial counter is then initialized from the nonce to create
@code
{
IC = flags | nonce | padding
}
, where @code
{
padding
}
is the
shortest string of zero bytes such that @code
{
IC
}
is exactly one block
in length.
@item The authentication tag is encrypted using using @acronym
{
CTR
}
mode:
@code
{
MAC = E
_
k(IC) XOR T
}
@item The plaintext is then encrypted using @acronym
{
CTR
}
mode with an
initial counter of @code
{
IC+1
}
.
@end itemize
@acronym
{
CCM
}
mode decryption operates similarly, except that the
ciphertext and @acronym
{
MAC
}
are first decrypted using CTR mode to
retreive the plaintext and authentication tag. The authentication tag
can then be recalucated from the authenticated data and plantext, and
compared to the value in the message to check for authenticity.
@subsubsection General @acronym
{
CCM
}
interface
For all of the functions in the @acronym
{
CCM
}
interface, @var
{
cipher
}
is
the context struct for the underlying cipher and @var
{
f
}
is the
encryption function. The cipher's encryption key must be set before
calling any of the @acronym
{
CCM
}
functions. The cipher's decryption
function and key are never used.
@deftp
{
Context struct
}
{
struct ccm
_
ctx
}
Holds state corresponding to a particular message.
@end deftp
@defvr Constant CCM
_
BLOCK
_
SIZE
@acronym
{
CCM
}
's block size, 16.
@end defvr
@deftypefun void ccm
_
set
_
nonce (struct ccm
_
ctx *@var
{
ctx
}
, const void *@var
{
cipher
}
, nettle
_
crypt
_
func *@var
{
f
}
, size
_
t @var
{
noncelen
}
, const uint8
_
t *@var
{
nonce
}
, size
_
t @var
{
authlen
}
, size
_
t @var
{
msglen
}
, size
_
t @var
{
taglen
}
)
Initializes @var
{
ctx
}
using the given nonce and the sizes of the
authenticated data, message, and @acronym
{
MAC
}
to be processed.
@end deftypefun
@deftypefun void ccm
_
update (struct ccm
_
ctx *@var
{
ctx
}
, const void *@var
{
cipher
}
, nettle
_
crypt
_
func *@var
{
f
}
, size
_
t @var
{
length
}
, const uint8
_
t *@var
{
data
}
)
Provides associated data to be authenticated. Must be called after
@code
{
ccm
_
set
_
nonce
}
, and before @code
{
ccm
_
encrypt
}
, @code
{
ccm
_
decrypt
}
, or
@code
{
ccm
_
digest
}
.
@end deftypefun
@deftypefun void ccm
_
encrypt (struct ccm
_
ctx *@var
{
ctx
}
, const void *@var
{
cipher
}
, nettle
_
crypt
_
func *@var
{
f
}
, size
_
t @var
{
length
}
, uint8
_
t *@var
{
dst
}
, const uint8
_
t *@var
{
src
}
)
@deftypefunx void ccm
_
decrypt (struct ccm
_
ctx *@var
{
ctx
}
, const void *@var
{
cipher
}
, nettle
_
crypt
_
func *@var
{
f
}
, size
_
t @var
{
length
}
, uint8
_
t *@var
{
dst
}
, const uint8
_
t *@var
{
src
}
)
Encrypts or decrypts the message data. Must be called after
@code
{
ccm
_
set
_
nonce
}
and before @code
{
ccm
_
digest
}
. 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 ccm
_
digest (struct ccm
_
ctx *@var
{
ctx
}
, const void *@var
{
cipher
}
, nettle
_
crypt
_
func *@var
{
f
}
, 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 the @var
{
taglen
}
parameter supplied to @code
{
ccm
_
set
_
nonce
}
,
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 the general @acronym
{
CCM
}
interface, set the
message nonce and length using @code
{
ccm
_
set
_
nonce
}
and then call
@code
{
ccm
_
update
}
to generate the digest of any authenticated data.
After all of the authenticated data has been digested use
@code
{
ccm
_
encrypt
}
to encrypt the plaintext. Finally, use
@code
{
ccm
_
digest
}
to return the encrypted @acronym
{
MAC
}
.
To decrypt a message, use @code
{
ccm
_
set
_
nonce
}
and @code
{
ccm
_
update
}
the
same as you would for encryption, and then call @code
{
ccm
_
decrypt
}
to
decrypt the ciphertext. After decrypting the ciphertext
@code
{
ccm
_
digest
}
will return the encrypted @acronym
{
MAC
}
which should
be identical to the @acronym
{
MAC
}
in the received message.
@subsubsection @acronym
{
CCM
}
message interface
The @acronym
{
CCM
}
message fuctions provides a simple interface that will
perform authentication and message encryption in a single function call.
The length of the cleartext is given by @var
{
mlength
}
and the length of
the ciphertext is given by @var
{
clength
}
, always exactly @var
{
tlength
}
bytes longer than the corresponding plaintext. The length argument
passed to a function is always the size for the result, @var
{
clength
}
for the encryption functions, and @var
{
mlength
}
for the decryption
functions.
@deftypefun void ccm
_
encrypt
_
message (void *@var
{
cipher
}
, nettle
_
crypt
_
func *@var
{
f
}
, size
_
t @var
{
nlength
}
, const uint8
_
t *@var
{
nonce
}
, size
_
t @var
{
alength
}
, const uint8
_
t *@var
{
adata
}
, size
_
t @var
{
tlength
}
, size
_
t @var
{
clength
}
, uint8
_
t *@var
{
dst
}
, const uint8
_
t *@var
{
src
}
)
Computes the message digest from the @var
{
adata
}
and @var
{
src
}
parameters, encrypts the plaintext from @var
{
src
}
, appends the encrypted
@acronym
{
MAC
}
to ciphertext and outputs it to @var
{
dst
}
.
@end deftypefun
@deftypefun int ccm
_
decrypt
_
message (void *@var
{
cipher
}
, nettle
_
crypt
_
func *@var
{
f
}
, size
_
t @var
{
nlength
}
, const uint8
_
t *@var
{
nonce
}
, size
_
t @var
{
alength
}
, const uint8
_
t *@var
{
adata
}
, size
_
t @var
{
tlength
}
, size
_
t @var
{
mlength
}
, uint8
_
t *@var
{
dst
}
, const uint8
_
t *@var
{
src
}
)
Decrypts the ciphertext from @var
{
src
}
, outputs the plaintext to
@var
{
dst
}
, recalculates the @acronym
{
MAC
}
from @var
{
adata
}
and the
plaintext, and compares it to the final @var
{
tlength
}
bytes of
@var
{
src
}
. If the values of the received and calculated @acronym
{
MAC
}
s
are equal, this will return 1 indicating a valid and authenticated
message. Otherwise, this function will return zero.
@end deftypefun
@subsubsection @acronym
{
CCM
}
-@acronym
{
AES
}
interface
The @acronym
{
AES
}
@acronym
{
CCM
}
functions provide an API for using
@acronym
{
CCM
}
mode with the @acronym
{
AES
}
block ciphers. The parameters
all have the same meaning as the general and message interfaces, except
that the @var
{
cipher
}
, @var
{
f
}
, and @var
{
ctx
}
parameters are replaced
with an @acronym
{
AES
}
context structure, and a set-key function must be
called before using any of the other functions in this interface.
@deftp
{
Context struct
}
{
struct ccm
_
aes128
_
ctx
}
Holds state corresponding to a particular message encrypted using the
AES-128 block cipher.
@end deftp
@deftp
{
Context struct
}
{
struct ccm
_
aes192
_
ctx
}
Holds state corresponding to a particular message encrypted using the
AES-192 block cipher.
@end deftp
@deftp
{
Context struct
}
{
struct ccm
_
aes256
_
ctx
}
Holds state corresponding to a particular message encrypted using the
AES-256 block cipher.
@end deftp
@deftypefun void ccm
_
aes128
_
set
_
key (struct ccm
_
aes128
_
ctx *@var
{
ctx
}
, const uint8
_
t *@var
{
key
}
)
@deftypefunx void ccm
_
aes192
_
set
_
key (struct ccm
_
aes192
_
ctx *@var
{
ctx
}
, const uint8
_
t *@var
{
key
}
)
@deftypefunx void ccm
_
aes256
_
set
_
key (struct ccm
_
aes256
_
ctx *@var
{
ctx
}
, const uint8
_
t *@var
{
key
}
)
Initializes the encryption key for the AES block cipher. One of these
functions must be called before any of the other functions in the
@acronym
{
AES
}
@acronym
{
CCM
}
interface.
@end deftypefun
@deftypefun void ccm
_
aes128
_
set
_
nonce (struct ccm
_
aes128
_
ctx *@var
{
ctx
}
, size
_
t @var
{
noncelen
}
, const uint8
_
t *@var
{
nonce
}
, size
_
t @var
{
authlen
}
, size
_
t @var
{
msglen
}
, size
_
t @var
{
taglen
}
)
@deftypefunx void ccm
_
aes192
_
set
_
nonce (struct ccm
_
aes192
_
ctx *@var
{
ctx
}
, size
_
t @var
{
noncelen
}
, const uint8
_
t *@var
{
nonce
}
, size
_
t @var
{
authlen
}
, size
_
t @var
{
msglen
}
, size
_
t @var
{
taglen
}
)
@deftypefunx void ccm
_
aes256
_
set
_
nonce (struct ccm
_
aes256
_
ctx *@var
{
ctx
}
, size
_
t @var
{
noncelen
}
, const uint8
_
t *@var
{
nonce
}
, size
_
t @var
{
authlen
}
, size
_
t @var
{
msglen
}
, size
_
t @var
{
taglen
}
)
These are identical to @code
{
ccm
_
set
_
nonce
}
, except that @var
{
cipher
}
,
@var
{
f
}
, and @var
{
ctx
}
are replaced with a context structure.
@end deftypefun
@deftypefun void ccm
_
aes128
_
update (struct ccm
_
aes128
_
ctx *@var
{
ctx
}
, size
_
t @var
{
length
}
, const uint8
_
t *@var
{
data
}
)
@deftypefunx void ccm
_
aes192
_
update (struct ccm
_
aes192
_
ctx *@var
{
ctx
}
, size
_
t @var
{
length
}
, const uint8
_
t *@var
{
data
}
)
@deftypefunx void ccm
_
aes256
_
update (struct ccm
_
aes256
_
ctx *@var
{
ctx
}
, size
_
t @var
{
length
}
, const uint8
_
t *@var
{
data
}
)
These are identical to @code
{
ccm
_
set
_
update
}
, except that @var
{
cipher
}
,
@var
{
f
}
, and @var
{
ctx
}
are replaced with a context structure.
@end deftypefun
@deftypefun void ccm
_
aes128
_
encrypt (struct ccm
_
aes128
_
ctx *@var
{
ctx
}
, size
_
t @var
{
length
}
, uint8
_
t *@var
{
dst
}
, const uint8
_
t *@var
{
src
}
)
@deftypefunx void ccm
_
aes192
_
encrypt (struct ccm
_
aes192
_
ctx *@var
{
ctx
}
, size
_
t @var
{
length
}
, uint8
_
t *@var
{
dst
}
, const uint8
_
t *@var
{
src
}
)
@deftypefunx void ccm
_
aes256
_
encrypt (struct ccm
_
aes256
_
ctx *@var
{
ctx
}
, size
_
t @var
{
length
}
, uint8
_
t *@var
{
dst
}
, const uint8
_
t *@var
{
src
}
)
@deftypefunx void ccm
_
aes128
_
decrypt (struct ccm
_
aes128
_
ctx *@var
{
ctx
}
, size
_
t @var
{
length
}
, uint8
_
t *@var
{
dst
}
, const uint8
_
t *@var
{
src
}
)
@deftypefunx void ccm
_
aes192
_
decrypt (struct ccm
_
aes192
_
ctx *@var
{
ctx
}
, size
_
t @var
{
length
}
, uint8
_
t *@var
{
dst
}
, const uint8
_
t *@var
{
src
}
)
@deftypefunx void ccm
_
aes256
_
decrypt (struct ccm
_
aes256
_
ctx *@var
{
ctx
}
, size
_
t @var
{
length
}
, uint8
_
t *@var
{
dst
}
, const uint8
_
t *@var
{
src
}
)
These are identical to @code
{
ccm
_
set
_
encrypt
}
and @code
{
ccm
_
set
_
decrypt
}
, except
that @var
{
cipher
}
, @var
{
f
}
, and @var
{
ctx
}
are replaced with a context structure.
@end deftypefun
@deftypefun void ccm
_
aes128
_
digest (struct ccm
_
aes128
_
ctx *@var
{
ctx
}
, size
_
t @var
{
length
}
, uint8
_
t *@var
{
digest
}
)
@deftypefunx void ccm
_
aes192
_
digest (struct ccm
_
aes192
_
ctx *@var
{
ctx
}
, size
_
t @var
{
length
}
, uint8
_
t *@var
{
digest
}
)
@deftypefunx void ccm
_
aes256
_
digest (struct ccm
_
aes256
_
ctx *@var
{
ctx
}
, size
_
t @var
{
length
}
, uint8
_
t *@var
{
digest
}
)
These are identical to @code
{
ccm
_
set
_
digest
}
, except that @var
{
cipher
}
,
@var
{
f
}
, and @var
{
ctx
}
are replaced with a context structure.
@end deftypefun
@deftypefun void ccm
_
aes128
_
encrypt
_
message (struct ccm
_
aes128
_
ctx *@var
{
ctx
}
, size
_
t @var
{
nlength
}
, const uint8
_
t *@var
{
nonce
}
, size
_
t @var
{
alength
}
, const uint8
_
t *@var
{
adata
}
, size
_
t @var
{
tlength
}
, size
_
t @var
{
clength
}
, uint8
_
t *@var
{
dst
}
, const uint8
_
t *@var
{
src
}
)
@deftypefunx void ccm
_
aes192
_
encrypt
_
message (struct ccm
_
aes192
_
ctx *@var
{
ctx
}
, size
_
t @var
{
nlength
}
, const uint8
_
t *@var
{
nonce
}
, size
_
t @var
{
alength
}
, const uint8
_
t *@var
{
adata
}
, size
_
t @var
{
tlength
}
, size
_
t @var
{
clength
}
, uint8
_
t *@var
{
dst
}
, const uint8
_
t *@var
{
src
}
)
@deftypefunx void ccm
_
aes256
_
encrypt
_
message (struct ccm
_
aes256
_
ctx *@var
{
ctx
}
, size
_
t @var
{
nlength
}
, const uint8
_
t *@var
{
nonce
}
, size
_
t @var
{
alength
}
, const uint8
_
t *@var
{
adata
}
, size
_
t @var
{
tlength
}
, size
_
t @var
{
clength
}
, uint8
_
t *@var
{
dst
}
, const uint8
_
t *@var
{
src
}
)
@deftypefunx int ccm
_
aes128
_
decrypt
_
message (struct ccm
_
aes128
_
ctx *@var
{
ctx
}
, size
_
t @var
{
nlength
}
, const uint8
_
t *@var
{
nonce
}
, size
_
t @var
{
alength
}
, const uint8
_
t *@var
{
adata
}
, size
_
t @var
{
tlength
}
, size
_
t @var
{
mlength
}
, uint8
_
t *@var
{
dst
}
, const uint8
_
t *@var
{
src
}
)
@deftypefunx int ccm
_
aes192
_
decrypt
_
message (struct ccm
_
aes192
_
ctx *@var
{
ctx
}
, size
_
t @var
{
nlength
}
, const uint8
_
t *@var
{
nonce
}
, size
_
t @var
{
alength
}
, const uint8
_
t *@var
{
adata
}
, size
_
t @var
{
tlength
}
, size
_
t @var
{
mlength
}
, uint8
_
t *@var
{
dst
}
, const uint8
_
t *@var
{
src
}
)
@deftypefunx int ccm
_
aes192
_
decrypt
_
message (struct ccm
_
aes256
_
ctx *@var
{
ctx
}
, size
_
t @var
{
nlength
}
, const uint8
_
t *@var
{
nonce
}
, size
_
t @var
{
alength
}
, const uint8
_
t *@var
{
adata
}
, size
_
t @var
{
tlength
}
, size
_
t @var
{
mlength
}
, uint8
_
t *@var
{
dst
}
, const uint8
_
t *@var
{
src
}
)
These are identical to @code
{
ccm
_
encrypt
_
message
}
and @code
{
ccm
_
decrypt
_
message
}
except that @var
{
cipher
}
and @var
{
f
}
are replaced with a context structure.
@end deftypefun
@node Keyed hash functions, Key derivation functions, Cipher modes, Reference
@comment node-name, next, previous, up
...
...
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
