1 files changed, 182 insertions, 0 deletions

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 .