secure/lib/libcrypto/man/man3/OSSL_STORE_SEARCH.3

   1 .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 .    ds C`
  42 .    ds C'
  43 'br\}
  44 .\"
  45 .\" Escape single quotes in literal strings from groff's Unicode transform.
  46 .ie \n(.g .ds Aq \(aq
  47 .el       .ds Aq '
  48 .\"
  49 .\" If the F register is >0, we'll generate index entries on stderr for
  50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  51 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  52 .\" output yourself in some meaningful fashion.
  53 .\"
  54 .\" Avoid warning from groff about undefined register 'F'.
  55 .de IX
  56 ..
  57 .nr rF 0
  58 .if \n(.g .if rF .nr rF 1
  59 .if (\n(rF:(\n(.g==0)) \{\
  60 .    if \nF \{\
  61 .        de IX
  62 .        tm Index:\\$1\t\\n%\t"\\$2"
  63 ..
  64 .        if !\nF==2 \{\
  65 .            nr % 0
  66 .            nr F 2
  67 .        \}
  68 .    \}
  69 .\}
  70 .rr rF
  71 .\"
  72 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  73 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  74 .    \" fudge factors for nroff and troff
  75 .if n \{\
  76 .    ds #H 0
  77 .    ds #V .8m
  78 .    ds #F .3m
  79 .    ds #[ \f1
  80 .    ds #] \fP
  81 .\}
  82 .if t \{\
  83 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  84 .    ds #V .6m
  85 .    ds #F 0
  86 .    ds #[ \&
  87 .    ds #] \&
  88 .\}
  89 .    \" simple accents for nroff and troff
  90 .if n \{\
  91 .    ds ' \&
  92 .    ds ` \&
  93 .    ds ^ \&
  94 .    ds , \&
  95 .    ds ~ ~
  96 .    ds /
  97 .\}
  98 .if t \{\
  99 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 100 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 101 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 102 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 103 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 104 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 105 .\}
 106 .    \" troff and (daisy-wheel) nroff accents
 107 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 108 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 109 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 110 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 111 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 112 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 113 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 114 .ds ae a\h'-(\w'a'u*4/10)'e
 115 .ds Ae A\h'-(\w'A'u*4/10)'E
 116 .    \" corrections for vroff
 117 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 118 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 119 .    \" for low resolution devices (crt and lpr)
 120 .if \n(.H>23 .if \n(.V>19 \
 121 \{\
 122 .    ds : e
 123 .    ds 8 ss
 124 .    ds o a
 125 .    ds d- d\h'-1'\(ga
 126 .    ds D- D\h'-1'\(hy
 127 .    ds th \o'bp'
 128 .    ds Th \o'LP'
 129 .    ds ae ae
 130 .    ds Ae AE
 131 .\}
 132 .rm #[ #] #H #V #F C
 133 .\" ========================================================================
 134 .\"
 135 .IX Title "OSSL_STORE_SEARCH 3"
 136 .TH OSSL_STORE_SEARCH 3 "2020-09-22" "1.1.1h" "OpenSSL"
 137 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 138 .\" way too many mistakes in technical documents.
 139 .if n .ad l
 140 .nh
 141 .SH "NAME"
 142 OSSL_STORE_SEARCH, OSSL_STORE_SEARCH_by_name, OSSL_STORE_SEARCH_by_issuer_serial, OSSL_STORE_SEARCH_by_key_fingerprint, OSSL_STORE_SEARCH_by_alias, OSSL_STORE_SEARCH_free, OSSL_STORE_SEARCH_get_type, OSSL_STORE_SEARCH_get0_name, OSSL_STORE_SEARCH_get0_serial, OSSL_STORE_SEARCH_get0_bytes, OSSL_STORE_SEARCH_get0_string, OSSL_STORE_SEARCH_get0_digest \&\- Type and functions to create OSSL_STORE search criteria
 143 .SH "SYNOPSIS"
 144 .IX Header "SYNOPSIS"
 145 .Vb 1
 146 \& #include <openssl/store.h>
 147 \&
 148 \& typedef struct ossl_store_search_st OSSL_STORE_SEARCH;
 149 \&
 150 \& OSSL_STORE_SEARCH *OSSL_STORE_SEARCH_by_name(X509_NAME *name);
 151 \& OSSL_STORE_SEARCH *OSSL_STORE_SEARCH_by_issuer_serial(X509_NAME *name,
 152 \&                                                       const ASN1_INTEGER
 153 \&                                                       *serial);
 154 \& OSSL_STORE_SEARCH *OSSL_STORE_SEARCH_by_key_fingerprint(const EVP_MD *digest,
 155 \&                                                         const unsigned char
 156 \&                                                         *bytes, int len);
 157 \& OSSL_STORE_SEARCH *OSSL_STORE_SEARCH_by_alias(const char *alias);
 158 \&
 159 \& void OSSL_STORE_SEARCH_free(OSSL_STORE_SEARCH *search);
 160 \&
 161 \& int OSSL_STORE_SEARCH_get_type(const OSSL_STORE_SEARCH *criterion);
 162 \& X509_NAME *OSSL_STORE_SEARCH_get0_name(OSSL_STORE_SEARCH *criterion);
 163 \& const ASN1_INTEGER *OSSL_STORE_SEARCH_get0_serial(const OSSL_STORE_SEARCH
 164 \&                                                   *criterion);
 165 \& const unsigned char *OSSL_STORE_SEARCH_get0_bytes(const OSSL_STORE_SEARCH
 166 \&                                                   *criterion, size_t *length);
 167 \& const char *OSSL_STORE_SEARCH_get0_string(const OSSL_STORE_SEARCH *criterion);
 168 \& const EVP_MD *OSSL_STORE_SEARCH_get0_digest(const OSSL_STORE_SEARCH
 169 \&                                             *criterion);
 170 .Ve
 171 .SH "DESCRIPTION"
 172 .IX Header "DESCRIPTION"
 173 These functions are used to specify search criteria to help search for specific
 174 objects through other names than just the \s-1URI\s0 that's given to \fBOSSL_STORE_open()\fR.
 175 For example, this can be useful for an application that has received a \s-1URI\s0
 176 and then wants to add on search criteria in a uniform and supported manner.
 177 .SS "Types"
 178 .IX Subsection "Types"
 179 \&\fB\s-1OSSL_STORE_SEARCH\s0\fR is an opaque type that holds the constructed search
 180 criterion, and that can be given to an \s-1OSSL_STORE\s0 context with
 181 \&\fBOSSL_STORE_find()\fR.
 182 .PP
 183 The calling application owns the allocation of an \fB\s-1OSSL_STORE_SEARCH\s0\fR at all
 184 times, and should therefore be careful not to deallocate it before
 185 \&\fBOSSL_STORE_close()\fR has been called for the \s-1OSSL_STORE\s0 context it was given
 186 to.
 187 .SS "Application Functions"
 188 .IX Subsection "Application Functions"
 189 \&\fBOSSL_STORE_SEARCH_by_name()\fR,
 190 \&\fBOSSL_STORE_SEARCH_by_issuer_serial()\fR,
 191 \&\fBOSSL_STORE_SEARCH_by_key_fingerprint()\fR,
 192 and \fBOSSL_STORE_SEARCH_by_alias()\fR
 193 are used to create an \fB\s-1OSSL_STORE_SEARCH\s0\fR from a subject name, an issuer name
 194 and serial number pair, a key fingerprint, and an alias (for example a friendly
 195 name).
 196 The parameters that are provided are not copied, only referred to in a
 197 criterion, so they must have at least the same life time as the created
 198 \&\fB\s-1OSSL_STORE_SEARCH\s0\fR.
 199 .PP
 200 \&\fBOSSL_STORE_SEARCH_free()\fR is used to free the \fB\s-1OSSL_STORE_SEARCH\s0\fR.
 201 .SS "Loader Functions"
 202 .IX Subsection "Loader Functions"
 203 \&\fBOSSL_STORE_SEARCH_get_type()\fR returns the criterion type for the given
 204 \&\fB\s-1OSSL_STORE_SEARCH\s0\fR.
 205 .PP
 206 \&\fBOSSL_STORE_SEARCH_get0_name()\fR, \fBOSSL_STORE_SEARCH_get0_serial()\fR,
 207 \&\fBOSSL_STORE_SEARCH_get0_bytes()\fR, \fBOSSL_STORE_SEARCH_get0_string()\fR,
 208 and \fBOSSL_STORE_SEARCH_get0_digest()\fR
 209 are used to retrieve different data from a \fB\s-1OSSL_STORE_SEARCH\s0\fR, as
 210 available for each type.
 211 For more information, see \*(L"\s-1SUPPORTED CRITERION TYPES\*(R"\s0 below.
 212 .SH "SUPPORTED CRITERION TYPES"
 213 .IX Header "SUPPORTED CRITERION TYPES"
 214 Currently supported criterion types are:
 215 .IP "\s-1OSSL_STORE_SEARCH_BY_NAME\s0" 4
 216 .IX Item "OSSL_STORE_SEARCH_BY_NAME"
 217 This criterion supports a search by exact match of subject name.
 218 The subject name itself is a \fBX509_NAME\fR pointer.
 219 A criterion of this type is created with \fBOSSL_STORE_SEARCH_by_name()\fR,
 220 and the actual subject name is retrieved with \fBOSSL_STORE_SEARCH_get0_name()\fR.
 221 .IP "\s-1OSSL_STORE_SEARCH_BY_ISSUER_SERIAL\s0" 4
 222 .IX Item "OSSL_STORE_SEARCH_BY_ISSUER_SERIAL"
 223 This criterion supports a search by exact match of both issuer name and serial
 224 number.
 225 The issuer name itself is a \fBX509_NAME\fR pointer, and the serial number is
 226 a \fB\s-1ASN1_INTEGER\s0\fR pointer.
 227 A criterion of this type is created with \fBOSSL_STORE_SEARCH_by_issuer_serial()\fR
 228 and the actual issuer name and serial number are retrieved with
 229 \&\fBOSSL_STORE_SEARCH_get0_name()\fR and \fBOSSL_STORE_SEARCH_get0_serial()\fR.
 230 .IP "\s-1OSSL_STORE_SEARCH_BY_KEY_FINGERPRINT\s0" 4
 231 .IX Item "OSSL_STORE_SEARCH_BY_KEY_FINGERPRINT"
 232 This criterion supports a search by exact match of key fingerprint.
 233 The key fingerprint in itself is a string of bytes and its length, as
 234 well as the algorithm that was used to compute the fingerprint.
 235 The digest may be left unspecified (\s-1NULL\s0), and in that case, the
 236 loader has to decide on a default digest and compare fingerprints
 237 accordingly.
 238 A criterion of this type is created with \fBOSSL_STORE_SEARCH_by_key_fingerprint()\fR
 239 and the actual fingerprint and its length can be retrieved with
 240 \&\fBOSSL_STORE_SEARCH_get0_bytes()\fR.
 241 The digest can be retrieved with \fBOSSL_STORE_SEARCH_get0_digest()\fR.
 242 .IP "\s-1OSSL_STORE_SEARCH_BY_ALIAS\s0" 4
 243 .IX Item "OSSL_STORE_SEARCH_BY_ALIAS"
 244 This criterion supports a search by match of an alias of some kind.
 245 The alias in itself is a simple C string.
 246 A criterion of this type is created with \fBOSSL_STORE_SEARCH_by_alias()\fR
 247 and the actual alias is retrieved with \fBOSSL_STORE_SEARCH_get0_string()\fR.
 248 .SH "RETURN VALUES"
 249 .IX Header "RETURN VALUES"
 250 \&\fBOSSL_STORE_SEARCH_by_name()\fR,
 251 \&\fBOSSL_STORE_SEARCH_by_issuer_serial()\fR,
 252 \&\fBOSSL_STORE_SEARCH_by_key_fingerprint()\fR,
 253 and \fBOSSL_STORE_SEARCH_by_alias()\fR
 254 return a \fB\s-1OSSL_STORE_SEARCH\s0\fR pointer on success, or \fB\s-1NULL\s0\fR on failure.
 255 .PP
 256 \&\fBOSSL_STORE_SEARCH_get_type()\fR returns the criterion type of the given
 257 \&\fB\s-1OSSL_STORE_SEARCH\s0\fR.
 258 There is no error value.
 259 .PP
 260 \&\fBOSSL_STORE_SEARCH_get0_name()\fR returns a \fBX509_NAME\fR pointer on success,
 261 or \fB\s-1NULL\s0\fR when the given \fB\s-1OSSL_STORE_SEARCH\s0\fR was of a different type.
 262 .PP
 263 \&\fBOSSL_STORE_SEARCH_get0_serial()\fR returns a \fB\s-1ASN1_INTEGER\s0\fR pointer on success,
 264 or \fB\s-1NULL\s0\fR when the given \fB\s-1OSSL_STORE_SEARCH\s0\fR was of a different type.
 265 .PP
 266 \&\fBOSSL_STORE_SEARCH_get0_bytes()\fR returns a \fBconst unsigned char\fR pointer and
 267 sets \fB*length\fR to the strings length on success, or \fB\s-1NULL\s0\fR when the given
 268 \&\fB\s-1OSSL_STORE_SEARCH\s0\fR was of a different type.
 269 .PP
 270 \&\fBOSSL_STORE_SEARCH_get0_string()\fR returns a \fBconst char\fR pointer on success,
 271 or \fB\s-1NULL\s0\fR when the given \fB\s-1OSSL_STORE_SEARCH\s0\fR was of a different type.
 272 .PP
 273 \&\fBOSSL_STORE_SEARCH_get0_digest()\fR returns a \fBconst \s-1EVP_MD\s0\fR pointer.
 274 \&\fB\s-1NULL\s0\fR is a valid value and means that the store loader default will
 275 be used when applicable.
 276 .SH "SEE ALSO"
 277 .IX Header "SEE ALSO"
 278 \&\fBossl_store\fR\|(7), \fBOSSL_STORE_supports_search\fR\|(3), \fBOSSL_STORE_find\fR\|(3)
 279 .SH "HISTORY"
 280 .IX Header "HISTORY"
 281 \&\fB\s-1OSSL_STORE_SEARCH\s0\fR,
 282 \&\fBOSSL_STORE_SEARCH_by_name()\fR,
 283 \&\fBOSSL_STORE_SEARCH_by_issuer_serial()\fR,
 284 \&\fBOSSL_STORE_SEARCH_by_key_fingerprint()\fR,
 285 \&\fBOSSL_STORE_SEARCH_by_alias()\fR,
 286 \&\fBOSSL_STORE_SEARCH_free()\fR,
 287 \&\fBOSSL_STORE_SEARCH_get_type()\fR,
 288 \&\fBOSSL_STORE_SEARCH_get0_name()\fR,
 289 \&\fBOSSL_STORE_SEARCH_get0_serial()\fR,
 290 \&\fBOSSL_STORE_SEARCH_get0_bytes()\fR,
 291 and \fBOSSL_STORE_SEARCH_get0_string()\fR
 292 were added in OpenSSL 1.1.1.
 293 .SH "COPYRIGHT"
 294 .IX Header "COPYRIGHT"
 295 Copyright 2018 The OpenSSL Project Authors. All Rights Reserved.
 296 .PP
 297 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 298 this file except in compliance with the License.  You can obtain a copy
 299 in the file \s-1LICENSE\s0 in the source distribution or at
 300 <https://www.openssl.org/source/license.html>.