Debian Codegraph @

upstream/debian-unstable/man3/OSSL_STORE_SEARCH.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "OSSL_STORE_SEARCH 3SSL"
58 .TH OSSL_STORE_SEARCH 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 OSSL_STORE_SEARCH,
65 OSSL_STORE_SEARCH_by_name,
66 OSSL_STORE_SEARCH_by_issuer_serial,
67 OSSL_STORE_SEARCH_by_key_fingerprint,
68 OSSL_STORE_SEARCH_by_alias,
69 OSSL_STORE_SEARCH_free,
70 OSSL_STORE_SEARCH_get_type,
71 OSSL_STORE_SEARCH_get0_name,
72 OSSL_STORE_SEARCH_get0_serial,
73 OSSL_STORE_SEARCH_get0_bytes,
74 OSSL_STORE_SEARCH_get0_string,
75 OSSL_STORE_SEARCH_get0_digest
76 \&\- Type and functions to create OSSL_STORE search criteria
77 .SH SYNOPSIS
78 .IX Header "SYNOPSIS"
79 .Vb 1
80 \& #include <openssl/store.h>
81 \&
82 \& typedef struct ossl_store_search_st OSSL_STORE_SEARCH;
83 \&
84 \& OSSL_STORE_SEARCH *OSSL_STORE_SEARCH_by_name(X509_NAME *name);
85 \& OSSL_STORE_SEARCH *OSSL_STORE_SEARCH_by_issuer_serial(X509_NAME *name,
86 \& const ASN1_INTEGER
87 \& *serial);
88 \& OSSL_STORE_SEARCH *OSSL_STORE_SEARCH_by_key_fingerprint(const EVP_MD *digest,
89 \& const unsigned char
90 \& *bytes, int len);
91 \& OSSL_STORE_SEARCH *OSSL_STORE_SEARCH_by_alias(const char *alias);
92 \&
93 \& void OSSL_STORE_SEARCH_free(OSSL_STORE_SEARCH *search);
94 \&
95 \& int OSSL_STORE_SEARCH_get_type(const OSSL_STORE_SEARCH *criterion);
96 \& X509_NAME *OSSL_STORE_SEARCH_get0_name(OSSL_STORE_SEARCH *criterion);
97 \& const ASN1_INTEGER *OSSL_STORE_SEARCH_get0_serial(const OSSL_STORE_SEARCH
98 \& *criterion);
99 \& const unsigned char *OSSL_STORE_SEARCH_get0_bytes(const OSSL_STORE_SEARCH
100 \& *criterion, size_t *length);
101 \& const char *OSSL_STORE_SEARCH_get0_string(const OSSL_STORE_SEARCH *criterion);
102 \& const EVP_MD *OSSL_STORE_SEARCH_get0_digest(const OSSL_STORE_SEARCH
103 \& *criterion);
104 .Ve
105 .SH DESCRIPTION
106 .IX Header "DESCRIPTION"
107 These functions are used to specify search criteria to help search for specific
108 objects through other names than just the URI that's given to \fBOSSL_STORE_open()\fR.
109 For example, this can be useful for an application that has received a URI
110 and then wants to add on search criteria in a uniform and supported manner.
111 .SS Types
112 .IX Subsection "Types"
113 \&\fBOSSL_STORE_SEARCH\fR is an opaque type that holds the constructed search
114 criterion, and that can be given to an OSSL_STORE context with
115 \&\fBOSSL_STORE_find()\fR.
116 .PP
117 The calling application owns the allocation of an \fBOSSL_STORE_SEARCH\fR at all
118 times, and should therefore be careful not to deallocate it before
119 \&\fBOSSL_STORE_close()\fR has been called for the OSSL_STORE context it was given
120 to.
121 .SS "Application Functions"
122 .IX Subsection "Application Functions"
123 \&\fBOSSL_STORE_SEARCH_by_name()\fR,
124 \&\fBOSSL_STORE_SEARCH_by_issuer_serial()\fR,
125 \&\fBOSSL_STORE_SEARCH_by_key_fingerprint()\fR,
126 and \fBOSSL_STORE_SEARCH_by_alias()\fR
127 are used to create an \fBOSSL_STORE_SEARCH\fR from a subject name, an issuer name
128 and serial number pair, a key fingerprint, and an alias (for example a friendly
129 name).
130 The parameters that are provided are not copied, only referred to in a
131 criterion, so they must have at least the same life time as the created
132 \&\fBOSSL_STORE_SEARCH\fR.
133 .PP
134 \&\fBOSSL_STORE_SEARCH_free()\fR is used to free the \fBOSSL_STORE_SEARCH\fR.
135 If the argument is NULL, nothing is done.
136 .SS "Loader Functions"
137 .IX Subsection "Loader Functions"
138 \&\fBOSSL_STORE_SEARCH_get_type()\fR returns the criterion type for the given
139 \&\fBOSSL_STORE_SEARCH\fR.
140 .PP
141 \&\fBOSSL_STORE_SEARCH_get0_name()\fR, \fBOSSL_STORE_SEARCH_get0_serial()\fR,
142 \&\fBOSSL_STORE_SEARCH_get0_bytes()\fR, \fBOSSL_STORE_SEARCH_get0_string()\fR,
143 and \fBOSSL_STORE_SEARCH_get0_digest()\fR
144 are used to retrieve different data from a \fBOSSL_STORE_SEARCH\fR, as
145 available for each type.
146 For more information, see "SUPPORTED CRITERION TYPES" below.
147 .SH "SUPPORTED CRITERION TYPES"
148 .IX Header "SUPPORTED CRITERION TYPES"
149 Currently supported criterion types are:
150 .IP OSSL_STORE_SEARCH_BY_NAME 4
151 .IX Item "OSSL_STORE_SEARCH_BY_NAME"
152 This criterion supports a search by exact match of subject name.
153 The subject name itself is a \fBX509_NAME\fR pointer.
154 A criterion of this type is created with \fBOSSL_STORE_SEARCH_by_name()\fR,
155 and the actual subject name is retrieved with \fBOSSL_STORE_SEARCH_get0_name()\fR.
156 .IP OSSL_STORE_SEARCH_BY_ISSUER_SERIAL 4
157 .IX Item "OSSL_STORE_SEARCH_BY_ISSUER_SERIAL"
158 This criterion supports a search by exact match of both issuer name and serial
159 number.
160 The issuer name itself is a \fBX509_NAME\fR pointer, and the serial number is
161 a \fBASN1_INTEGER\fR pointer.
162 A criterion of this type is created with \fBOSSL_STORE_SEARCH_by_issuer_serial()\fR
163 and the actual issuer name and serial number are retrieved with
164 \&\fBOSSL_STORE_SEARCH_get0_name()\fR and \fBOSSL_STORE_SEARCH_get0_serial()\fR.
165 .IP OSSL_STORE_SEARCH_BY_KEY_FINGERPRINT 4
166 .IX Item "OSSL_STORE_SEARCH_BY_KEY_FINGERPRINT"
167 This criterion supports a search by exact match of key fingerprint.
168 The key fingerprint in itself is a string of bytes and its length, as
169 well as the algorithm that was used to compute the fingerprint.
170 The digest may be left unspecified (NULL), and in that case, the
171 loader has to decide on a default digest and compare fingerprints
172 accordingly.
173 A criterion of this type is created with \fBOSSL_STORE_SEARCH_by_key_fingerprint()\fR
174 and the actual fingerprint and its length can be retrieved with
175 \&\fBOSSL_STORE_SEARCH_get0_bytes()\fR.
176 The digest can be retrieved with \fBOSSL_STORE_SEARCH_get0_digest()\fR.
177 .IP OSSL_STORE_SEARCH_BY_ALIAS 4
178 .IX Item "OSSL_STORE_SEARCH_BY_ALIAS"
179 This criterion supports a search by match of an alias of some kind.
180 The alias in itself is a simple C string.
181 A criterion of this type is created with \fBOSSL_STORE_SEARCH_by_alias()\fR
182 and the actual alias is retrieved with \fBOSSL_STORE_SEARCH_get0_string()\fR.
183 .SH "RETURN VALUES"
184 .IX Header "RETURN VALUES"
185 \&\fBOSSL_STORE_SEARCH_by_name()\fR,
186 \&\fBOSSL_STORE_SEARCH_by_issuer_serial()\fR,
187 \&\fBOSSL_STORE_SEARCH_by_key_fingerprint()\fR,
188 and \fBOSSL_STORE_SEARCH_by_alias()\fR
189 return a \fBOSSL_STORE_SEARCH\fR pointer on success, or NULL on failure.
190 .PP
191 \&\fBOSSL_STORE_SEARCH_get_type()\fR returns the criterion type of the given
192 \&\fBOSSL_STORE_SEARCH\fR.
193 There is no error value.
194 .PP
195 \&\fBOSSL_STORE_SEARCH_get0_name()\fR returns a \fBX509_NAME\fR pointer on success,
196 or NULL when the given \fBOSSL_STORE_SEARCH\fR was of a different type.
197 .PP
198 \&\fBOSSL_STORE_SEARCH_get0_serial()\fR returns a \fBASN1_INTEGER\fR pointer on success,
199 or NULL when the given \fBOSSL_STORE_SEARCH\fR was of a different type.
200 .PP
201 \&\fBOSSL_STORE_SEARCH_get0_bytes()\fR returns a \fBconst unsigned char\fR pointer and
202 sets \fI*length\fR to the strings length on success, or NULL when the given
203 \&\fBOSSL_STORE_SEARCH\fR was of a different type.
204 .PP
205 \&\fBOSSL_STORE_SEARCH_get0_string()\fR returns a \fBconst char\fR pointer on success,
206 or NULL when the given \fBOSSL_STORE_SEARCH\fR was of a different type.
207 .PP
208 \&\fBOSSL_STORE_SEARCH_get0_digest()\fR returns a \fBconst EVP_MD\fR pointer.
209 NULL is a valid value and means that the store loader default will
210 be used when applicable.
211 .SH "SEE ALSO"
212 .IX Header "SEE ALSO"
213 \&\fBossl_store\fR\|(7), \fBOSSL_STORE_supports_search\fR\|(3), \fBOSSL_STORE_find\fR\|(3)
214 .SH HISTORY
215 .IX Header "HISTORY"
216 \&\fBOSSL_STORE_SEARCH\fR,
217 \&\fBOSSL_STORE_SEARCH_by_name()\fR,
218 \&\fBOSSL_STORE_SEARCH_by_issuer_serial()\fR,
219 \&\fBOSSL_STORE_SEARCH_by_key_fingerprint()\fR,
220 \&\fBOSSL_STORE_SEARCH_by_alias()\fR,
221 \&\fBOSSL_STORE_SEARCH_free()\fR,
222 \&\fBOSSL_STORE_SEARCH_get_type()\fR,
223 \&\fBOSSL_STORE_SEARCH_get0_name()\fR,
224 \&\fBOSSL_STORE_SEARCH_get0_serial()\fR,
225 \&\fBOSSL_STORE_SEARCH_get0_bytes()\fR,
226 and \fBOSSL_STORE_SEARCH_get0_string()\fR
227 were added in OpenSSL 1.1.1.
228 .SH COPYRIGHT
229 .IX Header "COPYRIGHT"
230 Copyright 2018\-2024 The OpenSSL Project Authors. All Rights Reserved.
231 .PP
232 Licensed under the Apache License 2.0 (the "License"). You may not use
233 this file except in compliance with the License. You can obtain a copy
234 in the file LICENSE in the source distribution or at
235 <https://www.openssl.org/source/license.html>.