doc/man3/OSSL_STORE_SEARCH.pod

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