diff options
author | Niels Möller <nisse@lysator.liu.se> | 2023-04-21 14:53:33 +0200 |
---|---|---|
committer | Niels Möller <nisse@lysator.liu.se> | 2023-04-21 14:53:33 +0200 |
commit | 9226b48545080885acd4b4bf4acfc4f2f583db0e (patch) | |
tree | 2699598e7d6623c6e7d20c77c23bc5be3f5b54a8 | |
parent | b144b629a2b841f0800ffe27af52b692708fe0e5 (diff) | |
download | nettle-9226b48545080885acd4b4bf4acfc4f2f583db0e.tar.gz |
Document OCB support.
-rw-r--r-- | nettle.texinfo | 176 |
1 files changed, 176 insertions, 0 deletions
diff --git a/nettle.texinfo b/nettle.texinfo index b12955c0..e26d7187 100644 --- a/nettle.texinfo +++ b/nettle.texinfo @@ -2880,6 +2880,7 @@ more adventurous alternative, in particular if performance is important. * GCM:: * CCM:: * ChaCha-Poly1305:: +* OCB:: * SIV-CMAC:: * SIV-GCM:: * nettle_aead abstraction:: @@ -3641,6 +3642,181 @@ smaller than @code{CHACHA_POLY1305_DIGEST_SIZE}, only the first @var{length} octets of the digest are written. @end deftypefun +@node OCB +@subsection @acronym{OCB} (Offset Code Book) Mode + +@cindex OCB +@cindex OCB mode +@cindex Offset Code Book + +The @acronym{OCB} mode is an @acronym{AEAD} construction, featuring +particularly fast and simple authentication; it needs one block cipher +operation per data block, and almost free authentication. It is +constructed on top of a block cipher which must have a block size of 128 +bits. + +There have been several versions of the OCB scheme, the implementation +in Nettle follows @cite{RFC 7253}, which is almost the same as the +scheme OCB3. + +@subsubsection General interface + +@deftp {Context struct} {struct ocb_key} +@acronym{OCB} state which depends only on the key, but not on the nonce +or the message. +@end deftp + +@deftp {Context struct} {struct ocb_ctx} +Holds state corresponding to a particular message. +@end deftp + +@defvr Constant OCB_BLOCK_SIZE +The block size for @acronym{OCB}'s block size, 16. +@end defvr + +@defvr Constant OCB_MAX_NONCE_SIZE +The maximum nonce size for @acronym{OCB}, 15. +@end defvr + +@defvr Constant OCB_DIGEST_SIZE +Size of the @acronym{OCB} authentication tag. +@end defvr + +@deftypefun void ocb_set_key (struct ocb_key *@var{key}, const void *@var{cipher}, nettle_cipher_func *@var{f}) +Initializes the @var{key} struct. The @var{cipher} context must be +initialized for encryption, and @var{f} should be the corresponding +encryption function. +@end deftypefun + +@deftypefun void ocb_set_nonce (struct ocb_ctx *@var{ctx}, const void *@var{cipher}, nettle_cipher_func *@var{f}, size_t @var{tag_length}, size_t @var{nonce_length}, const uint8_t *@var{nonce}) +Initializes @var{ctx} for processing a new message, using the given +nonce. The @var{cipher} must be initialized for encryption, and @var{f} +should be the corresponding encryption function. The @var{tag_length} +(non-zero, and at most 16) is included when initializing the state, and +should be the same value later passed to @code{ocb_digest}. Nonce is +optional, and length at most 15 bytes. +@end deftypefun + +@deftypefun void ocb_update (struct ocb_ctx *@var{ctx}, const struct ocb_key *@var{key}, const void *@var{cipher}, nettle_cipher_func *@var{f}, size_t @var{length}, const uint8_t *@var{data}) +Process associated data for authentication. 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 ocb_encrypt (struct ocb_ctx *@var{ctx}, const struct ocb_key *@var{key}, const void *@var{cipher}, nettle_cipher_func *@var{f}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) +Encrypts 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 ocb_decrypt (struct ocb_ctx *@var{ctx}, const struct ocb_key *@var{key}, const void *@var{encrypt_ctx}, nettle_cipher_func *@var{encrypt}, const void *@var{decrypt_ctx}, nettle_cipher_func *@var{decrypt}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) +Decrypts the data of a message. @var{encrypt_ctx} and @var{encrypt} +define the encryption operation of the underlying cipher, while +@var{decrypt_ctx} and @var{decrypt} represent the decryption operation +(for some ciphers, one of context pointer and function pointer may be +the same). 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 ocb_digest (const struct ocb_ctx *@var{ctx}, const struct ocb_key *@var{key}, const void *@var{cipher}, nettle_cipher_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. The @var{length} value +@emph{should} be the same as the tag length passed to the preceding +@code{ocb_set_nonce} call (using a different length is possible, but +incompatible with @cite{RFC 7253}). +@end deftypefun + +@deftypefun void ocb_encrypt_message (const struct ocb_key *@var{ocb_key}, const void *@var{cipher}, nettle_cipher_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 tag to +the ciphertext and writes it to @var{dst}. The @var{clength} variable +must be equal to the length of @var{src} plus @var{tlength}. +@end deftypefun + +@deftypefun int ocb_decrypt_message (const struct ocb_key *@var{ocb_key}, const void *@var{encrypt_ctx}, nettle_cipher_func *@var{encrypt}, const void *@var{decrypt_ctx}, nettle_cipher_func *@var{decrypt}, 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}. Like @code{ocb_decrypt}, it needs both the encrypt and the +decrypt function of the underlying cipher. It also recalculates the +authentication tag 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 tags are equal, this will return 1 indicating a +valid and authenticated message. Otherwise, this function will return +zero. +@end deftypefun + +@subsubsection @acronym{OCB-AES} interface + + +@deftp {Context struct} {struct ocb_aes128_encrypt_key} +Key-dependent state for encryption using @acronym{OCB-AES128}. For +decryption, a separate @code{struct aes128_ctx}, initialized for +decryption, is needed as well. +@end deftp + +@deftypefun void ocb_aes128_set_encrypt_key (struct ocb_aes128_encrypt_key *@var{ocb}, const uint8_t *@var{key}) +Initializes @var{ocb} and the underlying AES cipher with the given key. +@end deftypefun + +@deftypefun void ocb_aes128_set_decrypt_key (struct ocb_aes128_encrypt_key *@var{ocb}, struct aes128_ctx *@var{decrypt}, const uint8_t *@var{key}) +Initializes @var{ocb} and the underlying AES cipher with the given key. +In addition, initialize @var{decrypt} for decryption using the same key; +this is needed for @code{ocb_aes128_decrypt} and +@code{ocb_aes128_decrypt_message}. +@end deftypefun + +@deftypefun void ocb_aes128_set_nonce (struct ocb_ctx *@var{ctx}, const struct ocb_aes128_encrypt_key *@var{key}, size_t @var{tag_length}, size_t @var{nonce_length}, const uint8_t *@var{nonce}) +Initializes @var{ctx} for processing a new message, using the given +nonce and key. The @var{tag_length} (non-zero, and at most 16) is +included when initializing the state, and should be the same value later +passed to @code{ocb_digest}. Nonce is optional, and length at most 15 +bytes. +@end deftypefun + +@deftypefun void ocb_aes128_update (struct ocb_ctx *@var{ctx}, const struct ocb_aes128_encrypt_key *@var{key}, size_t @var{length}, const uint8_t *@var{data}) +Process associated data for authentication. 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 ocb_aes128_encrypt(struct ocb_ctx *@var{ctx}, const struct ocb_aes128_encrypt_key *@var{key}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) +Encrypts 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 ocb_aes128_decrypt(struct ocb_ctx *@var{ctx}, const struct ocb_aes128_encrypt_key *@var{key}, const struct aes128_ctx *@var{decrypt}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) +Decrypts the data of a message. @var{decrypt} is an AES context +initialized for decryption using the same key. 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 ocb_aes128_digest(struct ocb_ctx *@var{ctx}, const struct ocb_aes128_encrypt_key *@var{key}, 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. The @var{length} value +@emph{should} be the same as the tag length passed to the preceding +@code{ocb_set_nonce} call (using a different length is possible, but +incompatible with @cite{RFC 7253}). +@end deftypefun + +@deftypefun void ocb_aes128_encrypt_message (const struct ocb_aes128_encrypt_key *@var{key}, 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 tag to +the ciphertext and writes it to @var{dst}. The @var{clength} variable +must be equal to the length of @var{src} plus @var{tlength}. +@end deftypefun + +@deftypefun int ocb_aes128_decrypt_message (const struct ocb_aes128_encrypt_key *@var{key}, const struct aes128_ctx *@var{decrypt}, 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}. Like @code{ocb_aes128_decrypt}, it needs an AES context +initialized for decryption using the same key. It also recalculates the +authentication tag 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 tags are equal, this will return 1 indicating a +valid and authenticated message. Otherwise, this function will return +zero. +@end deftypefun + @node SIV-CMAC @subsection Synthetic Initialization Vector AEAD |