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>. 78 79=head2 Loader Functions 80 81OSSL_STORE_SEARCH_get_type() returns the criterion type for the given 82B<OSSL_STORE_SEARCH>. 83 84OSSL_STORE_SEARCH_get0_name(), OSSL_STORE_SEARCH_get0_serial(), 85OSSL_STORE_SEARCH_get0_bytes(), OSSL_STORE_SEARCH_get0_string(), 86and OSSL_STORE_SEARCH_get0_digest() 87are used to retrieve different data from a B<OSSL_STORE_SEARCH>, as 88available for each type. 89For more information, see L</SUPPORTED CRITERION TYPES> below. 90 91=head1 SUPPORTED CRITERION TYPES 92 93Currently supported criterion types are: 94 95=over 4 96 97=item OSSL_STORE_SEARCH_BY_NAME 98 99This criterion supports a search by exact match of subject name. 100The subject name itself is a B<X509_NAME> pointer. 101A criterion of this type is created with OSSL_STORE_SEARCH_by_name(), 102and the actual subject name is retrieved with OSSL_STORE_SEARCH_get0_name(). 103 104=item OSSL_STORE_SEARCH_BY_ISSUER_SERIAL 105 106This criterion supports a search by exact match of both issuer name and serial 107number. 108The issuer name itself is a B<X509_NAME> pointer, and the serial number is 109a B<ASN1_INTEGER> pointer. 110A criterion of this type is created with OSSL_STORE_SEARCH_by_issuer_serial() 111and the actual issuer name and serial number are retrieved with 112OSSL_STORE_SEARCH_get0_name() and OSSL_STORE_SEARCH_get0_serial(). 113 114=item OSSL_STORE_SEARCH_BY_KEY_FINGERPRINT 115 116This criterion supports a search by exact match of key fingerprint. 117The key fingerprint in itself is a string of bytes and its length, as 118well as the algorithm that was used to compute the fingerprint. 119The digest may be left unspecified (NULL), and in that case, the 120loader has to decide on a default digest and compare fingerprints 121accordingly. 122A criterion of this type is created with OSSL_STORE_SEARCH_by_key_fingerprint() 123and the actual fingerprint and its length can be retrieved with 124OSSL_STORE_SEARCH_get0_bytes(). 125The digest can be retrieved with OSSL_STORE_SEARCH_get0_digest(). 126 127=item OSSL_STORE_SEARCH_BY_ALIAS 128 129This criterion supports a search by match of an alias of some kind. 130The alias in itself is a simple C string. 131A criterion of this type is created with OSSL_STORE_SEARCH_by_alias() 132and the actual alias is retrieved with OSSL_STORE_SEARCH_get0_string(). 133 134=back 135 136=head1 RETURN VALUES 137 138OSSL_STORE_SEARCH_by_name(), 139OSSL_STORE_SEARCH_by_issuer_serial(), 140OSSL_STORE_SEARCH_by_key_fingerprint(), 141and OSSL_STORE_SEARCH_by_alias() 142return a B<OSSL_STORE_SEARCH> pointer on success, or NULL on failure. 143 144OSSL_STORE_SEARCH_get_type() returns the criterion type of the given 145B<OSSL_STORE_SEARCH>. 146There is no error value. 147 148OSSL_STORE_SEARCH_get0_name() returns a B<X509_NAME> pointer on success, 149or NULL when the given B<OSSL_STORE_SEARCH> was of a different type. 150 151OSSL_STORE_SEARCH_get0_serial() returns a B<ASN1_INTEGER> pointer on success, 152or NULL when the given B<OSSL_STORE_SEARCH> was of a different type. 153 154OSSL_STORE_SEARCH_get0_bytes() returns a B<const unsigned char> pointer and 155sets I<*length> to the strings length on success, or NULL when the given 156B<OSSL_STORE_SEARCH> was of a different type. 157 158OSSL_STORE_SEARCH_get0_string() returns a B<const char> pointer on success, 159or NULL when the given B<OSSL_STORE_SEARCH> was of a different type. 160 161OSSL_STORE_SEARCH_get0_digest() returns a B<const EVP_MD> pointer. 162NULL is a valid value and means that the store loader default will 163be used when applicable. 164 165=head1 SEE ALSO 166 167L<ossl_store(7)>, L<OSSL_STORE_supports_search(3)>, L<OSSL_STORE_find(3)> 168 169=head1 HISTORY 170 171B<OSSL_STORE_SEARCH>, 172OSSL_STORE_SEARCH_by_name(), 173OSSL_STORE_SEARCH_by_issuer_serial(), 174OSSL_STORE_SEARCH_by_key_fingerprint(), 175OSSL_STORE_SEARCH_by_alias(), 176OSSL_STORE_SEARCH_free(), 177OSSL_STORE_SEARCH_get_type(), 178OSSL_STORE_SEARCH_get0_name(), 179OSSL_STORE_SEARCH_get0_serial(), 180OSSL_STORE_SEARCH_get0_bytes(), 181and OSSL_STORE_SEARCH_get0_string() 182were added in OpenSSL 1.1.1. 183 184=head1 COPYRIGHT 185 186Copyright 2018-2020 The OpenSSL Project Authors. All Rights Reserved. 187 188Licensed under the Apache License 2.0 (the "License"). You may not use 189this file except in compliance with the License. You can obtain a copy 190in the file LICENSE in the source distribution or at 191L<https://www.openssl.org/source/license.html>. 192 193=cut 194