new manual page X509_CRL_METHOD_new(3)

documenting five functions to customize CRL handling

6 files changed, 245 insertions, 14 deletions

diff --git a/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile
index 43d7c5bc56..1e2c626d0c 100644
--- a/src/lib/libcrypto/man/Makefile
+++ b/src/lib/libcrypto/man/Makefile
@@ -1,4 +1,4 @@
-# $OpenBSD: Makefile,v 1.207 2021/10/29 09:42:07 schwarze Exp $
+# $OpenBSD: Makefile,v 1.208 2021/10/30 16:20:35 schwarze Exp $
 
 .include <bsd.own.mk>
 
@@ -286,6 +286,7 @@ MAN=	\
         X509_ATTRIBUTE_new.3 \
         X509_ATTRIBUTE_set1_object.3 \
         X509_CINF_new.3 \
+        X509_CRL_METHOD_new.3 \
         X509_CRL_get0_by_serial.3 \
         X509_CRL_new.3 \
         X509_CRL_print.3 \
diff --git a/src/lib/libcrypto/man/X509_CRL_METHOD_new.3 b/src/lib/libcrypto/man/X509_CRL_METHOD_new.3
new file mode 100644
index 0000000000..f80ce743cd
--- /dev/null
+++ b/src/lib/libcrypto/man/X509_CRL_METHOD_new.3
@@ -0,0 +1,182 @@
+.\" $OpenBSD: X509_CRL_METHOD_new.3,v 1.1 2021/10/30 16:20:35 schwarze Exp $
+.\"
+.\" Copyright (c) 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
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.Dd $Mdocdate: October 30 2021 $
+.Dt X509_CRL_METHOD_NEW 3
+.Os
+.Sh NAME
+.Nm X509_CRL_METHOD_new ,
+.Nm X509_CRL_METHOD_free ,
+.Nm X509_CRL_set_default_method ,
+.Nm X509_CRL_set_meth_data ,
+.Nm X509_CRL_get_meth_data
+.Nd customize CRL handling
+.Sh SYNOPSIS
+.In openssl/x509.h
+.Ft X509_CRL_METHOD *
+.Fo X509_CRL_METHOD_new
+.Fa "int (*crl_init)(X509_CRL *crl)"
+.Fa "int (*crl_free)(X509_CRL *crl)"
+.Fa "int (*crl_lookup)(X509_CRL *crl, X509_REVOKED **ret,\
+ ASN1_INTEGER *ser, X509_NAME *issuer)"
+.Fa "int (*crl_verify)(X509_CRL *crl, EVP_PKEY *pk)"
+.Fc
+.Ft void
+.Fn X509_CRL_METHOD_free "X509_CRL_METHOD *method"
+.Ft void
+.Fn X509_CRL_set_default_method "const X509_CRL_METHOD *method"
+.Ft void
+.Fn X509_CRL_set_meth_data "X509_CRL *crl" "void *data"
+.Ft void *
+.Fn X509_CRL_get_meth_data "X509_CRL *crl"
+.Sh DESCRIPTION
+These functions customize BER decoding and signature verification
+of X.509 certificate revocation lists,
+as well as retrieval of revoked entries from such lists.
+.Pp
+.Fn X509_CRL_METHOD_new
+allocates and initializes a new
+.Vt X509_CRL_METHOD
+object, storing the four pointers to callback functions in it
+that are provided as arguments.
+.Pp
+.Fn X509_CRL_METHOD_free
+frees the given
+.Fa method
+object.
+If
+.Fa method
+is a
+.Dv NULL
+pointer or points to the static object built into the library,
+no action occurs.
+.Pp
+.Fn X509_CRL_set_default_method
+designates the given
+.Fa method
+to be used for objects that will be created with
+.Xr X509_CRL_new 3
+in the future.
+It has no effect on
+.Vt X509_CRL
+objects that already exist.
+If
+.Fa method
+is
+.Dv NULL ,
+any previously installed method will no longer be used for new
+.Vt X509_CRL
+objects created in the future, and those future objects will adhere
+to the default behaviour instead.
+.Pp
+The optional function
+.Fn crl_init
+will be called at the end of
+.Xr d2i_X509_CRL 3 ,
+the optional function
+.Fn crl_free
+near the end of
+.Xr X509_CRL_free 3 ,
+immediately before freeing
+.Fa crl
+itself.
+The function
+.Fn crl_lookup
+will be called by
+.Xr X509_CRL_get0_by_serial 3 ,
+setting
+.Fa issuer
+to
+.Dv NULL ,
+and by
+.Xr X509_CRL_get0_by_cert 3 ,
+both instead of performing the default action.
+The function
+.Fn crl_verify
+will be called by
+.Xr X509_CRL_verify 3
+instead of performing the default action.
+.Pp
+.Fn X509_CRL_set_meth_data
+stores the pointer to the auxiliary
+.Fa data
+inside the
+.Fa crl
+object.
+The pointer is expected to remain valid during the whole lifetime of the
+.Fa crl
+object but is not automatically freed when the
+.Fa crl
+object is freed.
+.Pp
+.Fn X509_CRL_get_meth_data
+retrieves the
+.Fa data
+from
+.Fa crl
+the was added with
+.Fn X509_CRL_set_meth_data .
+This may for example be useful inside the four callback methods
+installed with
+.Fn X509_CRL_METHOD_new .
+.Sh RETURN VALUES
+.Fn X509_CRL_METHOD_new
+returns a pointer to the new object or
+.Dv NULL
+if memory allocation fails.
+.Pp
+.Fn X509_CRL_get_meth_data
+returns the pointer previously installed with
+.Fn X509_CRL_set_meth_data
+or
+.Dv NULL
+if
+.Fn X509_CRL_set_meth_data
+was not called on
+.Fa crl .
+.Pp
+The callback functions
+.Fn crl_init
+and
+.Fn crl_free
+are supposed to return 1 for success or 0 for failure.
+.Pp
+The callback function
+.Fn crl_lookup
+is supposed to return 0 for failure or 1 for success,
+except if the revoked entry has the reason
+.Qq removeFromCRL ,
+in which case it is supposed to return 2.
+.Pp
+The callback function
+.Fn crl_verify
+is supposed to return 1 if the signature is valid
+or 0 if the signature check fails.
+If the signature could not be checked at all because it was invalid
+or some other error occurred, \-1 may be returned.
+.Sh SEE ALSO
+.Xr ASN1_INTEGER_new 3 ,
+.Xr d2i_X509_CRL 3 ,
+.Xr EVP_PKEY_new 3 ,
+.Xr X509_CRL_get0_by_serial 3 ,
+.Xr X509_CRL_new 3 ,
+.Xr X509_CRL_verify 3 ,
+.Xr X509_NAME_new 3 ,
+.Xr X509_REVOKED_new 3
+.Sh HISTORY
+These functions first appeared in OpenSSL 1.0.0
+and have been available since
+.Ox 4.9 .
diff --git a/src/lib/libcrypto/man/X509_CRL_get0_by_serial.3 b/src/lib/libcrypto/man/X509_CRL_get0_by_serial.3
index 8db046051b..865e86feb9 100644
--- a/src/lib/libcrypto/man/X509_CRL_get0_by_serial.3
+++ b/src/lib/libcrypto/man/X509_CRL_get0_by_serial.3
@@ -1,5 +1,5 @@
-.\"     $OpenBSD: X509_CRL_get0_by_serial.3,v 1.11 2020/10/21 17:17:43 tb Exp $
-.\"     OpenSSL X509_CRL_get0_by_serial.pod cdd6c8c5 Mar 20 12:29:37 2017 +0100
+.\" $OpenBSD: X509_CRL_get0_by_serial.3,v 1.12 2021/10/30 16:20:35 schwarze Exp $
+.\" full merge up to: OpenSSL cdd6c8c5 Mar 20 12:29:37 2017 +0100
 .\"
 .\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
 .\" Copyright (c) 2015, 2017 The OpenSSL Project.  All rights reserved.
