secure/lib/libcrypto/man/OSSL_STORE_INFO.3

   1 .\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.39)
   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_INFO 3"
 136 .TH OSSL_STORE_INFO 3 "2019-09-10" "1.1.1d" "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_INFO, OSSL_STORE_INFO_get_type, OSSL_STORE_INFO_get0_NAME, OSSL_STORE_INFO_get0_NAME_description, OSSL_STORE_INFO_get0_PARAMS, OSSL_STORE_INFO_get0_PKEY, OSSL_STORE_INFO_get0_CERT, OSSL_STORE_INFO_get0_CRL, OSSL_STORE_INFO_get1_NAME, OSSL_STORE_INFO_get1_NAME_description, OSSL_STORE_INFO_get1_PARAMS, OSSL_STORE_INFO_get1_PKEY, OSSL_STORE_INFO_get1_CERT, OSSL_STORE_INFO_get1_CRL, OSSL_STORE_INFO_type_string, OSSL_STORE_INFO_free, OSSL_STORE_INFO_new_NAME, OSSL_STORE_INFO_set0_NAME_description, OSSL_STORE_INFO_new_PARAMS, OSSL_STORE_INFO_new_PKEY, OSSL_STORE_INFO_new_CERT, OSSL_STORE_INFO_new_CRL \- Functions to manipulate OSSL_STORE_INFO objects
 143 .SH "SYNOPSIS"
 144 .IX Header "SYNOPSIS"
 145 .Vb 1
 146 \& #include <openssl/store.h>
 147 \&
 148 \& typedef struct ossl_store_info_st OSSL_STORE_INFO;
 149 \&
 150 \& int OSSL_STORE_INFO_get_type(const OSSL_STORE_INFO *store_info);
 151 \& const char *OSSL_STORE_INFO_get0_NAME(const OSSL_STORE_INFO *store_info);
 152 \& char *OSSL_STORE_INFO_get1_NAME(const OSSL_STORE_INFO *store_info);
 153 \& const char *OSSL_STORE_INFO_get0_NAME_description(const OSSL_STORE_INFO
 154 \&                                                   *store_info);
 155 \& char *OSSL_STORE_INFO_get1_NAME_description(const OSSL_STORE_INFO *store_info);
 156 \& EVP_PKEY *OSSL_STORE_INFO_get0_PARAMS(const OSSL_STORE_INFO *store_info);
 157 \& EVP_PKEY *OSSL_STORE_INFO_get1_PARAMS(const OSSL_STORE_INFO *store_info);
 158 \& EVP_PKEY *OSSL_STORE_INFO_get0_PKEY(const OSSL_STORE_INFO *store_info);
 159 \& EVP_PKEY *OSSL_STORE_INFO_get1_PKEY(const OSSL_STORE_INFO *store_info);
 160 \& X509 *OSSL_STORE_INFO_get0_CERT(const OSSL_STORE_INFO *store_info);
 161 \& X509 *OSSL_STORE_INFO_get1_CERT(const OSSL_STORE_INFO *store_info);
 162 \& X509_CRL *OSSL_STORE_INFO_get0_CRL(const OSSL_STORE_INFO *store_info);
 163 \& X509_CRL *OSSL_STORE_INFO_get1_CRL(const OSSL_STORE_INFO *store_info);
 164 \&
 165 \& const char *OSSL_STORE_INFO_type_string(int type);
 166 \&
 167 \& void OSSL_STORE_INFO_free(OSSL_STORE_INFO *store_info);
 168 \&
 169 \& OSSL_STORE_INFO *OSSL_STORE_INFO_new_NAME(char *name);
 170 \& int OSSL_STORE_INFO_set0_NAME_description(OSSL_STORE_INFO *info, char *desc);
 171 \& OSSL_STORE_INFO *OSSL_STORE_INFO_new_PARAMS(DSA *dsa_params);
 172 \& OSSL_STORE_INFO *OSSL_STORE_INFO_new_PKEY(EVP_PKEY *pkey);
 173 \& OSSL_STORE_INFO *OSSL_STORE_INFO_new_CERT(X509 *x509);
 174 \& OSSL_STORE_INFO *OSSL_STORE_INFO_new_CRL(X509_CRL *crl);
 175 .Ve
 176 .SH "DESCRIPTION"
 177 .IX Header "DESCRIPTION"
 178 These functions are primarily useful for applications to retrieve
 179 supported objects from \fB\s-1OSSL_STORE_INFO\s0\fR objects and for scheme specific
 180 loaders to create \fB\s-1OSSL_STORE_INFO\s0\fR holders.
 181 .SS "Types"
 182 .IX Subsection "Types"
 183 \&\fB\s-1OSSL_STORE_INFO\s0\fR is an opaque type that's just an intermediary holder for
 184 the objects that have been retrieved by \fBOSSL_STORE_load()\fR and similar
 185 functions.
 186 Supported OpenSSL type object can be extracted using one of
 187 \&\fBSTORE_INFO_get0_TYPE()\fR.
 188 The life time of this extracted object is as long as the life time of
 189 the \fB\s-1OSSL_STORE_INFO\s0\fR it was extracted from, so care should be taken not
 190 to free the latter too early.
 191 As an alternative, \fBSTORE_INFO_get1_TYPE()\fR extracts a duplicate (or the
 192 same object with its reference count increased), which can be used
 193 after the containing \fB\s-1OSSL_STORE_INFO\s0\fR has been freed.
 194 The object returned by \fBSTORE_INFO_get1_TYPE()\fR must be freed separately
 195 by the caller.
 196 See \*(L"\s-1SUPPORTED OBJECTS\*(R"\s0 for more information on the types that are
 197 supported.
 198 .SS "Functions"
 199 .IX Subsection "Functions"
 200 \&\fBOSSL_STORE_INFO_get_type()\fR takes a \fB\s-1OSSL_STORE_INFO\s0\fR and returns the \s-1STORE\s0
 201 type number for the object inside.
 202 \&\fBSTORE_INFO_get_type_string()\fR takes a \s-1STORE\s0 type number and returns a
 203 short string describing it.
 204 .PP
 205 \&\fBOSSL_STORE_INFO_get0_NAME()\fR, \fBOSSL_STORE_INFO_get0_NAME_description()\fR,
 206 \&\fBOSSL_STORE_INFO_get0_PARAMS()\fR, \fBOSSL_STORE_INFO_get0_PKEY()\fR,
 207 \&\fBOSSL_STORE_INFO_get0_CERT()\fR and \fBOSSL_STORE_INFO_get0_CRL()\fR all take a
 208 \&\fB\s-1OSSL_STORE_INFO\s0\fR and return the held object of the appropriate OpenSSL
 209 type provided that's what's held.
 210 .PP
 211 \&\fBOSSL_STORE_INFO_get1_NAME()\fR, \fBOSSL_STORE_INFO_get1_NAME_description()\fR,
 212 \&\fBOSSL_STORE_INFO_get1_PARAMS()\fR, \fBOSSL_STORE_INFO_get1_PKEY()\fR,
 213 \&\fBOSSL_STORE_INFO_get1_CERT()\fR and \fBOSSL_STORE_INFO_get1_CRL()\fR all take a
 214 \&\fB\s-1OSSL_STORE_INFO\s0\fR and return a duplicate of the held object of the
 215 appropriate OpenSSL type provided that's what's held.
 216 .PP
 217 \&\fBOSSL_STORE_INFO_free()\fR frees a \fB\s-1OSSL_STORE_INFO\s0\fR and its contained type.
 218 .PP
 219 \&\fBOSSL_STORE_INFO_new_NAME()\fR , \fBOSSL_STORE_INFO_new_PARAMS()\fR,
 220 \&\fBOSSL_STORE_INFO_new_PKEY()\fR, \fBOSSL_STORE_INFO_new_CERT()\fR and
 221 \&\fBOSSL_STORE_INFO_new_CRL()\fR create a \fB\s-1OSSL_STORE_INFO\s0\fR
 222 object to hold the given input object.
 223 Additionally, for \fB\s-1OSSL_STORE_INFO_NAME\s0\fR` objects,
 224 \&\fBOSSL_STORE_INFO_set0_NAME_description()\fR can be used to add an extra
 225 description.
 226 This description is meant to be human readable and should be used for
 227 information printout.
 228 .SH "SUPPORTED OBJECTS"
 229 .IX Header "SUPPORTED OBJECTS"
 230 Currently supported object types are:
 231 .IP "\s-1OSSL_STORE_INFO_NAME\s0" 4
 232 .IX Item "OSSL_STORE_INFO_NAME"
 233 A name is exactly that, a name.
 234 It's like a name in a directory, but formatted as a complete \s-1URI.\s0
 235 For example, the path in \s-1URI\s0 \f(CW\*(C`file:/foo/bar/\*(C'\fR could include a file
 236 named \f(CW\*(C`cookie.pem\*(C'\fR, and in that case, the returned \fB\s-1OSSL_STORE_INFO_NAME\s0\fR
 237 object would have the \s-1URI\s0 \f(CW\*(C`file:/foo/bar/cookie.pem\*(C'\fR, which can be
 238 used by the application to get the objects in that file.
 239 This can be applied to all schemes that can somehow support a listing
 240 of object URIs.
 241 .Sp
 242 For \f(CW\*(C`file:\*(C'\fR URIs that are used without the explicit scheme, the
 243 returned name will be the path of each object, so if \f(CW\*(C`/foo/bar\*(C'\fR was
 244 given and that path has the file \f(CW\*(C`cookie.pem\*(C'\fR, the name
 245 \&\f(CW\*(C`/foo/bar/cookie.pem\*(C'\fR will be returned.
 246 .Sp
 247 The returned \s-1URI\s0 is considered canonical and must be unique and permanent
 248 for the storage where the object (or collection of objects) resides.
 249 Each loader is responsible for ensuring that it only returns canonical
 250 URIs.
 251 However, it's possible that certain schemes allow an object (or collection
 252 thereof) to be reached with alternative URIs; just because one \s-1URI\s0 is
 253 canonical doesn't mean that other variants can't be used.
 254 .Sp
 255 At the discretion of the loader that was used to get these names, an
 256 extra description may be attached as well.
 257 .IP "\s-1OSSL_STORE_INFO_PARAMS\s0" 4
 258 .IX Item "OSSL_STORE_INFO_PARAMS"
 259 Key parameters.
 260 .IP "\s-1OSSL_STORE_INFO_PKEY\s0" 4
 261 .IX Item "OSSL_STORE_INFO_PKEY"
 262 A private/public key of some sort.
 263 .IP "\s-1OSSL_STORE_INFO_CERT\s0" 4
 264 .IX Item "OSSL_STORE_INFO_CERT"
 265 An X.509 certificate.
 266 .IP "\s-1OSSL_STORE_INFO_CRL\s0" 4
 267 .IX Item "OSSL_STORE_INFO_CRL"
 268 A X.509 certificate revocation list.
 269 .SH "RETURN VALUES"
 270 .IX Header "RETURN VALUES"
 271 \&\fBOSSL_STORE_INFO_get_type()\fR returns the \s-1STORE\s0 type number of the given
 272 \&\fB\s-1OSSL_STORE_INFO\s0\fR.
 273 There is no error value.
 274 .PP
 275 \&\fBOSSL_STORE_INFO_get0_NAME()\fR, \fBOSSL_STORE_INFO_get0_NAME_description()\fR,
 276 \&\fBOSSL_STORE_INFO_get0_PARAMS()\fR, \fBOSSL_STORE_INFO_get0_PKEY()\fR,
 277 \&\fBOSSL_STORE_INFO_get0_CERT()\fR and \fBOSSL_STORE_INFO_get0_CRL()\fR all return
 278 a pointer to the OpenSSL object on success, \s-1NULL\s0 otherwise.
 279 .PP
 280 \&\fBOSSL_STORE_INFO_get0_NAME()\fR, \fBOSSL_STORE_INFO_get0_NAME_description()\fR,
 281 \&\fBOSSL_STORE_INFO_get0_PARAMS()\fR, \fBOSSL_STORE_INFO_get0_PKEY()\fR,
 282 \&\fBOSSL_STORE_INFO_get0_CERT()\fR and \fBOSSL_STORE_INFO_get0_CRL()\fR all return
 283 a pointer to a duplicate of the OpenSSL object on success, \s-1NULL\s0 otherwise.
 284 .PP
 285 \&\fBOSSL_STORE_INFO_type_string()\fR returns a string on success, or \fB\s-1NULL\s0\fR on
 286 failure.
 287 .PP
 288 \&\fBOSSL_STORE_INFO_new_NAME()\fR, \fBOSSL_STORE_INFO_new_PARAMS()\fR,
 289 \&\fBOSSL_STORE_INFO_new_PKEY()\fR, \fBOSSL_STORE_INFO_new_CERT()\fR and
 290 \&\fBOSSL_STORE_INFO_new_CRL()\fR return a \fB\s-1OSSL_STORE_INFO\s0\fR
 291 pointer on success, or \fB\s-1NULL\s0\fR on failure.
 292 .PP
 293 \&\fBOSSL_STORE_INFO_set0_NAME_description()\fR returns 1 on success, or 0 on
 294 failure.
 295 .SH "SEE ALSO"
 296 .IX Header "SEE ALSO"
 297 \&\fBossl_store\fR\|(7), \fBOSSL_STORE_open\fR\|(3), \fBOSSL_STORE_register_loader\fR\|(3)
 298 .SH "HISTORY"
 299 .IX Header "HISTORY"
 300 \&\s-1\fBOSSL_STORE_INFO\s0()\fR, \fBOSSL_STORE_INFO_get_type()\fR, \fBOSSL_STORE_INFO_get0_NAME()\fR,
 301 \&\fBOSSL_STORE_INFO_get0_PARAMS()\fR, \fBOSSL_STORE_INFO_get0_PKEY()\fR,
 302 \&\fBOSSL_STORE_INFO_get0_CERT()\fR, \fBOSSL_STORE_INFO_get0_CRL()\fR,
 303 \&\fBOSSL_STORE_INFO_type_string()\fR, \fBOSSL_STORE_INFO_free()\fR, \fBOSSL_STORE_INFO_new_NAME()\fR,
 304 \&\fBOSSL_STORE_INFO_new_PARAMS()\fR, \fBOSSL_STORE_INFO_new_PKEY()\fR,
 305 \&\fBOSSL_STORE_INFO_new_CERT()\fR and \fBOSSL_STORE_INFO_new_CRL()\fR
 306 were added in OpenSSL 1.1.1.
 307 .SH "COPYRIGHT"
 308 .IX Header "COPYRIGHT"
 309 Copyright 2016\-2017 The OpenSSL Project Authors. All Rights Reserved.
 310 .PP
 311 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 312 this file except in compliance with the License.  You can obtain a copy
 313 in the file \s-1LICENSE\s0 in the source distribution or at
 314 <https://www.openssl.org/source/license.html>.