1.\" $OpenBSD: X509_OBJECT_get0_X509.3,v 1.13 2021/11/18 10:09:24 schwarze Exp $
2.\"
3.\" Copyright (c) 2018, 2021 Ingo Schwarze <schwarze@openbsd.org>
4.\"
5.\" Permission to use, copy, modify, and distribute this software for any
6.\" purpose with or without fee is hereby granted, provided that the above
7.\" copyright notice and this permission notice appear in all copies.
8.\"
9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16.\"
17.Dd $Mdocdate: November 18 2021 $
18.Dt X509_OBJECT_GET0_X509 3
19.Os
20.Sh NAME
21.Nm X509_OBJECT_get_type ,
22.Nm X509_OBJECT_new ,
23.Nm X509_OBJECT_up_ref_count ,
24.Nm X509_OBJECT_free_contents ,
25.Nm X509_OBJECT_free ,
26.Nm X509_OBJECT_get0_X509 ,
27.Nm X509_OBJECT_get0_X509_CRL ,
28.Nm X509_OBJECT_idx_by_subject ,
29.Nm X509_OBJECT_retrieve_by_subject ,
30.Nm X509_OBJECT_retrieve_match
31.Nd certificate, CRL, private key, and string wrapper for certificate stores
32.Sh SYNOPSIS
33.In openssl/x509_vfy.h
34.Ft X509_LOOKUP_TYPE
35.Fo X509_OBJECT_get_type
36.Fa "const X509_OBJECT *obj"
37.Fc
38.Ft X509_OBJECT *
39.Fo X509_OBJECT_new
40.Fa void
41.Fc
42.Ft int
43.Fo X509_OBJECT_up_ref_count
44.Fa "X509_OBJECT *obj"
45.Fc
46.Ft void
47.Fo X509_OBJECT_free_contents
48.Fa "X509_OBJECT *obj"
49.Fc
50.Ft void
51.Fo X509_OBJECT_free
52.Fa "X509_OBJECT *obj"
53.Fc
54.Ft X509 *
55.Fo X509_OBJECT_get0_X509
56.Fa "const X509_OBJECT *obj"
57.Fc
58.Ft X509_CRL *
59.Fo X509_OBJECT_get0_X509_CRL
60.Fa "X509_OBJECT *obj"
61.Fc
62.Ft int
63.Fo X509_OBJECT_idx_by_subject
64.Fa "STACK_OF(X509_OBJECT) *stack"
65.Fa "X509_LOOKUP_TYPE type"
66.Fa "X509_NAME *name"
67.Fc
68.Ft X509_OBJECT *
69.Fo X509_OBJECT_retrieve_by_subject
70.Fa "STACK_OF(X509_OBJECT) *stack"
71.Fa "X509_LOOKUP_TYPE type"
72.Fa "X509_NAME *name"
73.Fc
74.Ft X509_OBJECT *
75.Fo X509_OBJECT_retrieve_match
76.Fa "STACK_OF(X509_OBJECT) *stack"
77.Fa "X509_OBJECT *obj"
78.Fc
79.Sh DESCRIPTION
80The
81.Vt X509_OBJECT
82structure is a shallow wrapper around one
83.Vt X509
84certificate object or one
85.Vt X509_CRL
86certificate revocation list object.
87The type of object stored at any given time can be inspected with
88.Fn X509_OBJECT_get_type .
89.Pp
90Each
91.Vt X509_STORE
92object uses one stack of
93.Vt X509_OBJECT
94structures as its main storage area.
95.Pp
96.Fn X509_OBJECT_new
97allocates a new
98.Vt X509_OBJECT
99structure.
100It sets the object type to
101.Dv X509_LU_NONE
102and the pointer to the certificate or CRL to
103.Dv NULL .
104.Pp
105If
106.Fa obj
107contains an
108.Vt X509
109certificate or an
110.Vt X509_CRL
111certificate revocation list,
112.Fn X509_OBJECT_up_ref_count
113increments the reference count of that inner object by 1.
114Otherwise, no action occurs.
115.Pp
116If
117.Fa obj
118contains an
119.Vt X509
120certificate,
121.Fn X509_OBJECT_free_contents
122calls
123.Xr X509_free 3
124on that inner object.
125If
126.Fa obj
127contains an
128.Vt X509_CRL
129certificate revocation list, it calls
130.Xr X509_CRL_free 3
131on that inner list.
132Otherwise, no action occurs.
133.Fn X509_OBJECT_free_contents
134does not free
135.Fa obj
136itself.
137.Pp
138.Fn X509_OBJECT_free
139calls
140.Fn X509_OBJECT_free_contents
141and then frees the storage used for the
142.Fa obj
143itself.
144.Pp
145If
146.Fa type
147is
148.Dv X509_LU_X509 ,
149.Fn X509_OBJECT_idx_by_subject
150and
151.Fn X509_OBJECT_retrieve_by_subject
152search the given
153.Fa stack
154for a certificate with the subject
155.Fa name .
156If
157.Fa type
158is
159.Dv X509_LU_CRL ,
160they search for a certificate revocation list with the issuer
161.Fa name
162instead.
163.Pp
164If
165.Fa obj
166contains a certificate,
167.Fn X509_OBJECT_retrieve_match
168searches the given
169.Fa stack
170for a certificate with a matching subject name;
171if it contains a certificate revocation list, it searches for a
172certificate revocation list with a matching issuer name instead;
173otherwise, it searches for an
174.Vt X509_OBJECT
175with a matching type.
176.Sh RETURN VALUES
177.Fn X509_OBJECT_get_type
178returns
179.Dv X509_LU_X509
180if
181.Fa obj
182contains a certificate,
183.Dv X509_LU_CRL
184if it contains a certificate revocation list, or
185.Dv X509_LU_NONE
186if it contains neither.
187.Pp
188.Fn X509_OBJECT_up_ref_count
189returns 1 on success and 0 on failure.
190.Pp
191.Fn X509_OBJECT_new
192returns the new object or
193.Dv NULL
194if memory allocation fails.
195.Pp
196.Fn X509_OBJECT_get0_X509
197returns an internal pointer to the certificate contained in
198.Fa obj
199or
200.Dv NULL
201if
202.Fa obj
203is
204.Dv NULL
205or contains no certificate.
206.Pp
207.Fn X509_OBJECT_get0_X509_CRL
208returns an internal pointer to the certificate revocation list contained in
209.Fa obj
210or
211.Dv NULL
212if
213.Fa obj
214is
215.Dv NULL
216or contains no certificate revocation list.
217.Pp
218.Fn X509_OBJECT_idx_by_subject
219returns the zero-based index of the first matching certificate
220or revocation list in the
221.Fa stack
222or \-1 if
223.Fa type
224is neither
225.Dv X509_LU_X509
226nor
227.Dv X509_LU_CRL
228or if no match is found.
229.Pp
230.Fn X509_OBJECT_retrieve_by_subject
231returns the first matching certificate or revocation list in the
232.Fa stack
233or
234.Dv NULL
235if
236.Fa type
237is neither
238.Dv X509_LU_X509
239nor
240.Dv X509_LU_CRL
241or if no match is found.
242.Pp
243.Fn X509_OBJECT_retrieve_match
244returns the first mathching
245.Vt X509_OBJECT
246or
247.Dv NULL
248if
249.Fa stack
250or
251.Fa obj
252is
253.Dv NULL
254or no match is found.
255.Sh SEE ALSO
256.Xr STACK_OF 3 ,
257.Xr X509_CRL_new 3 ,
258.Xr X509_LOOKUP_new 3 ,
259.Xr X509_NAME_new 3 ,
260.Xr X509_new 3 ,
261.Xr X509_STORE_get0_objects 3 ,
262.Xr X509_STORE_get_by_subject 3 ,
263.Xr X509_STORE_load_locations 3 ,
264.Xr X509_STORE_new 3
265.Sh HISTORY
266.Fn X509_OBJECT_up_ref_count
267and
268.Fn X509_OBJECT_free_contents
269first appeared in SSLeay 0.8.0 and have been available since
270.Ox 2.4 .
271.Pp
272.Fn X509_OBJECT_idx_by_subject ,
273.Fn X509_OBJECT_retrieve_by_subject ,
274and
275.Fn X509_OBJECT_retrieve_match
276first appeared in OpenSSL 0.9.6 and have been available since
277.Ox 2.9 .
278.Pp
279.Fn X509_OBJECT_get_type ,
280.Fn X509_OBJECT_get0_X509 ,
281and
282.Fn X509_OBJECT_get0_X509_CRL
283first appeared in OpenSSL 1.1.0 and have been available since
284.Ox 6.3 .
285.Pp
286.Fn X509_OBJECT_new
287and
288.Fn X509_OBJECT_free
289first appeared in OpenSSL 1.1.0 and have been available since
290.Ox 7.1 .
291