Add documentation for OCB mode

Reviewed-by: Tim Hudson <tjh@openssl.org>

diff --git a/doc/crypto/EVP_EncryptInit.pod b/doc/crypto/EVP_EncryptInit.pod
index ea166bf6fbab358cd81ce88c5d2ffe1c55550a53..524921f834cf21a3d82351c228f8b32c2e2b53d3 100644 (file)
--- a/doc/crypto/EVP_EncryptInit.pod
+++ b/doc/crypto/EVP_EncryptInit.pod
@@ -368,7 +368,13 @@ bits and 12 rounds.
 
 AES Galois Counter Mode (GCM) for 128, 192 and 256 bit keys respectively.
 These ciphers require additional control operations to function correctly: see
-L<GCM mode> section below for details.
+the L<GCM and OCB modes> section below for details.
+
+=item EVP_aes_128_ocb(void), EVP_aes_192_ocb(void), EVP_aes_256_ocb(void)
+
+Offest Codebook Mode (OCB) for 128, 192 and 256 bit keys respectively.
+These ciphers require additional control operations to function correctly: see
+the L<GCM and OCB modes> section below for details.
 
 =item EVP_aes_128_ccm(), EVP_aes_192_ccm(), EVP_aes_256_ccm()
 
@@ -378,10 +384,10 @@ CCM mode section below for details.
 
 =back
 
-=head1 GCM Mode
+=head1 GCM and OCB Modes
 
-For GCM mode ciphers the behaviour of the EVP interface is subtly altered and
-several GCM specific ctrl operations are supported.
+For GCM and OCB mode ciphers the behaviour of the EVP interface is subtly
+altered and several additional ctrl operations are supported.
 
 To specify any additional authenticated data (AAD) a call to EVP_CipherUpdate(),
 EVP_EncryptUpdate() or EVP_DecryptUpdate() should be made with the output
@@ -392,24 +398,35 @@ indicates if the operation was successful. If it does not indicate success
 the authentication operation has failed and any output data B<MUST NOT>
 be used as it is corrupted.
 
-The following ctrls are supported in GCM mode:
+The following ctrl is supported in OCB mode only:
+
+ EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_OCB_SET_TAGLEN, taglen, NULL);
+
+Sets the tag length: this call can only be made before specifying an IV. If
+not called a default tag length is used. For OCB AES the default is 16 (i.e. 128
+bits). This is also the maximum tag length.
+
+The following ctrls are supported in both GCM and OCB modes:
 
- EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GCM_SET_IVLEN, ivlen, NULL);
+ EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_SET_IVLEN, ivlen, NULL);
 
-Sets the GCM IV length: this call can only be made before specifying an IV. If
-not called a default IV length is used (96 bits for AES).
+Sets the IV length: this call can only be made before specifying an IV. If
+not called a default IV length is used. For GCM AES and OCB AES the default is
+12 (i.e. 96 bits). For OCB mode the maximum is 15.
 
- EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GCM_GET_TAG, taglen, tag);
+ EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GET_TAG, taglen, tag);
 
 Writes B<taglen> bytes of the tag value to the buffer indicated by B<tag>.
 This call can only be made when encrypting data and B<after> all data has been
-processed (e.g. after an EVP_EncryptFinal() call).
+processed (e.g. after an EVP_EncryptFinal() call). For OCB mode the taglen must
+either be 16 or the value previously set via EVP_CTRL_OCB_SET_TAGLEN.
 
- EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GCM_SET_TAG, taglen, tag);
+ EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_SET_TAG, taglen, tag);
 
 Sets the expected tag to B<taglen> bytes from B<tag>. This call is only legal
 when decrypting data and must be made B<before> any data is processed (e.g.
-before any EVP_DecryptUpdate() call).
+before any EVP_DecryptUpdate() call). For OCB mode the taglen must
+either be 16 or the value previously set via EVP_CTRL_OCB_SET_TAGLEN.
 
 See L<EXAMPLES> below for an example of the use of GCM mode.
 
@@ -418,7 +435,7 @@ See L<EXAMPLES> below for an example of the use of GCM mode.
 The behaviour of CCM mode ciphers is similar to CCM mode but with a few
 additional requirements and different ctrl values.
 
-Like GCM mode any additional authenticated data (AAD) is passed by calling
+Like GCM and OCB modes any additional authenticated data (AAD) is passed by calling
 EVP_CipherUpdate(), EVP_EncryptUpdate() or EVP_DecryptUpdate() with the output
 parameter B<out> set to B<NULL>. Additionally the total plaintext or ciphertext
 length B<MUST> be passed to EVP_CipherUpdate(), EVP_EncryptUpdate() or
@@ -607,4 +624,5 @@ OpenSSL 0.9.7.
 IDEA appeared in OpenSSL 0.9.7 but was often disabled due to
 patent concerns; the last patents expired in 2012.
 
+Support for OCB mode was added in OpenSSL 1.1.0
 =cut