nettle: GCM
1
1 6.4.2 Galois counter mode
1 -------------------------
1
1 Galois counter mode is an AEAD constructions combining counter mode with
1 message authentication based on universal hashing. The main objective
1 of the design is to provide high performance for hardware
1 functions::) become a bottleneck for high-speed hardware
1 implementations. It was proposed by David A. McGrew and John Viega in
1 2005, and recommended by NIST in 2007, NIST Special Publication 800-38D
1 (http://csrc.nist.gov/publications/nistpubs/800-38D/SP-800-38D.pdf). It
1 is constructed on top of a block cipher which must have a block size of
1 128 bits.
1
1 The authentication in GCM has some known weaknesses, see
1 <http://csrc.nist.gov/groups/ST/toolkit/BCM/documents/comments/CWC-GCM/Ferguson2.pdf>.
1 In particular, don’t use GCM with short authentication tags.
1
1 Nettle’s support for GCM consists of a low-level general interface,
1 some convenience macros, and specific functions for GCM using AES or
1 Camellia as the underlying cipher. These interfaces are defined in
1 ‘<nettle/gcm.h>’
1
1 6.4.2.1 General GCM interface
1 .............................
1
1 -- Context struct: struct gcm_key
1 Message independent hash sub-key, and related tables.
1
1 -- Context struct: struct gcm_ctx
1 Holds state corresponding to a particular message.
1
1 -- Constant: GCM_BLOCK_SIZE
1 GCM’s block size, 16.
1
1 -- Constant: GCM_DIGEST_SIZE
1 Size of the GCM digest, also 16.
1
1 -- Constant: GCM_IV_SIZE
1 Recommended size of the IV, 12. Arbitrary sizes are allowed.
1
1 -- Function: void gcm_set_key (struct gcm_key *KEY, const void *CIPHER,
1 nettle_cipher_func *F)
1 Initializes KEY. CIPHER gives a context struct for the underlying
1 cipher, which must have been previously initialized for encryption,
1 and F is the encryption function.
1
1 -- Function: void gcm_set_iv (struct gcm_ctx *CTX, const struct gcm_key
1 *KEY, size_t LENGTH, const uint8_t *IV)
1 Initializes CTX using the given IV. The KEY argument is actually
1 needed only if LENGTH differs from ‘GCM_IV_SIZE’.
1
1 -- Function: void gcm_update (struct gcm_ctx *CTX, const struct gcm_key
1 *KEY, size_t LENGTH, const uint8_t *DATA)
1 Provides associated data to be authenticated. If used, must be
1 called before ‘gcm_encrypt’ or ‘gcm_decrypt’. All but the last
1 call for each message _must_ use a length that is a multiple of the
1 block size.
1
1 -- Function: void gcm_encrypt (struct gcm_ctx *CTX, const struct
1 gcm_key *KEY, const void *CIPHER, nettle_cipher_func *F,
1 size_t LENGTH, uint8_t *DST, const uint8_t *SRC)
1 -- Function: void gcm_decrypt (struct gcm_ctx *CTX, const struct
1 gcm_key *KEY, const void *CIPHER, nettle_cipher_func *F,
1 size_t LENGTH, uint8_t *DST, const uint8_t *SRC)
1 Encrypts or decrypts the data of a message. CIPHER is the context
1 struct for the underlying cipher and F is the encryption function.
1 All but the last call for each message _must_ use a length that is
1 a multiple of the block size.
1
1 -- Function: void gcm_digest (struct gcm_ctx *CTX, const struct gcm_key
1 *KEY, const void *CIPHER, nettle_cipher_func *F, size_t
1 LENGTH, uint8_t *DIGEST)
1 Extracts the message digest (also known “authentication tag”).
1 This is the final operation when processing a message. It’s
1 strongly recommended that LENGTH is ‘GCM_DIGEST_SIZE’, but if you
1 provide a smaller value, only the first LENGTH octets of the digest
1 are written.
1
1 To encrypt a message using GCM, first initialize a context for the
1 underlying block cipher with a key to use for encryption. Then call the
1 above functions in the following order: ‘gcm_set_key’, ‘gcm_set_iv’,
1 ‘gcm_update’, ‘gcm_encrypt’, ‘gcm_digest’. The decryption procedure is
1 analogous, just calling ‘gcm_decrypt’ instead of ‘gcm_encrypt’ (note
1 that GCM decryption still uses the encryption function of the underlying
1 block cipher). To process a new message, using the same key, call
1 ‘gcm_set_iv’ with a new iv.
1
1 6.4.2.2 GCM helper macros
1 .........................
1
1 The following macros are defined.
1
1 -- Macro: GCM_CTX (CONTEXT_TYPE)
1 This defines an all-in-one context struct, including the context of
1 the underlying cipher, the hash sub-key, and the per-message state.
1 It expands to
1 {
1 struct gcm_key key;
1 struct gcm_ctx gcm;
1 context_type cipher;
1 }
1
1 Example use:
1 struct gcm_aes128_ctx GCM_CTX(struct aes128_ctx);
1
1 The following macros operate on context structs of this form.
1
1 -- Macro: GCM_SET_KEY (CTX, SET_KEY, ENCRYPT, KEY)
1 First argument, CTX, is a context struct as defined by ‘GCM_CTX’.
1 SET_KEY and ENCRYPT are functions for setting the encryption key
1 and for encrypting data using the underlying cipher.
1
1 -- Macro: GCM_SET_IV (CTX, LENGTH, DATA)
1 First argument is a context struct as defined by ‘GCM_CTX’. LENGTH
1 and DATA give the initialization vector (IV).
1
1 -- Macro: GCM_UPDATE (CTX, LENGTH, DATA)
1 Simpler way to call ‘gcm_update’. First argument is a context
1 struct as defined by ‘GCM_CTX’
1
1 -- Macro: GCM_ENCRYPT (CTX, ENCRYPT, LENGTH, DST, SRC)
1 -- Macro: GCM_DECRYPT (CTX, ENCRYPT, LENGTH, DST, SRC)
1 -- Macro: GCM_DIGEST (CTX, ENCRYPT, LENGTH, DIGEST)
1 Simpler way to call ‘gcm_encrypt’, ‘gcm_decrypt’ or ‘gcm_digest’.
1 First argument is a context struct as defined by ‘GCM_CTX’. Second
1 argument, ENCRYPT, is the encryption function of the underlying
1 cipher.
1
1 6.4.2.3 GCM-AES interface
1 .........................
1
1 The following functions implement the common case of GCM using AES as
1 the underlying cipher. The variants with a specific AES flavor are
1 recommended, while the fucntinos using ‘struct gcm_aes_ctx’ are kept for
1 compatibility with older versiosn of Nettle.
1
1 -- Context struct: struct gcm_aes128_ctx
1 -- Context struct: struct gcm_aes192_ctx
1 -- Context struct: struct gcm_aes256_ctx
1 Context structs, defined using ‘GCM_CTX’.
1
1 -- Context struct: struct gcm_aes_ctx
1 Alternative context struct, usign the old AES interface.
1
1 -- Function: void gcm_aes128_set_key (struct gcm_aes128_ctx *CTX, const
1 uint8_t *KEY)
1 -- Function: void gcm_aes192_set_key (struct gcm_aes192_ctx *CTX, const
1 uint8_t *KEY)
1 -- Function: void gcm_aes256_set_key (struct gcm_aes256_ctx *CTX, const
1 uint8_t *KEY)
1 Initializes CTX using the given key.
1
1 -- Function: void gcm_aes_set_key (struct gcm_aes_ctx *CTX, size_t
1 LENGTH, const uint8_t *KEY)
1 Corresponding function, using the old AES interface. All valid AES
1 key sizes can be used.
1
1 -- Function: void gcm_aes128_set_iv (struct gcm_aes128_ctx *CTX, size_t
1 LENGTH, const uint8_t *IV)
1 -- Function: void gcm_aes192_set_iv (struct gcm_aes192_ctx *CTX, size_t
1 LENGTH, const uint8_t *IV)
1 -- Function: void gcm_aes256_set_iv (struct gcm_aes256_ctx *CTX, size_t
1 LENGTH, const uint8_t *IV)
1 -- Function: void gcm_aes_set_iv (struct gcm_aes_ctx *CTX, size_t
1 LENGTH, const uint8_t *IV)
1 Initializes the per-message state, using the given IV.
1
1 -- Function: void gcm_aes128_update (struct gcm_aes128_ctx *CTX, size_t
1 LENGTH, const uint8_t *DATA)
1 -- Function: void gcm_aes192_update (struct gcm_aes192_ctx *CTX, size_t
1 LENGTH, const uint8_t *DATA)
1 -- Function: void gcm_aes256_update (struct gcm_aes256_ctx *CTX, size_t
1 LENGTH, const uint8_t *DATA)
1 -- Function: void gcm_aes_update (struct gcm_aes_ctx *CTX, size_t
1 LENGTH, const uint8_t *DATA)
1 Provides associated data to be authenticated. If used, must be
1 called before ‘gcm_aes_encrypt’ or ‘gcm_aes_decrypt’. All but the
1 last call for each message _must_ use a length that is a multiple
1 of the block size.
1
1 -- Function: void gcm_aes128_encrypt (struct gcm_aes128_ctx *CTX,
1 size_t LENGTH, uint8_t *DST, const uint8_t *SRC)
1 -- Function: void gcm_aes192_encrypt (struct gcm_aes192_ctx *CTX,
1 size_t LENGTH, uint8_t *DST, const uint8_t *SRC)
1 -- Function: void gcm_aes256_encrypt (struct gcm_aes256_ctx *CTX,
1 size_t LENGTH, uint8_t *DST, const uint8_t *SRC)
1 -- Function: void gcm_aes_encrypt (struct gcm_aes_ctx *CTX, size_t
1 LENGTH, uint8_t *DST, const uint8_t *SRC)
1 -- Function: void gcm_aes128_decrypt (struct gcm_aes128_ctx *CTX,
1 size_t LENGTH, uint8_t *DST, const uint8_t *SRC)
1 -- Function: void gcm_aes192_decrypt (struct gcm_aes192_ctx *CTX,
1 size_t LENGTH, uint8_t *DST, const uint8_t *SRC)
1 -- Function: void gcm_aes256_decrypt (struct gcm_aes256_ctx *CTX,
1 size_t LENGTH, uint8_t *DST, const uint8_t *SRC)
1 -- Function: void gcm_aes_decrypt (struct gcm_aes_ctx *CTX, size_t
1 LENGTH, uint8_t *DST, const uint8_t *SRC)
1 Encrypts or decrypts the data of a message. All but the last call
1 for each message _must_ use a length that is a multiple of the
1 block size.
1
1 -- Function: void gcm_aes128_digest (struct gcm_aes128_ctx *CTX, size_t
1 LENGTH, uint8_t *DIGEST)
1 -- Function: void gcm_aes192_digest (struct gcm_aes192_ctx *CTX, size_t
1 LENGTH, uint8_t *DIGEST)
1 -- Function: void gcm_aes256_digest (struct gcm_aes256_ctx *CTX, size_t
1 LENGTH, uint8_t *DIGEST)
1 -- Function: void gcm_aes_digest (struct gcm_aes_ctx *CTX, size_t
1 LENGTH, uint8_t *DIGEST)
1 Extracts the message digest (also known “authentication tag”).
1 This is the final operation when processing a message. It’s
1 strongly recommended that LENGTH is ‘GCM_DIGEST_SIZE’, but if you
1 provide a smaller value, only the first LENGTH octets of the digest
1 are written.
1
1 6.4.2.4 GCM-Camellia interface
1 ..............................
1
1 The following functions implement the case of GCM using Camellia as the
1 underlying cipher.
1
1 -- Context struct: struct gcm_camellia128_ctx
1 -- Context struct: struct gcm_camellia256_ctx
1 Context structs, defined using ‘GCM_CTX’.
1
1 -- Function: void gcm_camellia128_set_key (struct gcm_camellia128_ctx
1 *CTX, const uint8_t *KEY)
1 -- Function: void gcm_camellia256_set_key (struct gcm_camellia256_ctx
1 *CTX, const uint8_t *KEY)
1 Initializes CTX using the given key.
1
1 -- Function: void gcm_camellia128_set_iv (struct gcm_camellia128_ctx
1 *CTX, size_t LENGTH, const uint8_t *IV)
1 -- Function: void gcm_camellia256_set_iv (struct gcm_camellia256_ctx
1 *CTX, size_t LENGTH, const uint8_t *IV)
1 Initializes the per-message state, using the given IV.
1
1 -- Function: void gcm_camellia128_update (struct gcm_camellia128_ctx
1 *CTX, size_t LENGTH, const uint8_t *DATA)
1 -- Function: void gcm_camellia256_update (struct gcm_camellia256_ctx
1 *CTX, size_t LENGTH, const uint8_t *DATA)
1 Provides associated data to be authenticated. If used, must be
1 called before ‘gcm_camellia_encrypt’ or ‘gcm_camellia_decrypt’.
1 All but the last call for each message _must_ use a length that is
1 a multiple of the block size.
1
1 -- Function: void gcm_camellia128_encrypt (struct gcm_camellia128_ctx
1 *CTX, size_t LENGTH, uint8_t *DST, const uint8_t *SRC)
1 -- Function: void gcm_camellia256_encrypt (struct gcm_camellia256_ctx
1 *CTX, size_t LENGTH, uint8_t *DST, const uint8_t *SRC)
1 -- Function: void gcm_camellia128_decrypt (struct gcm_camellia128_ctx
1 *CTX, size_t LENGTH, uint8_t *DST, const uint8_t *SRC)
1 -- Function: void gcm_camellia256_decrypt (struct gcm_camellia256_ctx
1 *CTX, size_t LENGTH, uint8_t *DST, const uint8_t *SRC)
1 Encrypts or decrypts the data of a message. All but the last call
1 for each message _must_ use a length that is a multiple of the
1 block size.
1
1 -- Function: void gcm_camellia128_digest (struct gcm_camellia128_ctx
1 *CTX, size_t LENGTH, uint8_t *DIGEST)
1 -- Function: void gcm_camellia192_digest (struct gcm_camellia192_ctx
1 *CTX, size_t LENGTH, uint8_t *DIGEST)
1 -- Function: void gcm_camellia256_digest (struct gcm_camellia256_ctx
1 *CTX, size_t LENGTH, uint8_t *DIGEST)
1 -- Function: void gcm_camellia_digest (struct gcm_camellia_ctx *CTX,
1 size_t LENGTH, uint8_t *DIGEST)
1 Extracts the message digest (also known “authentication tag”).
1 This is the final operation when processing a message. It’s
1 strongly recommended that LENGTH is ‘GCM_DIGEST_SIZE’, but if you
1 provide a smaller value, only the first LENGTH octets of the digest
1 are written.
1