1OSSL_STORE_SEARCH(3ossl) OpenSSL OSSL_STORE_SEARCH(3ossl)
2
6 OSSL_STORE_SEARCH, OSSL_STORE_SEARCH_by_name,
7 OSSL_STORE_SEARCH_by_issuer_serial,
8 OSSL_STORE_SEARCH_by_key_fingerprint, OSSL_STORE_SEARCH_by_alias,
9 OSSL_STORE_SEARCH_free, OSSL_STORE_SEARCH_get_type,
10 OSSL_STORE_SEARCH_get0_name, OSSL_STORE_SEARCH_get0_serial,
11 OSSL_STORE_SEARCH_get0_bytes, OSSL_STORE_SEARCH_get0_string,
12 OSSL_STORE_SEARCH_get0_digest - Type and functions to create OSSL_STORE
13 search criteria
14
16 #include <openssl/store.h>
17 typedef struct ossl_store_search_st OSSL_STORE_SEARCH;
19 OSSL_STORE_SEARCH *OSSL_STORE_SEARCH_by_name(X509_NAME *name);
21 OSSL_STORE_SEARCH *OSSL_STORE_SEARCH_by_issuer_serial(X509_NAME *name,
22 const ASN1_INTEGER
23 *serial);
24 OSSL_STORE_SEARCH *OSSL_STORE_SEARCH_by_key_fingerprint(const EVP_MD *digest,
25 const unsigned char
26 *bytes, int len);
27 OSSL_STORE_SEARCH *OSSL_STORE_SEARCH_by_alias(const char *alias);
28 void OSSL_STORE_SEARCH_free(OSSL_STORE_SEARCH *search);
30 int OSSL_STORE_SEARCH_get_type(const OSSL_STORE_SEARCH *criterion);
32 X509_NAME *OSSL_STORE_SEARCH_get0_name(OSSL_STORE_SEARCH *criterion);
33 const ASN1_INTEGER *OSSL_STORE_SEARCH_get0_serial(const OSSL_STORE_SEARCH
34 *criterion);
35 const unsigned char *OSSL_STORE_SEARCH_get0_bytes(const OSSL_STORE_SEARCH
36 *criterion, size_t *length);
37 const char *OSSL_STORE_SEARCH_get0_string(const OSSL_STORE_SEARCH *criterion);
38 const EVP_MD *OSSL_STORE_SEARCH_get0_digest(const OSSL_STORE_SEARCH
39 *criterion);
40
42 These functions are used to specify search criteria to help search for
43 specific objects through other names than just the URI that's given to
44 OSSL_STORE_open(). For example, this can be useful for an application
45 that has received a URI and then wants to add on search criteria in a
46 uniform and supported manner.
47 Types
49 OSSL_STORE_SEARCH is an opaque type that holds the constructed search
50 criterion, and that can be given to an OSSL_STORE context with
51 OSSL_STORE_find().
52 The calling application owns the allocation of an OSSL_STORE_SEARCH at
54 all times, and should therefore be careful not to deallocate it before
55 OSSL_STORE_close() has been called for the OSSL_STORE context it was
56 given to.
57 Application Functions
59 OSSL_STORE_SEARCH_by_name(), OSSL_STORE_SEARCH_by_issuer_serial(),
60 OSSL_STORE_SEARCH_by_key_fingerprint(), and
61 OSSL_STORE_SEARCH_by_alias() are used to create an OSSL_STORE_SEARCH
62 from a subject name, an issuer name and serial number pair, a key
63 fingerprint, and an alias (for example a friendly name). The
64 parameters that are provided are not copied, only referred to in a
65 criterion, so they must have at least the same life time as the created
66 OSSL_STORE_SEARCH.
67 OSSL_STORE_SEARCH_free() is used to free the OSSL_STORE_SEARCH.
69 Loader Functions
71 OSSL_STORE_SEARCH_get_type() returns the criterion type for the given
72 OSSL_STORE_SEARCH.
73 OSSL_STORE_SEARCH_get0_name(), OSSL_STORE_SEARCH_get0_serial(),
75 OSSL_STORE_SEARCH_get0_bytes(), OSSL_STORE_SEARCH_get0_string(), and
76 OSSL_STORE_SEARCH_get0_digest() are used to retrieve different data
77 from a OSSL_STORE_SEARCH, as available for each type. For more
78 information, see "SUPPORTED CRITERION TYPES" below.
79
81 Currently supported criterion types are:
82 OSSL_STORE_SEARCH_BY_NAME
84 This criterion supports a search by exact match of subject name.
85 The subject name itself is a X509_NAME pointer. A criterion of
86 this type is created with OSSL_STORE_SEARCH_by_name(), and the
87 actual subject name is retrieved with
88 OSSL_STORE_SEARCH_get0_name().
89 OSSL_STORE_SEARCH_BY_ISSUER_SERIAL
91 This criterion supports a search by exact match of both issuer name
92 and serial number. The issuer name itself is a X509_NAME pointer,
93 and the serial number is a ASN1_INTEGER pointer. A criterion of
94 this type is created with OSSL_STORE_SEARCH_by_issuer_serial() and
95 the actual issuer name and serial number are retrieved with
96 OSSL_STORE_SEARCH_get0_name() and OSSL_STORE_SEARCH_get0_serial().
97 OSSL_STORE_SEARCH_BY_KEY_FINGERPRINT
99 This criterion supports a search by exact match of key fingerprint.
100 The key fingerprint in itself is a string of bytes and its length,
101 as well as the algorithm that was used to compute the fingerprint.
102 The digest may be left unspecified (NULL), and in that case, the
103 loader has to decide on a default digest and compare fingerprints
104 accordingly. A criterion of this type is created with
105 OSSL_STORE_SEARCH_by_key_fingerprint() and the actual fingerprint
106 and its length can be retrieved with
107 OSSL_STORE_SEARCH_get0_bytes(). The digest can be retrieved with
108 OSSL_STORE_SEARCH_get0_digest().
109 OSSL_STORE_SEARCH_BY_ALIAS
111 This criterion supports a search by match of an alias of some kind.
112 The alias in itself is a simple C string. A criterion of this type
113 is created with OSSL_STORE_SEARCH_by_alias() and the actual alias
114 is retrieved with OSSL_STORE_SEARCH_get0_string().
115
117 OSSL_STORE_SEARCH_by_name(), OSSL_STORE_SEARCH_by_issuer_serial(),
118 OSSL_STORE_SEARCH_by_key_fingerprint(), and
119 OSSL_STORE_SEARCH_by_alias() return a OSSL_STORE_SEARCH pointer on
120 success, or NULL on failure.
121 OSSL_STORE_SEARCH_get_type() returns the criterion type of the given
123 OSSL_STORE_SEARCH. There is no error value.
124 OSSL_STORE_SEARCH_get0_name() returns a X509_NAME pointer on success,
126 or NULL when the given OSSL_STORE_SEARCH was of a different type.
127 OSSL_STORE_SEARCH_get0_serial() returns a ASN1_INTEGER pointer on
129 success, or NULL when the given OSSL_STORE_SEARCH was of a different
130 type.
131 OSSL_STORE_SEARCH_get0_bytes() returns a const unsigned char pointer
133 and sets *length to the strings length on success, or NULL when the
134 given OSSL_STORE_SEARCH was of a different type.
135 OSSL_STORE_SEARCH_get0_string() returns a const char pointer on
137 success, or NULL when the given OSSL_STORE_SEARCH was of a different
138 type.
139 OSSL_STORE_SEARCH_get0_digest() returns a const EVP_MD pointer. NULL
141 is a valid value and means that the store loader default will be used
142 when applicable.
143
145 ossl_store(7), OSSL_STORE_supports_search(3), OSSL_STORE_find(3)
146
148 OSSL_STORE_SEARCH, OSSL_STORE_SEARCH_by_name(),
149 OSSL_STORE_SEARCH_by_issuer_serial(),
150 OSSL_STORE_SEARCH_by_key_fingerprint(), OSSL_STORE_SEARCH_by_alias(),
151 OSSL_STORE_SEARCH_free(), OSSL_STORE_SEARCH_get_type(),
152 OSSL_STORE_SEARCH_get0_name(), OSSL_STORE_SEARCH_get0_serial(),
153 OSSL_STORE_SEARCH_get0_bytes(), and OSSL_STORE_SEARCH_get0_string()
154 were added in OpenSSL 1.1.1.
155
157 Copyright 2018-2020 The OpenSSL Project Authors. All Rights Reserved.
158 Licensed under the Apache License 2.0 (the "License"). You may not use
160 this file except in compliance with the License. You can obtain a copy
161 in the file LICENSE in the source distribution or at
162 <https://www.openssl.org/source/license.html>.
1633.1.1 2023-08-31 OSSL_STORE_SEARCH(3ossl)