1.\" $OpenBSD: X509_STORE_get_by_subject.3,v 1.5 2023/11/16 20:27:43 schwarze Exp $
2.\"
3.\" Copyright (c) 2021, 2023 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 16 2023 $
18.Dt X509_STORE_GET_BY_SUBJECT 3
19.Os
20.Sh NAME
21.Nm X509_STORE_CTX_get_by_subject ,
22.Nm X509_STORE_CTX_get_obj_by_subject ,
23.Nm X509_STORE_CTX_get1_certs ,
24.Nm X509_STORE_CTX_get1_crls ,
25.Nm X509_STORE_CTX_get1_issuer ,
26.Nm X509_STORE_get_by_subject ,
27.Nm X509_STORE_get1_certs ,
28.Nm X509_STORE_get1_crls
29.Nd retrieve objects from a certificate store
30.Sh SYNOPSIS
31.In openssl/x509_vfy.h
32.Ft int
33.Fo X509_STORE_CTX_get_by_subject
34.Fa "X509_STORE_CTX *ctx"
35.Fa "X509_LOOKUP_TYPE type"
36.Fa "X509_NAME *name"
37.Fa "X509_OBJECT *object"
38.Fc
39.Ft X509_OBJECT *
40.Fo X509_STORE_CTX_get_obj_by_subject
41.Fa "X509_STORE_CTX *ctx"
42.Fa "X509_LOOKUP_TYPE type"
43.Fa "X509_NAME *name"
44.Fc
45.Ft STACK_OF(X509) *
46.Fo X509_STORE_CTX_get1_certs
47.Fa "X509_STORE_CTX *ctx"
48.Fa "X509_NAME *name"
49.Fc
50.Ft STACK_OF(X509_CRL) *
51.Fo X509_STORE_CTX_get1_crls
52.Fa "X509_STORE_CTX *ctx"
53.Fa "X509_NAME *name"
54.Fc
55.Ft int
56.Fo X509_STORE_CTX_get1_issuer
57.Fa "X509 **issuer"
58.Fa "X509_STORE_CTX *ctx"
59.Fa "X509 *certificate"
60.Fc
61.Ft int
62.Fo X509_STORE_get_by_subject
63.Fa "X509_STORE_CTX *ctx"
64.Fa "X509_LOOKUP_TYPE type"
65.Fa "X509_NAME *name"
66.Fa "X509_OBJECT *object"
67.Fc
68.Ft STACK_OF(X509) *
69.Fo X509_STORE_get1_certs
70.Fa "X509_STORE_CTX *ctx"
71.Fa "X509_NAME *name"
72.Fc
73.Ft STACK_OF(X509_CRL) *
74.Fo X509_STORE_get1_crls
75.Fa "X509_STORE_CTX *ctx"
76.Fa "X509_NAME *name"
77.Fc
78.Sh DESCRIPTION
79.Fn X509_STORE_CTX_get_by_subject
80retrieves the first object having a matching
81.Fa type
82and
83.Fa name
84from the
85.Vt X509_STORE
86associated with the
87.Fa ctx .
88The
89.Fa type
90can be
91.Dv X509_LU_X509
92to retrieve a certificate or
93.Dv X509_LU_CRL
94to retrieve a revocation list.
95.Pp
96If the store does not yet contain a matching object or if the type is
97.Dv X509_LU_CRL ,
98.Xr X509_LOOKUP_by_subject 3
99is called on
100.Vt X509_LOOKUP
101objects associated with the store until a match is found,
102which may add zero or more objects to the store.
103.Pp
104In case of success, the content of the
105.Fa object
106provided by the caller is overwritten with a pointer to the first
107match, and the reference count of that certificate or revocation
108list is incremented by 1.
109Avoiding a memory leak by making sure the provided
110.Fa object
111is empty is the responsibility of the caller.
112.Pp
113.Fn X509_STORE_CTX_get_obj_by_subject
114is similar except that a new object is allocated and returned.
115.Pp
116.Fn X509_STORE_CTX_get1_certs
117retrieves all certificates matching the subject
118.Vt name
119from the
120.Vt X509_STORE
121associated with
122.Fa ctx .
123If there are none yet,
124.Fn X509_STORE_CTX_get_by_subject
125is called to try and add some.
126In case of success, the reference counts of all certificates
127added to the returned array are incremented by 1.
128.Pp
129.Fn X509_STORE_CTX_get1_crls
130is similar except that it operates on certificate revocation lists
131rather than on certificates and that it always calls
132.Fn X509_STORE_CTX_get_by_subject ,
133even if the
134.Vt X509_STORE
135already contains a matching revocation list.
136.Pp
137.Fn X509_STORE_CTX_get1_issuer
138retrieves the
139.Fa issuer
140CA certificate for the given
141.Fa certificate
142from the
143.Vt X509_STORE
144associated with
145.Fa ctx .
146Internally, the issuer name is retrieved with
147.Xr X509_get_issuer_name 3
148and the candidate issuer CA certificate with
149.Fn X509_STORE_X509_get_by_subject
150using that issuer name.
151.Xr X509_check_issued 3
152or a user-supplied replacement function is used to check whether the
153.Fa certificate
154was indeed issued using the
155.Fa issuer
156CA certificate before returning it.
157If verification parameters associated with
158.Fa ctx
159encourage checking of validity times, CAs with a valid time are
160preferred, but if no matching CA has a valid time, one with an
161invalid time is accepted anyway.
162.Pp
163The following are deprecated aliases implemented as macros:
164.Bl -column X509_STORE_get_by_subject F X509_STORE_CTX_get_by_subject
165.It Fn X509_STORE_get_by_subject Ta for Ta Fn X509_STORE_CTX_get_by_subject
166.It Fn X509_STORE_get1_certs     Ta for Ta Fn X509_STORE_CTX_get1_certs
167.It Fn X509_STORE_get1_crls      Ta for Ta Fn X509_STORE_CTX_get1_crls
168.El
169.Sh RETURN VALUES
170.Fn X509_STORE_CTX_get_by_subject
171and
172.Fn X509_STORE_get_by_subject
173return 1 if a match is found or 0 on failure.
174In addition to simply not finding a match,
175they may also fail due to memory allocation failure in
176.Xr X509_LOOKUP_by_subject 3 .
177With library implementations other than LibreSSL,
178they might also return negative values for internal errors.
179.Pp
180.Fn X509_STORE_CTX_get_obj_by_subject
181returns the new object or
182.Dv NULL
183on failure, in particular if no match is found or memory allocation fails.
184.Pp
185.Fn X509_STORE_CTX_get1_certs
186and
187.Fn X509_STORE_get1_certs
188return a newly allocated and populated array of certificates or
189.Dv NULL
190on failure.
191They fail if no match is found, if
192.Fn X509_STORE_CTX_get_by_subject
193fails, or if memory allocation fails.
194.Pp
195.Fn X509_STORE_CTX_get1_crls
196and
197.Fn X509_STORE_get1_crls
198return a newly allocated and populated array of CRLs or
199.Dv NULL
200on failure.
201They fail if
202.Fn X509_STORE_CTX_get_by_subject
203finds no new match, even if the associated
204.Vt X509_STORE
205already contains matching CRLs, or if memory allocation fails.
206.Pp
207.Fn X509_STORE_CTX_get1_issuer
208returns 1 if a matching
209.Fa issuer
210CA certificate is found or 0 otherwise.
211With library implementations other than LibreSSL,
212it might also return negative values for internal errors.
213.Sh SEE ALSO
214.Xr STACK_OF 3 ,
215.Xr X509_check_issued 3 ,
216.Xr X509_CRL_new 3 ,
217.Xr X509_get_issuer_name 3 ,
218.Xr X509_LOOKUP_by_subject 3 ,
219.Xr X509_NAME_new 3 ,
220.Xr X509_new 3 ,
221.Xr X509_OBJECT_retrieve_by_subject 3 ,
222.Xr X509_STORE_CTX_new 3 ,
223.Xr X509_VERIFY_PARAM_set_flags 3
224.Sh HISTORY
225.Fn X509_STORE_get_by_subject
226first appeared in SSLeay 0.8.0 and has been available since
227.Ox 2.4 .
228.Pp
229.Fn X509_STORE_CTX_get1_issuer
230first appeared in OpenSSL 0.9.6 and has been available since
231.Ox 2.9 .
232.Pp
233.Fn X509_STORE_get1_certs
234and
235.Fn X509_STORE_get1_crls
236first appeared in OpenSSL 1.0.0 and have been available since
237.Ox 4.9 .
238.Pp
239.Fn X509_STORE_CTX_get_by_subject
240and
241.Fn X509_STORE_CTX_get_obj_by_subject
242first appeared in OpenSSL 1.1.0 and have been available since
243.Ox 7.1 .
244.Pp
245.Fn X509_STORE_CTX_get1_certs
246and
247.Fn X509_STORE_CTX_get1_crls
248first appeared in OpenSSL 1.1.0 and have been available since
249.Ox 7.4 .
250