New function EVP_CIPHER_free()

This function re-implements EVP_CIPHER_meth_free(), but has a name that
isn't encumbered by legacy EVP_CIPHER construction functionality.

We also refactor most of EVP_CIPHER_meth_new() into an internal
evp_cipher_new() that's used when creating fetched methods.

EVP_CIPHER_meth_new() and EVP_CIPHER_meth_free() are rewritten in terms of
evp_cipher_new() and EVP_CIPHER_free().  This means that at any time, we can
deprecate all the EVP_CIPHER_meth_ functions with no harmful consequence.

Reviewed-by: Shane Lontis <shane.lontis@oracle.com>
(Merged from https://github.com/openssl/openssl/pull/9758)

2 files changed, 23 insertions, 9 deletions

diff --git a/doc/man3/EVP_CIPHER_meth_new.pod b/doc/man3/EVP_CIPHER_meth_new.pod
index 3d4da9c04e..8a6a4b99de 100644
--- a/doc/man3/EVP_CIPHER_meth_new.pod
+++ b/doc/man3/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, EVP_CIPHER_up_ref
+EVP_CIPHER_meth_get_ctrl
 - Routines to build up EVP_CIPHER methods
 
 =head1 SYNOPSIS
@@ -63,8 +63,6 @@ EVP_CIPHER_meth_get_ctrl, EVP_CIPHER_up_ref
                                                            int type, int arg,
                                                            void *ptr);
 
- int EVP_CIPHER_up_ref(EVP_CIPHER *cipher);
-
 =head1 DESCRIPTION
 
 The B<EVP_CIPHER> type is a structure for symmetric cipher method
@@ -226,8 +224,6 @@ 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.
 
-EVP_CIPHER_up_ref() increments the reference count for an EVP_CIPHER structure.
-
 =head1 RETURN VALUES
 
 EVP_CIPHER_meth_new() and EVP_CIPHER_meth_dup() return a pointer to a
@@ -236,8 +232,6 @@ All EVP_CIPHER_meth_set_*() functions return 1.
 All EVP_CIPHER_meth_get_*() functions return pointers to their
 respective B<cipher> function.
 
-EVP_CIPHER_up_ref() returns 1 for success or 0 otherwise.
-
 =head1 SEE ALSO
 
 L<EVP_EncryptInit>
@@ -245,6 +239,8 @@ L<EVP_EncryptInit>
 =head1 HISTORY
 
 The functions described here were added in OpenSSL 1.1.0.
+The B<EVP_CIPHER> structure created with these functions became reference
+counted in OpenSSL 3.0.
 
 =head1 COPYRIGHT
 
diff --git a/doc/man3/EVP_EncryptInit.pod b/doc/man3/EVP_EncryptInit.pod
index 7f69a23dd7..11d0250a0d 100644
--- a/doc/man3/EVP_EncryptInit.pod
+++ b/doc/man3/EVP_EncryptInit.pod
@@ -3,6 +3,8 @@
 =head1 NAME
 
 EVP_CIPHER_fetch,
+EVP_CIPHER_up_ref,
+EVP_CIPHER_free,
 EVP_CIPHER_CTX_new,
 EVP_CIPHER_CTX_reset,
 EVP_CIPHER_CTX_free,
@@ -67,6 +69,8 @@ EVP_CIPHER_do_all_ex
 
  EVP_CIPHER *EVP_CIPHER_fetch(OPENSSL_CTX *ctx, const char *algorithm,
                               const char *properties);
+ int EVP_CIPHER_up_ref(EVP_CIPHER *cipher);
+ void EVP_CIPHER_free(EVP_CIPHER *cipher);
  EVP_CIPHER_CTX *EVP_CIPHER_CTX_new(void);
  int EVP_CIPHER_CTX_reset(EVP_CIPHER_CTX *ctx);
  void EVP_CIPHER_CTX_free(EVP_CIPHER_CTX *ctx);
@@ -150,13 +154,21 @@ EVP_CIPHER_do_all_ex
 The EVP cipher routines are a high level interface to certain
 symmetric ciphers.
 
+The B<EVP_CIPHER> type is a structure for cipher method implementation.
+
 EVP_CIPHER_fetch() fetches the cipher implementation for the given
 B<algorithm> from any provider offering it, within the criteria given
 by the B<properties>.
 See L<provider(7)/Fetching algorithms> for further information.
 
-The returned value must eventually be freed with
-L<EVP_CIPHER_meth_free(3)>.
+The returned value must eventually be freed with EVP_CIPHER_free().
+
+EVP_CIPHER_up_ref() increments the reference count for an B<EVP_CIPHER>
+structure.
+
+EVP_CIPHER_free() decrements the reference count for the B<EVP_CIPHER>
+structure.
+If the reference count drops to 0 then the structure is freed.
 
 EVP_CIPHER_CTX_new() creates a cipher context.
 
@@ -351,6 +363,8 @@ and the given I<arg> as argument.
 EVP_CIPHER_fetch() returns a pointer to a B<EVP_CIPHER> for success
 and B<NULL> for failure.
 
+EVP_CIPHER_up_ref() returns 1 for success or 0 otherwise.
+
 EVP_CIPHER_CTX_new() returns a pointer to a newly created
 B<EVP_CIPHER_CTX> for success and B<NULL> for failure.
 
@@ -757,6 +771,10 @@ EVP_CIPHER_CTX_reset() appeared and EVP_CIPHER_CTX_cleanup()
 disappeared.  EVP_CIPHER_CTX_init() remains as an alias for
 EVP_CIPHER_CTX_reset().
 
+The EVP_CIPHER_fetch(), EVP_CIPHER_free(), EVP_CIPHER_up_ref(),
+EVP_CIPHER_CTX_set_params() and EVP_CIPHER_CTX_get_params() functions
+were added in 3.0.
+
 =head1 COPYRIGHT
 
 Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved.