From: schwarze Date: Sat, 30 Oct 2021 16:20:35 +0000 (+0000) Subject: new manual page X509_CRL_METHOD_new(3) X-Git-Url: http://artulab.com/gitweb/?a=commitdiff_plain;h=3da77284952e7839ecd44713a2e807e5afcdc478;p=openbsd new manual page X509_CRL_METHOD_new(3) documenting five functions to customize CRL handling --- diff --git a/lib/libcrypto/man/Makefile b/lib/libcrypto/man/Makefile index 43d7c5bc56d..1e2c626d0cb 100644 --- a/lib/libcrypto/man/Makefile +++ b/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 @@ -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/lib/libcrypto/man/X509_CRL_METHOD_new.3 b/lib/libcrypto/man/X509_CRL_METHOD_new.3 new file mode 100644 index 00000000000..f80ce743cde --- /dev/null +++ b/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 +.\" +.\" 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/lib/libcrypto/man/X509_CRL_get0_by_serial.3 b/lib/libcrypto/man/X509_CRL_get0_by_serial.3 index 8db046051b7..865e86feb96 100644 --- a/lib/libcrypto/man/X509_CRL_get0_by_serial.3 +++ b/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 . .\" 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/lib/libcrypto/man/X509_CRL_new.3 b/lib/libcrypto/man/X509_CRL_new.3 index 4d3f97afdb4..82ba18266a7 100644 --- a/lib/libcrypto/man/X509_CRL_new.3 +++ b/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 +.\" Copyright (c) 2016, 2018, 2021 Ingo Schwarze .\" .\" 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/lib/libcrypto/man/X509_sign.3 b/lib/libcrypto/man/X509_sign.3 index ca4c5192b25..eb69874cdce 100644 --- a/lib/libcrypto/man/X509_sign.3 +++ b/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 . .\" 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/lib/libcrypto/man/d2i_X509_CRL.3 b/lib/libcrypto/man/d2i_X509_CRL.3 index 920be4aa891..a0a19b4f554 100644 --- a/lib/libcrypto/man/d2i_X509_CRL.3 +++ b/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 +.\" Copyright (c) 2016, 2021 Ingo Schwarze .\" .\" 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