diff options
author | Matt Caswell <matt@openssl.org> | 2014-12-06 20:55:53 +0000 |
---|---|---|
committer | Matt Caswell <matt@openssl.org> | 2014-12-08 10:28:56 +0000 |
commit | e4bbee963348414a8f5e75dc7d23c3e30c72a860 (patch) | |
tree | 424c0e6154a9f25ea4579af0c92faed7d1118532 /doc | |
parent | d827c5edb54263f81cc46899080e2ad7b70ca9f5 (diff) |
Add documentation for OCB mode
Reviewed-by: Tim Hudson <tjh@openssl.org>
Diffstat (limited to 'doc')
-rw-r--r-- | doc/crypto/EVP_EncryptInit.pod | 44 |
1 files changed, 31 insertions, 13 deletions
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<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 |