@@ -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: October 21 2020 $
+.Dd $Mdocdate: October 30 2021 $
 .Dt X509_CRL_GET0_BY_SERIAL 3
 .Os
 .Sh NAME
@@ -105,6 +105,18 @@ except that it looks for a revoked entry using the serial number
 of certificate
 .Fa x .
 .Pp
+If
+.Xr X509_CRL_set_default_method 3
+was in effect at the time the
+.Fa crl
+object was created,
+.Fn X509_CRL_get0_by_serial
+and
+.Fn X509_CRL_get0_by_cert
+invoke the
+.Fn crl_lookup
+callback function instead of performing the default action.
+.Pp
 .Fn X509_CRL_get_REVOKED
 returns an internal pointer to a stack of all revoked entries for
 .Fa crl .
@@ -158,6 +170,7 @@ returns a STACK of revoked entries.
 .Xr X509_CRL_get_ext 3 ,
 .Xr X509_CRL_get_issuer 3 ,
 .Xr X509_CRL_get_version 3 ,
+.Xr X509_CRL_METHOD_new 3 ,
 .Xr X509_CRL_new 3 ,
 .Xr X509_REVOKED_new 3 ,
 .Xr X509V3_get_d2i 3
diff --git a/src/lib/libcrypto/man/X509_CRL_new.3 b/src/lib/libcrypto/man/X509_CRL_new.3
index 4d3f97afdb..82ba18266a 100644
--- a/src/lib/libcrypto/man/X509_CRL_new.3
+++ b/src/lib/libcrypto/man/X509_CRL_new.3
@@ -1,6 +1,6 @@
-.\" $OpenBSD: X509_CRL_new.3,v 1.12 2021/08/02 16:21:11 schwarze Exp $
+.\" $OpenBSD: X509_CRL_new.3,v 1.13 2021/10/30 16:20:35 schwarze Exp $
 .\"
-.\" Copyright (c) 2016, 2018 Ingo Schwarze <schwarze@openbsd.org>
+.\" Copyright (c) 2016, 2018, 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
@@ -14,7 +14,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: August 2 2021 $
+.Dd $Mdocdate: October 30 2021 $
 .Dt X509_CRL_NEW 3
 .Os
 .Sh NAME
