.\" $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 .