Update copyright year

[openssl.git] / doc / crypto / EVP_CIPHER_meth_new.pod

diff --git a/doc/crypto/EVP_CIPHER_meth_new.pod b/doc/crypto/EVP_CIPHER_meth_new.pod
index b0076d596a820b68ee0262b2de323306f790fa29..08e8290bef58b25ebdc2fca6c3c7cfefee142317 100644 (file)
--- a/doc/crypto/EVP_CIPHER_meth_new.pod
+++ b/doc/crypto/EVP_CIPHER_meth_new.pod
@@ -10,7 +10,7 @@ EVP_CIPHER_meth_set_set_asn1_params, EVP_CIPHER_meth_set_get_asn1_params,
 EVP_CIPHER_meth_set_ctrl, EVP_CIPHER_meth_get_init,
 EVP_CIPHER_meth_get_do_cipher, EVP_CIPHER_meth_get_cleanup,
 EVP_CIPHER_meth_get_set_asn1_params, EVP_CIPHER_meth_get_get_asn1_params,
-EVP_CIPHER_meth_get_ctrl  - Routines to build up EVP_CIPHER methods
+EVP_CIPHER_meth_get_ctrl - Routines to build up EVP_CIPHER methods
 
 =head1 SYNOPSIS
 
@@ -19,7 +19,7 @@ EVP_CIPHER_meth_get_ctrl  - Routines to build up EVP_CIPHER methods
  EVP_CIPHER *EVP_CIPHER_meth_new(int cipher_type, int block_size, int key_len);
  EVP_CIPHER *EVP_CIPHER_meth_dup(const EVP_CIPHER *cipher);
  void EVP_CIPHER_meth_free(EVP_CIPHER *cipher);
- 
+
  int EVP_CIPHER_meth_set_iv_length(EVP_CIPHER *cipher, int iv_len);
  int EVP_CIPHER_meth_set_flags(EVP_CIPHER *cipher, unsigned long flags);
  int EVP_CIPHER_meth_set_impl_ctx_size(EVP_CIPHER *cipher, int ctx_size);
@@ -44,7 +44,7 @@ EVP_CIPHER_meth_get_ctrl  - Routines to build up EVP_CIPHER methods
  int EVP_CIPHER_meth_set_ctrl(EVP_CIPHER *cipher,
                               int (*ctrl) (EVP_CIPHER_CTX *, int type,
                                            int arg, void *ptr));
