Add documentation for OCB mode

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()

=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

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.

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

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