1.\" $OpenBSD: X509_STORE_get_by_subject.3,v 1.6 2024/05/12 05:08:59 tb 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: May 12 2024 $
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 ,
98a lookup by subject is performed on
99.Vt X509_LOOKUP
100objects associated with the store until a match is found,
101which may add zero or more objects to the store.
102.Pp
103In case of success, the content of the
104.Fa object
105provided by the caller is overwritten with a pointer to the first
106match, and the reference count of that certificate or revocation
107list is incremented by 1.
108Avoiding a memory leak by making sure the provided
109.Fa object
110is empty is the responsibility of the caller.
111.Pp
112.Fn X509_STORE_CTX_get_obj_by_subject
113is similar except that a new object is allocated and returned.
114.Pp
115.Fn X509_STORE_CTX_get1_certs
116retrieves all certificates matching the subject
117.Vt name
118from the
119.Vt X509_STORE
120associated with
121.Fa ctx .
122If there are none yet,
123.Fn X509_STORE_CTX_get_by_subject
124is called to try and add some.
125In case of success, the reference counts of all certificates
126added to the returned array are incremented by 1.
127.Pp
128.Fn X509_STORE_CTX_get1_crls
129is similar except that it operates on certificate revocation lists
130rather than on certificates and that it always calls
131.Fn X509_STORE_CTX_get_by_subject ,
132even if the
133.Vt X509_STORE
134already contains a matching revocation list.
135.Pp
136.Fn X509_STORE_CTX_get1_issuer
137retrieves the
138.Fa issuer
139CA certificate for the given
140.Fa certificate
141from the
142.Vt X509_STORE
143associated with
144.Fa ctx .
145Internally, the issuer name is retrieved with
146.Xr X509_get_issuer_name 3
147and the candidate issuer CA certificate with
148.Fn X509_STORE_X509_get_by_subject
149using that issuer name.
150.Xr X509_check_issued 3
151or a user-supplied replacement function is used to check whether the
152.Fa certificate
153was indeed issued using the
154.Fa issuer
155CA certificate before returning it.
156If verification parameters associated with
157.Fa ctx
158encourage checking of validity times, CAs with a valid time are
159preferred, but if no matching CA has a valid time, one with an
160invalid time is accepted anyway.
161.Pp
162The following are deprecated aliases implemented as macros:
163.Bl -column X509_STORE_get_by_subject F X509_STORE_CTX_get_by_subject
164.It Fn X509_STORE_get_by_subject Ta for Ta Fn X509_STORE_CTX_get_by_subject
165.It Fn X509_STORE_get1_certs     Ta for Ta Fn X509_STORE_CTX_get1_certs
166.It Fn X509_STORE_get1_crls      Ta for Ta Fn X509_STORE_CTX_get1_crls
167.El
168.Sh RETURN VALUES
169.Fn X509_STORE_CTX_get_by_subject
170and
171.Fn X509_STORE_get_by_subject
172return 1 if a match is found or 0 on failure.
173In addition to simply not finding a match,
174they may also fail due to memory allocation failure.
175With library implementations other than LibreSSL,
176they might also return negative values for internal errors.
177.Pp
178.Fn X509_STORE_CTX_get_obj_by_subject
179returns the new object or
180.Dv NULL
181on failure, in particular if no match is found or memory allocation fails.
182.Pp
183.Fn X509_STORE_CTX_get1_certs
184and
185.Fn X509_STORE_get1_certs
186return a newly allocated and populated array of certificates or
187.Dv NULL
188on failure.
189They fail if no match is found, if
190.Fn X509_STORE_CTX_get_by_subject
191fails, or if memory allocation fails.
192.Pp
193.Fn X509_STORE_CTX_get1_crls
194and
195.Fn X509_STORE_get1_crls
196return a newly allocated and populated array of CRLs or
197.Dv NULL
198on failure.
199They fail if
200.Fn X509_STORE_CTX_get_by_subject
201finds no new match, even if the associated
202.Vt X509_STORE
203already contains matching CRLs, or if memory allocation fails.
204.Pp
205.Fn X509_STORE_CTX_get1_issuer
206returns 1 if a matching
207.Fa issuer
208CA certificate is found or 0 otherwise.
209With library implementations other than LibreSSL,
210it might also return negative values for internal errors.
211.Sh SEE ALSO
212.Xr STACK_OF 3 ,
213.Xr X509_check_issued 3 ,
214.Xr X509_CRL_new 3 ,
215.Xr X509_get_issuer_name 3 ,
216.Xr X509_NAME_new 3 ,
217.Xr X509_new 3 ,
218.Xr X509_OBJECT_retrieve_by_subject 3 ,
219.Xr X509_STORE_CTX_new 3 ,
220.Xr X509_VERIFY_PARAM_set_flags 3
221.Sh HISTORY
222.Fn X509_STORE_get_by_subject
223first appeared in SSLeay 0.8.0 and has been available since
224.Ox 2.4 .
225.Pp
226.Fn X509_STORE_CTX_get1_issuer
227first appeared in OpenSSL 0.9.6 and has been available since
228.Ox 2.9 .
229.Pp
230.Fn X509_STORE_get1_certs
231and
232.Fn X509_STORE_get1_crls
233first appeared in OpenSSL 1.0.0 and have been available since
234.Ox 4.9 .
235.Pp
236.Fn X509_STORE_CTX_get_by_subject
237and
238.Fn X509_STORE_CTX_get_obj_by_subject
239first appeared in OpenSSL 1.1.0 and have been available since
240.Ox 7.1 .
241.Pp
242.Fn X509_STORE_CTX_get1_certs
243and
244.Fn X509_STORE_CTX_get1_crls
245first appeared in OpenSSL 1.1.0 and have been available since
246.Ox 7.4 .
247