@@ -67,6 +67,19 @@ decrements the reference count of
 by 1.
 If the reference count reaches 0, it frees
 .Fa crl .
+If
+.Xr X509_CRL_set_default_method 3
+was in effect at the time
+.Fa crl
+was created and the
+.Fn crl_free
+callback is not
+.Dv NULL ,
+that callback is invoked near the end of
+.Fn X509_CRL_free ,
+right before freeing
+.Fa crl
+itself.
 .Pp
 .Fn X509_CRL_INFO_new
 allocates and initializes an empty
@@ -112,6 +125,7 @@ returns 1 on success or 0 on error.
 .Xr X509_CRL_get_issuer 3 ,
 .Xr X509_CRL_get_version 3 ,
 .Xr X509_CRL_match 3 ,
+.Xr X509_CRL_METHOD_new 3 ,
 .Xr X509_CRL_print 3 ,
 .Xr X509_CRL_sign 3 ,
 .Xr X509_EXTENSION_new 3 ,
diff --git a/src/lib/libcrypto/man/X509_sign.3 b/src/lib/libcrypto/man/X509_sign.3
index ca4c5192b2..eb69874cdc 100644
--- a/src/lib/libcrypto/man/X509_sign.3
+++ b/src/lib/libcrypto/man/X509_sign.3
@@ -1,5 +1,5 @@
-.\"     $OpenBSD: X509_sign.3,v 1.8 2019/06/14 13:59:32 schwarze Exp $
-.\"     OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400
+.\" $OpenBSD: X509_sign.3,v 1.9 2021/10/30 16:20:35 schwarze Exp $
+.\" full merge up to: OpenSSL df75c2bf Dec 9 01:02:36 2018 +0100
 .\"
 .\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
 .\" Copyright (c) 2015, 2016 The OpenSSL Project.  All rights reserved.
@@ -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: October 30 2021 $
 .Dt X509_SIGN 3
 .Os
 .Sh NAME
@@ -145,6 +145,16 @@ and
 .Fn X509_CRL_verify
 sign and verify certificate requests and CRLs, respectively.
 .Pp
+If
+.Xr X509_CRL_set_default_method 3
+was in effect at the time the
+.Vt X509_CRL
+object was created,
+.Fn X509_CRL_verify
+calls the
+.Fn crl_verify
+callback function instead of performing the default action.
+.Pp
 .Fn X509_sign_ctx
 is used where the default parameters for the corresponding public key
 and digest are not suitable.
@@ -181,6 +191,7 @@ In some cases of failure, the reason can be determined with
 .Xr d2i_X509 3 ,
 .Xr EVP_DigestInit 3 ,
 .Xr X509_CRL_get0_by_serial 3 ,
+.Xr X509_CRL_METHOD_new 3 ,
 .Xr X509_CRL_new 3 ,
 .Xr X509_get_pubkey 3 ,
 .Xr X509_get_subject_name 3 ,
diff --git a/src/lib/libcrypto/man/d2i_X509_CRL.3 b/src/lib/libcrypto/man/d2i_X509_CRL.3
index 920be4aa89..a0a19b4f55 100644
--- a/src/lib/libcrypto/man/d2i_X509_CRL.3
+++ b/src/lib/libcrypto/man/d2i_X509_CRL.3
@@ -1,7 +1,6 @@
-.\"     $OpenBSD: d2i_X509_CRL.3,v 1.7 2018/03/27 17:35:50 schwarze Exp $
-.\"     OpenSSL bb9ad09e Jun 6 00:43:05 2016 -0400
+.\" $OpenBSD: d2i_X509_CRL.3,v 1.8 2021/10/30 16:20:35 schwarze Exp $
 .\"
-.\" Copyright (c) 2016 Ingo Schwarze <schwarze@openbsd.org>
+.\" Copyright (c) 2016, 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
@@ -15,7 +14,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: March 27 2018 $
+.Dd $Mdocdate: October 30 2021 $
 .Dt D2I_X509_CRL 3
 .Os
 .Sh NAME
@@ -96,6 +95,16 @@ and
 decode and encode an ASN.1
 .Vt CertificateList
 structure defined in RFC 5280 section 5.1.
+.Pp
+If
+.Xr X509_CRL_set_default_method 3
+is in effect and the
+.Fn crl_init
+callback is not
+.Dv NULL ,
+that callback is invoked at the end of
+.Fn d2i_X509_CRL .
+.Pp
 .Fn d2i_X509_CRL_bio ,
 .Fn d2i_X509_CRL_fp ,
 .Fn i2d_X509_CRL_bio ,
@@ -123,6 +132,7 @@ the revokedCertificates field of the ASN.1
 structure.
 .Sh SEE ALSO
 .Xr ASN1_item_d2i 3 ,
+.Xr X509_CRL_METHOD_new 3 ,
 .Xr X509_CRL_new 3 ,
 .Xr X509_REVOKED_new 3
 .Sh STANDARDS