From 550f974a09942ace37cf3cf14021ea5e51e6dd11 Mon Sep 17 00:00:00 2001 From: Richard Levitte Date: Tue, 3 Sep 2019 18:11:49 +0200 Subject: 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 (Merged from https://github.com/openssl/openssl/pull/9758) --- doc/man3/EVP_CIPHER_meth_new.pod | 10 +++------- doc/man3/EVP_EncryptInit.pod | 22 ++++++++++++++++++++-- 2 files changed, 23 insertions(+), 9 deletions(-) (limited to 'doc') 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 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 function. -EVP_CIPHER_up_ref() returns 1 for success or 0 otherwise. - =head1 SEE ALSO L @@ -245,6 +239,8 @@ L =head1 HISTORY The functions described here were added in OpenSSL 1.1.0. +The B 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 type is a structure for cipher method implementation. + EVP_CIPHER_fetch() fetches the cipher implementation for the given B from any provider offering it, within the criteria given by the B. See L for further information. -The returned value must eventually be freed with -L. +The returned value must eventually be freed with EVP_CIPHER_free(). + +EVP_CIPHER_up_ref() increments the reference count for an B +structure. + +EVP_CIPHER_free() decrements the reference count for the B +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 as argument. EVP_CIPHER_fetch() returns a pointer to a B for success and B 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 for success and B 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. -- cgit v1.2.3