generic-library/openssl
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Add documentation for OCB mode

Browse Source 
Reviewed-by: Tim Hudson <tjh@openssl.org>
This commit is contained in:
Matt Caswell 2014-12-06 20:55:53 +00:00
parent d827c5edb5
commit e4bbee9633
1 changed files with 31 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

44
doc/crypto/EVP_EncryptInit.pod
View File

@ -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_GCM_SET_IVLEN, ivlen, NULL);
EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_OCB_SET_TAGLEN, taglen, 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 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.
EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GCM_GET_TAG, taglen, tag);
The following ctrls are supported in both GCM and OCB modes:
EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_SET_IVLEN, ivlen, NULL);
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_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