document obj_cleanup_defer(3) and check_defer(3)

2 files changed, 72 insertions, 8 deletions

diff --git a/lib/libcrypto/man/OBJ_create.3 b/lib/libcrypto/man/OBJ_create.3
index e79ef90853c..0a91fc86558 100644
--- a/lib/libcrypto/man/OBJ_create.3
+++ b/lib/libcrypto/man/OBJ_create.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: OBJ_create.3,v 1.2 2021/12/15 22:20:12 schwarze Exp $
+.\" $OpenBSD: OBJ_create.3,v 1.3 2021/12/16 16:36:16 schwarze Exp $
 .\" full merge up to:
 .\" OpenSSL OBJ_nid2obj.pod 9b86974e Aug 17 15:21:33 2015 -0400
 .\" selective merge up to:
@@ -7,7 +7,7 @@
 .\" This file is a derived work.
 .\" The changes are covered by the following Copyright and license:
 .\"
-.\" Copyright (c) 2017 Ingo Schwarze <schwarze@openbsd.org>
+.\" Copyright (c) 2017, 2021 Ingo Schwarze <schwarze@openbsd.org>
 .\"
 .\" Permission to use, copy, modify, and distribute this software for any
 .\" purpose with or without fee is hereby granted, provided that the above
@@ -69,7 +69,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: December 15 2021 $
+.Dd $Mdocdate: December 16 2021 $
 .Dt OBJ_CREATE 3
 .Os
 .Sh NAME
@@ -78,7 +78,9 @@
 .Nm OBJ_create ,
 .\" OBJ_create_and_add_object is a deprecated, unused alias for OBJ_create(3).
 .Nm OBJ_create_objects ,
-.Nm OBJ_cleanup
+.Nm obj_cleanup_defer ,
+.Nm OBJ_cleanup ,
+.Nm check_defer
 .Nd modify the table of ASN.1 object identifiers
 .Sh SYNOPSIS
 .In openssl/objects.h
@@ -94,8 +96,11 @@
 .Fc
 .Ft int
 .Fn OBJ_create_objects "BIO *in_bio"
+.Vt extern int obj_cleanup_defer ;
 .Ft void
 .Fn OBJ_cleanup void
+.Ft void
+.Fn check_defer "int nid"
 .Sh DESCRIPTION
 .Fn OBJ_new_nid
 returns the smallest currently unassigned ASN.1 numeric
@@ -149,13 +154,64 @@ or a similar function and then calling
 .Xr ASN1_OBJECT_free 3
 on the returned pointer will have no effect.
 .Pp
+The global variable
+.Va obj_cleanup_defer
+controls the behaviour of
+.Fn OBJ_cleanup
+and
+.Xr EVP_cleanup 3 .
+.Pp
+If
+.Va obj_cleanup_defer
+has the default value of 0,
 .Fn OBJ_cleanup
-cleans up the internal object table: this should be called before
-an application exits if any new objects were added using
+resets the internal object table to its default state,
+removing and freeing all objects that were added with
 .Fn OBJ_add_object ,
 .Fn OBJ_create ,
 or
 .Fn OBJ_create_objects .
+Otherwise,
+.Fn OBJ_cleanup
+only sets
+.Va obj_cleanup_defer
+to 2, which defers the cleanup of the internal object table
+to the next call of
+.Xr EVP_cleanup 3 .
+.Pp
+By default,
+.Xr EVP_cleanup 3
+has no effect on the internal object table.
+Only if
+.Va obj_cleanup_defer
+is 2, it resets
+.Va obj_cleanup_defer
+to 0 and calls
+.Fn OBJ_cleanup ,
+which then resets the table to its default state.
+.Pp
+The function
+.Fn check_defer
+sets
+.Va obj_cleanup_defer
+to 1 unless
+.Fa nid
+is a built-in numeric identifier, but it has no effect if
+.Va obj_cleanup_defer
+already differs from 0.
+This function is called internally by various functions
+in the EVP library, in particular by subroutines of
+.Xr OpenSSL_add_all_ciphers 3
+and
+.Xr OpenSSL_add_all_digests 3 .
+.Pp
+To reliably reset the internal object table no matter what the
+current state may be, an application program needs to call both
+.Fn OBJ_cleanup
+and
+.Xr EVP_cleanup 3 ,
+in this order.
+The opposite order will usually not work.
 .Sh RETURN VALUES
 .Fn OBJ_new_nid
 returns the new NID.
@@ -196,6 +252,7 @@ obj = OBJ_nid2obj(new_nid);
 .Ed
 .Sh SEE ALSO
 .Xr ASN1_OBJECT_new 3 ,
+.Xr EVP_cleanup 3 ,
 .Xr OBJ_nid2obj 3
 .Sh HISTORY
 .Fn OBJ_new_nid ,
@@ -207,6 +264,12 @@ first appeared in SSLeay 0.8.0 and
 in SSLeay 0.9.0.
 These functions have been available since
 .Ox 2.4 .
+.Pp
+.Va obj_cleanup_defer
+and
+.Fn check_defer
+first appeared in OpenSSL 1.0.0 and have been available since
+.Ox 4.9 .
 .Sh BUGS
 .Fn OBJ_new_nid
 does not reserve any return value to indicate an error.
diff --git a/lib/libcrypto/man/OpenSSL_add_all_algorithms.3 b/lib/libcrypto/man/OpenSSL_add_all_algorithms.3
index 9ef19e71634..e47948df4cb 100644
--- a/lib/libcrypto/man/OpenSSL_add_all_algorithms.3
+++ b/lib/libcrypto/man/OpenSSL_add_all_algorithms.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: OpenSSL_add_all_algorithms.3,v 1.8 2019/06/14 13:41:31 schwarze Exp $
+.\" $OpenBSD: OpenSSL_add_all_algorithms.3,v 1.9 2021/12/16 16:36:16 schwarze Exp $
 .\" full merge up to: OpenSSL b3696a55 Sep 2 09:35:50 2017 -0400
 .\"
 .\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
@@ -48,7 +48,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: June 14 2019 $
+.Dd $Mdocdate: December 16 2021 $
 .Dt OPENSSL_ADD_ALL_ALGORITHMS 3
 .Os
 .Sh NAME
@@ -103,6 +103,7 @@ removes all ciphers and digests from the table.
 .Xr evp 3 ,
 .Xr EVP_DigestInit 3 ,
 .Xr EVP_EncryptInit 3 ,
+.Xr OBJ_cleanup 3 ,
 .Xr OPENSSL_config 3
 .Sh HISTORY
 .Fn EVP_cleanup