From: Matt Caswell Date: Sat, 6 Dec 2014 20:55:53 +0000 (+0000) Subject: Add documentation for OCB mode X-Git-Tag: master-pre-reformat~167 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=e4bbee963348414a8f5e75dc7d23c3e30c72a860;p=openssl Add documentation for OCB mode Reviewed-by: Tim Hudson --- diff --git a/doc/crypto/EVP_EncryptInit.pod b/doc/crypto/EVP_EncryptInit.pod index ea166bf6fb..524921f834 100644 --- 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 section below for details. +the L 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 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 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 bytes of the tag value to the buffer indicated by B. This call can only be made when encrypting data and B 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 bytes from B. This call is only legal when decrypting data and must be made B 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 below for an example of the use of GCM mode. @@ -418,7 +435,7 @@ See L 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 set to B. Additionally the total plaintext or ciphertext length B 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