1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
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 .
|
