secure/lib/libcrypto/man/OSSL_STORE_INFO.3

   1 .\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
   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 .if !\nF .nr F 0
  58 .if \nF>0 \{\
  59 .    de IX
  60 .    tm Index:\\$1\t\\n%\t"\\$2"
  61 ..
  62 .    if !\nF==2 \{\
  63 .        nr % 0
  64 .        nr F 2
  65 .    \}
  66 .\}
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "OSSL_STORE_INFO 3"
 132 .TH OSSL_STORE_INFO 3 "2018-09-11" "1.1.1" "OpenSSL"
 133 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 134 .\" way too many mistakes in technical documents.
 135 .if n .ad l
 136 .nh
 137 .SH "NAME"
 138 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
 139 .SH "SYNOPSIS"
 140 .IX Header "SYNOPSIS"
 141 .Vb 1
 142 \& #include <openssl/store.h>
 143 \&
 144 \& typedef struct ossl_store_info_st OSSL_STORE_INFO;
 145 \&
 146 \& int OSSL_STORE_INFO_get_type(const OSSL_STORE_INFO *store_info);
 147 \& const char *OSSL_STORE_INFO_get0_NAME(const OSSL_STORE_INFO *store_info);
 148 \& char *OSSL_STORE_INFO_get1_NAME(const OSSL_STORE_INFO *store_info);
 149 \& const char *OSSL_STORE_INFO_get0_NAME_description(const OSSL_STORE_INFO
 150 \&                                                   *store_info);
 151 \& char *OSSL_STORE_INFO_get1_NAME_description(const OSSL_STORE_INFO *store_info);
 152 \& EVP_PKEY *OSSL_STORE_INFO_get0_PARAMS(const OSSL_STORE_INFO *store_info);
 153 \& EVP_PKEY *OSSL_STORE_INFO_get1_PARAMS(const OSSL_STORE_INFO *store_info);
 154 \& EVP_PKEY *OSSL_STORE_INFO_get0_PKEY(const OSSL_STORE_INFO *store_info);
 155 \& EVP_PKEY *OSSL_STORE_INFO_get1_PKEY(const OSSL_STORE_INFO *store_info);
 156 \& X509 *OSSL_STORE_INFO_get0_CERT(const OSSL_STORE_INFO *store_info);
 157 \& X509 *OSSL_STORE_INFO_get1_CERT(const OSSL_STORE_INFO *store_info);
 158 \& X509_CRL *OSSL_STORE_INFO_get0_CRL(const OSSL_STORE_INFO *store_info);
 159 \& X509_CRL *OSSL_STORE_INFO_get1_CRL(const OSSL_STORE_INFO *store_info);
 160 \&
 161 \& const char *OSSL_STORE_INFO_type_string(int type);
 162 \&
 163 \& void OSSL_STORE_INFO_free(OSSL_STORE_INFO *store_info);
 164 \&
 165 \& OSSL_STORE_INFO *OSSL_STORE_INFO_new_NAME(char *name);
 166 \& int OSSL_STORE_INFO_set0_NAME_description(OSSL_STORE_INFO *info, char *desc);
 167 \& OSSL_STORE_INFO *OSSL_STORE_INFO_new_PARAMS(DSA *dsa_params);
 168 \& OSSL_STORE_INFO *OSSL_STORE_INFO_new_PKEY(EVP_PKEY *pkey);
 169 \& OSSL_STORE_INFO *OSSL_STORE_INFO_new_CERT(X509 *x509);
 170 \& OSSL_STORE_INFO *OSSL_STORE_INFO_new_CRL(X509_CRL *crl);
 171 .Ve
 172 .SH "DESCRIPTION"
 173 .IX Header "DESCRIPTION"
 174 These functions are primarily useful for applications to retrieve
 175 supported objects from \fB\s-1OSSL_STORE_INFO\s0\fR objects and for scheme specific
 176 loaders to create \fB\s-1OSSL_STORE_INFO\s0\fR holders.
 177 .SS "Types"
 178 .IX Subsection "Types"
 179 \&\fB\s-1OSSL_STORE_INFO\s0\fR is an opaque type that's just an intermediary holder for
 180 the objects that have been retrieved by \fIOSSL_STORE_load()\fR and similar
 181 functions.
 182 Supported OpenSSL type object can be extracted using one of
 183 \&\fISTORE_INFO_get0_TYPE()\fR.
 184 The life time of this extracted object is as long as the life time of
 185 the \fB\s-1OSSL_STORE_INFO\s0\fR it was extracted from, so care should be taken not
 186 to free the latter too early.
 187 As an alternative, \fISTORE_INFO_get1_TYPE()\fR extracts a duplicate (or the
 188 same object with its reference count increased), which can be used
 189 after the containing \fB\s-1OSSL_STORE_INFO\s0\fR has been freed.
 190 The object returned by \fISTORE_INFO_get1_TYPE()\fR must be freed separately
 191 by the caller.
 192 See \*(L"\s-1SUPPORTED OBJECTS\*(R"\s0 for more information on the types that are
 193 supported.
 194 .SS "Functions"
 195 .IX Subsection "Functions"
 196 \&\fIOSSL_STORE_INFO_get_type()\fR takes a \fB\s-1OSSL_STORE_INFO\s0\fR and returns the \s-1STORE\s0
 197 type number for the object inside.
 198 \&\fISTORE_INFO_get_type_string()\fR takes a \s-1STORE\s0 type number and returns a
 199 short string describing it.
 200 .PP
 201 \&\fIOSSL_STORE_INFO_get0_NAME()\fR, \fIOSSL_STORE_INFO_get0_NAME_description()\fR,
 202 \&\fIOSSL_STORE_INFO_get0_PARAMS()\fR, \fIOSSL_STORE_INFO_get0_PKEY()\fR,
 203 \&\fIOSSL_STORE_INFO_get0_CERT()\fR and \fIOSSL_STORE_INFO_get0_CRL()\fR all take a
 204 \&\fB\s-1OSSL_STORE_INFO\s0\fR and return the held object of the appropriate OpenSSL
 205 type provided that's what's held.
 206 .PP
 207 \&\fIOSSL_STORE_INFO_get1_NAME()\fR, \fIOSSL_STORE_INFO_get1_NAME_description()\fR,
 208 \&\fIOSSL_STORE_INFO_get1_PARAMS()\fR, \fIOSSL_STORE_INFO_get1_PKEY()\fR,
 209 \&\fIOSSL_STORE_INFO_get1_CERT()\fR and \fIOSSL_STORE_INFO_get1_CRL()\fR all take a
 210 \&\fB\s-1OSSL_STORE_INFO\s0\fR and return a duplicate of the held object of the
 211 appropriate OpenSSL type provided that's what's held.
 212 .PP
 213 \&\fIOSSL_STORE_INFO_free()\fR frees a \fB\s-1OSSL_STORE_INFO\s0\fR and its contained type.
 214 .PP
 215 \&\fIOSSL_STORE_INFO_new_NAME()\fR , \fIOSSL_STORE_INFO_new_PARAMS()\fR,
 216 \&\fIOSSL_STORE_INFO_new_PKEY()\fR, \fIOSSL_STORE_INFO_new_CERT()\fR and
 217 \&\fIOSSL_STORE_INFO_new_CRL()\fR create a \fB\s-1OSSL_STORE_INFO\s0\fR
 218 object to hold the given input object.
 219 Additionally, for \fB\s-1OSSL_STORE_INFO_NAME\s0\fR` objects,
 220 \&\fIOSSL_STORE_INFO_set0_NAME_description()\fR can be used to add an extra
 221 description.
 222 This description is meant to be human readable and should be used for
 223 information printout.
 224 .SH "SUPPORTED OBJECTS"
 225 .IX Header "SUPPORTED OBJECTS"
 226 Currently supported object types are:
 227 .IP "\s-1OSSL_STORE_INFO_NAME\s0" 4
 228 .IX Item "OSSL_STORE_INFO_NAME"
 229 A name is exactly that, a name.
 230 It's like a name in a directory, but formatted as a complete \s-1URI.\s0
 231 For example, the path in \s-1URI\s0 \f(CW\*(C`file:/foo/bar/\*(C'\fR could include a file
 232 named \f(CW\*(C`cookie.pem\*(C'\fR, and in that case, the returned \fB\s-1OSSL_STORE_INFO_NAME\s0\fR
 233 object would have the \s-1URI\s0 \f(CW\*(C`file:/foo/bar/cookie.pem\*(C'\fR, which can be
 234 used by the application to get the objects in that file.
 235 This can be applied to all schemes that can somehow support a listing
 236 of object URIs.
 237 .Sp
 238 For \f(CW\*(C`file:\*(C'\fR URIs that are used without the explicit scheme, the
 239 returned name will be the path of each object, so if \f(CW\*(C`/foo/bar\*(C'\fR was
 240 given and that path has the file \f(CW\*(C`cookie.pem\*(C'\fR, the name
 241 \&\f(CW\*(C`/foo/bar/cookie.pem\*(C'\fR will be returned.
 242 .Sp
 243 The returned \s-1URI\s0 is considered canonical and must be unique and permanent
 244 for the storage where the object (or collection of objects) resides.
 245 Each loader is responsible for ensuring that it only returns canonical
 246 URIs.
 247 However, it's possible that certain schemes allow an object (or collection
 248 thereof) to be reached with alternative URIs; just because one \s-1URI\s0 is
 249 canonical doesn't mean that other variants can't be used.
 250 .Sp
 251 At the discretion of the loader that was used to get these names, an
 252 extra description may be attached as well.
 253 .IP "\s-1OSSL_STORE_INFO_PARAMS\s0" 4
 254 .IX Item "OSSL_STORE_INFO_PARAMS"
 255 Key parameters.
 256 .IP "\s-1OSSL_STORE_INFO_PKEY\s0" 4
 257 .IX Item "OSSL_STORE_INFO_PKEY"
 258 A private/public key of some sort.
 259 .IP "\s-1OSSL_STORE_INFO_CERT\s0" 4
 260 .IX Item "OSSL_STORE_INFO_CERT"
 261 An X.509 certificate.
 262 .IP "\s-1OSSL_STORE_INFO_CRL\s0" 4
 263 .IX Item "OSSL_STORE_INFO_CRL"
 264 A X.509 certificate revocation list.
 265 .SH "RETURN VALUES"
 266 .IX Header "RETURN VALUES"
 267 \&\fIOSSL_STORE_INFO_get_type()\fR returns the \s-1STORE\s0 type number of the given
 268 \&\fB\s-1OSSL_STORE_INFO\s0\fR.
 269 There is no error value.
 270 .PP
 271 \&\fIOSSL_STORE_INFO_get0_NAME()\fR, \fIOSSL_STORE_INFO_get0_NAME_description()\fR,
 272 \&\fIOSSL_STORE_INFO_get0_PARAMS()\fR, \fIOSSL_STORE_INFO_get0_PKEY()\fR,
 273 \&\fIOSSL_STORE_INFO_get0_CERT()\fR and \fIOSSL_STORE_INFO_get0_CRL()\fR all return
 274 a pointer to the OpenSSL object on success, \s-1NULL\s0 otherwise.
 275 .PP
 276 \&\fIOSSL_STORE_INFO_get0_NAME()\fR, \fIOSSL_STORE_INFO_get0_NAME_description()\fR,
 277 \&\fIOSSL_STORE_INFO_get0_PARAMS()\fR, \fIOSSL_STORE_INFO_get0_PKEY()\fR,
 278 \&\fIOSSL_STORE_INFO_get0_CERT()\fR and \fIOSSL_STORE_INFO_get0_CRL()\fR all return
 279 a pointer to a duplicate of the OpenSSL object on success, \s-1NULL\s0 otherwise.
 280 .PP
 281 \&\fIOSSL_STORE_INFO_type_string()\fR returns a string on success, or \fB\s-1NULL\s0\fR on
 282 failure.
 283 .PP
 284 \&\fIOSSL_STORE_INFO_new_NAME()\fR, \fIOSSL_STORE_INFO_new_PARAMS()\fR,
 285 \&\fIOSSL_STORE_INFO_new_PKEY()\fR, \fIOSSL_STORE_INFO_new_CERT()\fR and
 286 \&\fIOSSL_STORE_INFO_new_CRL()\fR return a \fB\s-1OSSL_STORE_INFO\s0\fR
 287 pointer on success, or \fB\s-1NULL\s0\fR on failure.
 288 .PP
 289 \&\fIOSSL_STORE_INFO_set0_NAME_description()\fR returns 1 on success, or 0 on
 290 failure.
 291 .SH "SEE ALSO"
 292 .IX Header "SEE ALSO"
 293 \&\fIossl_store\fR\|(7), \fIOSSL_STORE_open\fR\|(3), \fIOSSL_STORE_register_loader\fR\|(3)
 294 .SH "HISTORY"
 295 .IX Header "HISTORY"
 296 \&\s-1\fIOSSL_STORE_INFO\s0()\fR, \fIOSSL_STORE_INFO_get_type()\fR, \fIOSSL_STORE_INFO_get0_NAME()\fR,
 297 \&\fIOSSL_STORE_INFO_get0_PARAMS()\fR, \fIOSSL_STORE_INFO_get0_PKEY()\fR,
 298 \&\fIOSSL_STORE_INFO_get0_CERT()\fR, \fIOSSL_STORE_INFO_get0_CRL()\fR,
 299 \&\fIOSSL_STORE_INFO_type_string()\fR, \fIOSSL_STORE_INFO_free()\fR, \fIOSSL_STORE_INFO_new_NAME()\fR,
 300 \&\fIOSSL_STORE_INFO_new_PARAMS()\fR, \fIOSSL_STORE_INFO_new_PKEY()\fR,
 301 \&\fIOSSL_STORE_INFO_new_CERT()\fR and \fIOSSL_STORE_INFO_new_CRL()\fR
 302 were added to OpenSSL 1.1.1.
 303 .SH "COPYRIGHT"
 304 .IX Header "COPYRIGHT"
 305 Copyright 2016\-2017 The OpenSSL Project Authors. All Rights Reserved.
 306 .PP
 307 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 308 this file except in compliance with the License.  You can obtain a copy
 309 in the file \s-1LICENSE\s0 in the source distribution or at
 310 <https://www.openssl.org/source/license.html>.