Document OCB support.

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