1OSSL_STORE_SEARCH(3)                OpenSSL               OSSL_STORE_SEARCH(3)
2
3
4

NAME

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

SYNOPSIS

16        #include <openssl/store.h>
17
18        typedef struct ossl_store_search_st OSSL_STORE_SEARCH;
19
20        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
29        void OSSL_STORE_SEARCH_free(OSSL_STORE_SEARCH *search);
30
31        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

DESCRIPTION

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
48   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
53       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
58   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
68       OSSL_STORE_SEARCH_free() is used to free the OSSL_STORE_SEARCH.
69
70   Loader Functions
71       OSSL_STORE_SEARCH_get_type() returns the criterion type for the given
72       OSSL_STORE_SEARCH.
73
74       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

SUPPORTED CRITERION TYPES

81       Currently supported criterion types are:
82
83       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
90       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
98       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
110       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

RETURN VALUES

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
122       OSSL_STORE_SEARCH_get_type() returns the criterion type of the given
123       OSSL_STORE_SEARCH.  There is no error value.
124
125       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
128       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
132       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
136       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
140       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

SEE ALSO

145       ossl_store(7), OSSL_STORE_supports_search(3), OSSL_STORE_find(3)
146

HISTORY

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 The OpenSSL Project Authors. All Rights Reserved.
158
159       Licensed under the OpenSSL license (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>.
163
164
165
1661.1.1q                            2023-02-06              OSSL_STORE_SEARCH(3)
Impressum