- 
+
  int (*EVP_CIPHER_meth_get_init(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *ctx,
                                                            const unsigned char *key,
                                                            const unsigned char *iv,
@@ -84,35 +84,12 @@ The available flags are:
 
 =over 4
 
-=over 4
-
-=item The cipher modes:
-
-=over 4
-
-=item EVP_CIPH_STREAM_CIPHER
-
-=item EVP_CIPH_ECB_MODE
-
-=item EVP_CIPH_CBC_MODE
-
-=item EVP_CIPH_CFB_MODE
-
-=item EVP_CIPH_OFB_MODE
-
-=item EVP_CIPH_CTR_MODE
-
-=item EVP_CIPH_GCM_MODE
-
-=item EVP_CIPH_CCM_MODE
-
-=item EVP_CIPH_XTS_MODE
+=item EVP_CIPH_STREAM_CIPHER, EVP_CIPH_ECB_MODE EVP_CIPH_CBC_MODE,
+EVP_CIPH_CFB_MODE, EVP_CIPH_OFB_MODE, EVP_CIPH_CTR_MODE, EVP_CIPH_GCM_MODE,
+EVP_CIPH_CCM_MODE, EVP_CIPH_XTS_MODE, EVP_CIPH_WRAP_MODE,
+EVP_CIPH_OCB_MODE
 
-=item EVP_CIPH_WRAP_MODE
-
-=item EVP_CIPH_OCB_MODE
-
-=back
+The cipher mode.
 
 =item EVP_CIPH_VARIABLE_LENGTH
 
@@ -193,17 +170,12 @@ The EVP routines will simply give them control and do nothing more.
 
 =item EVP_CIPH_FLAG_AEAD_CIPHER
 
-This indicates that this is a AEAD cipher implementation.
+This indicates that this is an AEAD cipher implementation.
 
 =item EVP_CIPH_FLAG_TLS1_1_MULTIBLOCK
 
-=begin comment
-
-I could use some help explaining this one!
-
-=end comment
-
-=back
+Allow interleaving of crypto blocks, a particular optimization only applicable
+to certain TLS ciphers.
 
 =back
 
@@ -224,7 +196,7 @@ EVP_EncryptFinal(), EVP_EncryptFinal_ex(), EVP_DecryptFinal() and
 EVP_DecryptFinal_ex().
 
 EVP_CIPHER_meth_set_cleanup() sets the function for B<cipher> to do
-extra cleanup before the method's privata data structure is cleaned
+extra cleanup before the method's private data structure is cleaned
 out and freed.
 Note that the cleanup function is passed a B<EVP_CIPHER_CTX *>, the
 private data structure is then available with
@@ -232,16 +204,32 @@ EVP_CIPHER_CTX_get_cipher_data().
 This cleanup function is called by EVP_CIPHER_CTX_reset() and
 EVP_CIPHER_CTX_free().
 
+EVP_CIPHER_meth_set_set_asn1_params() sets the function for B<cipher>
+to set the AlgorithmIdentifier "parameter" based on the passed cipher.
+This function is called by EVP_CIPHER_param_to_asn1().
+EVP_CIPHER_meth_set_get_asn1_params() sets the function for B<cipher>
+that sets the cipher parameters based on an ASN.1 AlgorithmIdentifier
+"parameter".
+Both these functions are needed when there is a need for custom data
+(more or other than the cipher IV).
+They are called by EVP_CIPHER_param_to_asn1() and
+EVP_CIPHER_asn1_to_param() respectively if defined.
+
 EVP_CIPHER_meth_set_ctrl() sets the control function for B<cipher>.
 
+EVP_CIPHER_meth_get_init(), EVP_CIPHER_meth_get_do_cipher(),
+EVP_CIPHER_meth_get_cleanup(), EVP_CIPHER_meth_get_set_asn1_params(),
+EVP_CIPHER_meth_get_get_asn1_params() and EVP_CIPHER_meth_get_ctrl()
+are all used to retrieve the method data given with the
+EVP_CIPHER_meth_set_*() functions above.
+
+=head1 RETURN VALUES
 
-EVP_CIPHER_meth_get_input_blocksize(), EVP_CIPHER_meth_get_result_size(),
-EVP_CIPHER_meth_get_app_datasize(), EVP_CIPHER_meth_get_flags(),
-EVP_CIPHER_meth_get_init(), EVP_CIPHER_meth_get_update(),
-EVP_CIPHER_meth_get_final(), EVP_CIPHER_meth_get_copy(),
-EVP_CIPHER_meth_get_cleanup() and EVP_CIPHER_meth_get_ctrl() are all used
-to retrieve the method data given with the EVP_CIPHER_meth_set_*()
-functions above.
+EVP_CIPHER_meth_new() and EVP_CIPHER_meth_dup() return a pointer to a
+newly created B<EVP_CIPHER>, or NULL on failure.
+All EVP_CIPHER_meth_set_*() functions return 1.
+All EVP_CIPHER_meth_get_*() functions return pointers to their
+respective B<cipher> function.
 
 =head1 SEE ALSO
 
@@ -250,7 +238,16 @@ L<EVP_EncryptInit>
 =head1 HISTORY
 
 The B<EVP_CIPHER> structure was openly available in OpenSSL before version
-1.1.
-The functions described here were added in OpenSSL version 1.1.
+1.1.0.
+The functions described here were added in OpenSSL 1.1.0.
+
+=head1 COPYRIGHT
+
+Copyright 2016-2017 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License").  You may not use
+this file except in compliance with the License.  You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
 
 =cut