xref: /openssl/doc/man3/OSSL_STORE_SEARCH.pod (revision 7ed6de99) 
1=pod
2
3=head1 NAME
4
5OSSL_STORE_SEARCH,
6OSSL_STORE_SEARCH_by_name,
7OSSL_STORE_SEARCH_by_issuer_serial,
8OSSL_STORE_SEARCH_by_key_fingerprint,
9OSSL_STORE_SEARCH_by_alias,
10OSSL_STORE_SEARCH_free,
11OSSL_STORE_SEARCH_get_type,
12OSSL_STORE_SEARCH_get0_name,
13OSSL_STORE_SEARCH_get0_serial,
14OSSL_STORE_SEARCH_get0_bytes,
15OSSL_STORE_SEARCH_get0_string,
16OSSL_STORE_SEARCH_get0_digest
17- Type and functions to create OSSL_STORE search criteria
18
19=head1 SYNOPSIS
20
21 #include <openssl/store.h>
22
23 typedef struct ossl_store_search_st OSSL_STORE_SEARCH;
24
25 OSSL_STORE_SEARCH *OSSL_STORE_SEARCH_by_name(X509_NAME *name);
26 OSSL_STORE_SEARCH *OSSL_STORE_SEARCH_by_issuer_serial(X509_NAME *name,
27                                                       const ASN1_INTEGER
28                                                       *serial);
29 OSSL_STORE_SEARCH *OSSL_STORE_SEARCH_by_key_fingerprint(const EVP_MD *digest,
30                                                         const unsigned char
31                                                         *bytes, int len);
32 OSSL_STORE_SEARCH *OSSL_STORE_SEARCH_by_alias(const char *alias);
33
34 void OSSL_STORE_SEARCH_free(OSSL_STORE_SEARCH *search);
35
36 int OSSL_STORE_SEARCH_get_type(const OSSL_STORE_SEARCH *criterion);
37 X509_NAME *OSSL_STORE_SEARCH_get0_name(OSSL_STORE_SEARCH *criterion);
38 const ASN1_INTEGER *OSSL_STORE_SEARCH_get0_serial(const OSSL_STORE_SEARCH
39                                                   *criterion);
40 const unsigned char *OSSL_STORE_SEARCH_get0_bytes(const OSSL_STORE_SEARCH
41                                                   *criterion, size_t *length);
42 const char *OSSL_STORE_SEARCH_get0_string(const OSSL_STORE_SEARCH *criterion);
43 const EVP_MD *OSSL_STORE_SEARCH_get0_digest(const OSSL_STORE_SEARCH
44                                             *criterion);
45
46=head1 DESCRIPTION
47
48These functions are used to specify search criteria to help search for specific
49objects through other names than just the URI that's given to OSSL_STORE_open().
50For example, this can be useful for an application that has received a URI
51and then wants to add on search criteria in a uniform and supported manner.
52
53=head2 Types
54
55B<OSSL_STORE_SEARCH> is an opaque type that holds the constructed search
56criterion, and that can be given to an OSSL_STORE context with
57OSSL_STORE_find().
58
59The calling application owns the allocation of an B<OSSL_STORE_SEARCH> at all
60times, and should therefore be careful not to deallocate it before
61OSSL_STORE_close() has been called for the OSSL_STORE context it was given
62to.
63
64=head2 Application Functions
65
66OSSL_STORE_SEARCH_by_name(),
67OSSL_STORE_SEARCH_by_issuer_serial(),
68OSSL_STORE_SEARCH_by_key_fingerprint(),
69and OSSL_STORE_SEARCH_by_alias()
70are used to create an B<OSSL_STORE_SEARCH> from a subject name, an issuer name
71and serial number pair, a key fingerprint, and an alias (for example a friendly
72name).
73The parameters that are provided are not copied, only referred to in a
74criterion, so they must have at least the same life time as the created
75B<OSSL_STORE_SEARCH>.
76
77OSSL_STORE_SEARCH_free() is used to free the B<OSSL_STORE_SEARCH>.
78If the argument is NULL, nothing is done.
79
80=head2 Loader Functions
81
82OSSL_STORE_SEARCH_get_type() returns the criterion type for the given
83B<OSSL_STORE_SEARCH>.
84
85OSSL_STORE_SEARCH_get0_name(), OSSL_STORE_SEARCH_get0_serial(),
86OSSL_STORE_SEARCH_get0_bytes(), OSSL_STORE_SEARCH_get0_string(),
87and OSSL_STORE_SEARCH_get0_digest()
88are used to retrieve different data from a B<OSSL_STORE_SEARCH>, as
89available for each type.
90For more information, see L</SUPPORTED CRITERION TYPES> below.
91
92=head1 SUPPORTED CRITERION TYPES
93
94Currently supported criterion types are:
95
96=over 4
97
98=item OSSL_STORE_SEARCH_BY_NAME
99
100This criterion supports a search by exact match of subject name.
101The subject name itself is a B<X509_NAME> pointer.
102A criterion of this type is created with OSSL_STORE_SEARCH_by_name(),
103and the actual subject name is retrieved with OSSL_STORE_SEARCH_get0_name().
104
105=item OSSL_STORE_SEARCH_BY_ISSUER_SERIAL
106
107This criterion supports a search by exact match of both issuer name and serial
108number.
109The issuer name itself is a B<X509_NAME> pointer, and the serial number is
110a B<ASN1_INTEGER> pointer.
111A criterion of this type is created with OSSL_STORE_SEARCH_by_issuer_serial()
112and the actual issuer name and serial number are retrieved with
113OSSL_STORE_SEARCH_get0_name() and OSSL_STORE_SEARCH_get0_serial().
114
115=item OSSL_STORE_SEARCH_BY_KEY_FINGERPRINT
116
117This criterion supports a search by exact match of key fingerprint.
118The key fingerprint in itself is a string of bytes and its length, as
119well as the algorithm that was used to compute the fingerprint.
120The digest may be left unspecified (NULL), and in that case, the
121loader has to decide on a default digest and compare fingerprints
122accordingly.
123A criterion of this type is created with OSSL_STORE_SEARCH_by_key_fingerprint()
124and the actual fingerprint and its length can be retrieved with
125OSSL_STORE_SEARCH_get0_bytes().
126The digest can be retrieved with OSSL_STORE_SEARCH_get0_digest().
127
128=item OSSL_STORE_SEARCH_BY_ALIAS
129
130This criterion supports a search by match of an alias of some kind.
131The alias in itself is a simple C string.
132A criterion of this type is created with OSSL_STORE_SEARCH_by_alias()
133and the actual alias is retrieved with OSSL_STORE_SEARCH_get0_string().
134
135=back
136
137=head1 RETURN VALUES
138
139OSSL_STORE_SEARCH_by_name(),
140OSSL_STORE_SEARCH_by_issuer_serial(),
141OSSL_STORE_SEARCH_by_key_fingerprint(),
142and OSSL_STORE_SEARCH_by_alias()
143return a B<OSSL_STORE_SEARCH> pointer on success, or NULL on failure.
144
145OSSL_STORE_SEARCH_get_type() returns the criterion type of the given
146B<OSSL_STORE_SEARCH>.
147There is no error value.
148
149OSSL_STORE_SEARCH_get0_name() returns a B<X509_NAME> pointer on success,
150or NULL when the given B<OSSL_STORE_SEARCH> was of a different type.
151
152OSSL_STORE_SEARCH_get0_serial() returns a B<ASN1_INTEGER> pointer on success,
153or NULL when the given B<OSSL_STORE_SEARCH> was of a different type.
154
155OSSL_STORE_SEARCH_get0_bytes() returns a B<const unsigned char> pointer and
156sets I<*length> to the strings length on success, or NULL when the given
157B<OSSL_STORE_SEARCH> was of a different type.
158
159OSSL_STORE_SEARCH_get0_string() returns a B<const char> pointer on success,
160or NULL when the given B<OSSL_STORE_SEARCH> was of a different type.
161
162OSSL_STORE_SEARCH_get0_digest() returns a B<const EVP_MD> pointer.
163NULL is a valid value and means that the store loader default will
164be used when applicable.
165
166=head1 SEE ALSO
167
168L<ossl_store(7)>, L<OSSL_STORE_supports_search(3)>, L<OSSL_STORE_find(3)>
169
170=head1 HISTORY
171
172B<OSSL_STORE_SEARCH>,
173OSSL_STORE_SEARCH_by_name(),
174OSSL_STORE_SEARCH_by_issuer_serial(),
175OSSL_STORE_SEARCH_by_key_fingerprint(),
176OSSL_STORE_SEARCH_by_alias(),
177OSSL_STORE_SEARCH_free(),
178OSSL_STORE_SEARCH_get_type(),
179OSSL_STORE_SEARCH_get0_name(),
180OSSL_STORE_SEARCH_get0_serial(),
181OSSL_STORE_SEARCH_get0_bytes(),
182and OSSL_STORE_SEARCH_get0_string()
183were added in OpenSSL 1.1.1.
184
185=head1 COPYRIGHT
186
187Copyright 2018-2024 The OpenSSL Project Authors. All Rights Reserved.
188
189Licensed under the Apache License 2.0 (the "License").  You may not use
190this file except in compliance with the License.  You can obtain a copy
191in the file LICENSE in the source distribution or at
192L<https://www.openssl.org/source/license.html>.
193
194=cut
195