doc/man3/OSSL_STORE_INFO.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 OSSL_STORE_INFO, OSSL_STORE_INFO_get_type, OSSL_STORE_INFO_get0_NAME,
   6 OSSL_STORE_INFO_get0_NAME_description,
   7 OSSL_STORE_INFO_get0_PARAMS, OSSL_STORE_INFO_get0_PUBKEY,
   8 OSSL_STORE_INFO_get0_PKEY, OSSL_STORE_INFO_get0_CERT, OSSL_STORE_INFO_get0_CRL,
   9 OSSL_STORE_INFO_get1_NAME, OSSL_STORE_INFO_get1_NAME_description,
  10 OSSL_STORE_INFO_get1_PARAMS, OSSL_STORE_INFO_get1_PUBKEY,
  11 OSSL_STORE_INFO_get1_PKEY, OSSL_STORE_INFO_get1_CERT, OSSL_STORE_INFO_get1_CRL,
  12 OSSL_STORE_INFO_type_string, OSSL_STORE_INFO_free,
  13 OSSL_STORE_INFO_new_NAME, OSSL_STORE_INFO_set0_NAME_description,
  14 OSSL_STORE_INFO_new_PARAMS, OSSL_STORE_INFO_new_PUBKEY,
  15 OSSL_STORE_INFO_new_PKEY, OSSL_STORE_INFO_new_CERT, OSSL_STORE_INFO_new_CRL
  16 - Functions to manipulate OSSL_STORE_INFO objects
  17
  18 =head1 SYNOPSIS
  19
  20  #include <openssl/store.h>
  21
  22  typedef struct ossl_store_info_st OSSL_STORE_INFO;
  23
  24  int OSSL_STORE_INFO_get_type(const OSSL_STORE_INFO *store_info);
  25  const char *OSSL_STORE_INFO_get0_NAME(const OSSL_STORE_INFO *store_info);
  26  char *OSSL_STORE_INFO_get1_NAME(const OSSL_STORE_INFO *store_info);
  27  const char *OSSL_STORE_INFO_get0_NAME_description(const OSSL_STORE_INFO
  28                                                    *store_info);
  29  char *OSSL_STORE_INFO_get1_NAME_description(const OSSL_STORE_INFO *store_info);
  30  EVP_PKEY *OSSL_STORE_INFO_get0_PARAMS(const OSSL_STORE_INFO *store_info);
  31  EVP_PKEY *OSSL_STORE_INFO_get1_PARAMS(const OSSL_STORE_INFO *store_info);
  32  EVP_PKEY *OSSL_STORE_INFO_get0_PUBKEY(const OSSL_STORE_INFO *info);
  33  EVP_PKEY *OSSL_STORE_INFO_get1_PUBKEY(const OSSL_STORE_INFO *info);
  34  EVP_PKEY *OSSL_STORE_INFO_get0_PKEY(const OSSL_STORE_INFO *store_info);
  35  EVP_PKEY *OSSL_STORE_INFO_get1_PKEY(const OSSL_STORE_INFO *store_info);
  36  X509 *OSSL_STORE_INFO_get0_CERT(const OSSL_STORE_INFO *store_info);
  37  X509 *OSSL_STORE_INFO_get1_CERT(const OSSL_STORE_INFO *store_info);
  38  X509_CRL *OSSL_STORE_INFO_get0_CRL(const OSSL_STORE_INFO *store_info);
  39  X509_CRL *OSSL_STORE_INFO_get1_CRL(const OSSL_STORE_INFO *store_info);
  40
  41  const char *OSSL_STORE_INFO_type_string(int type);
  42
  43  void OSSL_STORE_INFO_free(OSSL_STORE_INFO *store_info);
  44
  45  OSSL_STORE_INFO *OSSL_STORE_INFO_new_NAME(char *name);
  46  int OSSL_STORE_INFO_set0_NAME_description(OSSL_STORE_INFO *info, char *desc);
  47  OSSL_STORE_INFO *OSSL_STORE_INFO_new_PARAMS(DSA *dsa_params);
  48  OSSL_STORE_INFO *OSSL_STORE_INFO_new_PUBKEY(EVP_PKEY *pubkey);
  49  OSSL_STORE_INFO *OSSL_STORE_INFO_new_PKEY(EVP_PKEY *pkey);
  50  OSSL_STORE_INFO *OSSL_STORE_INFO_new_CERT(X509 *x509);
  51  OSSL_STORE_INFO *OSSL_STORE_INFO_new_CRL(X509_CRL *crl);
  52
  53 =head1 DESCRIPTION
  54
  55 These functions are primarily useful for applications to retrieve
  56 supported objects from B<OSSL_STORE_INFO> objects and for scheme specific
  57 loaders to create B<OSSL_STORE_INFO> holders.
  58
  59 =head2 Types
  60
  61 B<OSSL_STORE_INFO> is an opaque type that's just an intermediary holder for
  62 the objects that have been retrieved by OSSL_STORE_load() and similar functions.
  63 Supported OpenSSL type object can be extracted using one of
  64 STORE_INFO_get0_<TYPE>() where <TYPE> can be NAME, PARAMS, PKEY, CERT, or CRL.
  65 The life time of this extracted object is as long as the life time of
  66 the B<OSSL_STORE_INFO> it was extracted from, so care should be taken not
  67 to free the latter too early.
  68 As an alternative, STORE_INFO_get1_<TYPE>() extracts a duplicate (or the
  69 same object with its reference count increased), which can be used
  70 after the containing B<OSSL_STORE_INFO> has been freed.
  71 The object returned by STORE_INFO_get1_<TYPE>() must be freed separately
  72 by the caller.
  73 See L</SUPPORTED OBJECTS> for more information on the types that are supported.
  74
  75 =head2 Functions
  76
  77 OSSL_STORE_INFO_get_type() takes a B<OSSL_STORE_INFO> and returns the STORE
  78 type number for the object inside.
  79
  80 STORE_INFO_get_type_string() takes a STORE type number and returns a
  81 short string describing it.
  82
  83 OSSL_STORE_INFO_get0_NAME(), OSSL_STORE_INFO_get0_NAME_description(),
  84 OSSL_STORE_INFO_get0_PARAMS(), OSSL_STORE_INFO_get0_PUBKEY(),
  85 OSSL_STORE_INFO_get0_PKEY(), OSSL_STORE_INFO_get0_CERT(),
  86 OSSL_STORE_INFO_get0_CRL()
  87 all take a B<OSSL_STORE_INFO> and return the object it holds if the
  88 B<OSSL_STORE_INFO> type (as returned by OSSL_STORE_INFO_get_type())
  89 matches the function, otherwise NULL.
  90
  91 OSSL_STORE_INFO_get1_NAME(), OSSL_STORE_INFO_get1_NAME_description(),
  92 OSSL_STORE_INFO_get1_PARAMS(), OSSL_STORE_INFO_get1_PUBKEY(),
  93 OSSL_STORE_INFO_get1_PKEY(), OSSL_STORE_INFO_get1_CERT() and
  94 OSSL_STORE_INFO_get1_CRL()
  95 all take a B<OSSL_STORE_INFO> and return a duplicate the object it
  96 holds if the B<OSSL_STORE_INFO> type (as returned by
  97 OSSL_STORE_INFO_get_type()) matches the function, otherwise NULL.
  98
  99 OSSL_STORE_INFO_free() frees a B<OSSL_STORE_INFO> and its contained type.
 100
 101 OSSL_STORE_INFO_new_NAME() , OSSL_STORE_INFO_new_PARAMS(),
 102 , OSSL_STORE_INFO_new_PUBKEY(), OSSL_STORE_INFO_new_PKEY(),
 103 OSSL_STORE_INFO_new_CERT() and OSSL_STORE_INFO_new_CRL()
 104 create a B<OSSL_STORE_INFO> object to hold the given input object.
 105 On success the input object is consumed.
 106
 107 Additionally, for B<OSSL_STORE_INFO_NAME>` objects,
 108 OSSL_STORE_INFO_set0_NAME_description() can be used to add an extra
 109 description.
 110 This description is meant to be human readable and should be used for
 111 information printout.
 112
 113 =head1 SUPPORTED OBJECTS
 114
 115 Currently supported object types are:
 116
 117 =over 4
 118
 119 =item OSSL_STORE_INFO_NAME
 120
 121 A name is exactly that, a name.
 122 It's like a name in a directory, but formatted as a complete URI.
 123 For example, the path in URI C<file:/foo/bar/> could include a file
 124 named C<cookie.pem>, and in that case, the returned B<OSSL_STORE_INFO_NAME>
 125 object would have the URI C<file:/foo/bar/cookie.pem>, which can be
 126 used by the application to get the objects in that file.
 127 This can be applied to all schemes that can somehow support a listing
 128 of object URIs.
 129
 130 For C<file:> URIs that are used without the explicit scheme, the
 131 returned name will be the path of each object, so if C</foo/bar> was
 132 given and that path has the file C<cookie.pem>, the name
 133 C</foo/bar/cookie.pem> will be returned.
 134
 135 The returned URI is considered canonical and must be unique and permanent
 136 for the storage where the object (or collection of objects) resides.
 137 Each loader is responsible for ensuring that it only returns canonical
 138 URIs.
 139 However, it's possible that certain schemes allow an object (or collection
 140 thereof) to be reached with alternative URIs; just because one URI is
 141 canonical doesn't mean that other variants can't be used.
 142
 143 At the discretion of the loader that was used to get these names, an
 144 extra description may be attached as well.
 145
 146 =item OSSL_STORE_INFO_PARAMS
 147
 148 Key parameters.
 149
 150 =item OSSL_STORE_INFO_PKEY
 151
 152 A private/public key of some sort.
 153
 154 =item OSSL_STORE_INFO_CERT
 155
 156 An X.509 certificate.
 157
 158 =item OSSL_STORE_INFO_CRL
 159
 160 A X.509 certificate revocation list.
 161
 162 =back
 163
 164 =head1 RETURN VALUES
 165
 166 OSSL_STORE_INFO_get_type() returns the STORE type number of the given
 167 B<OSSL_STORE_INFO>.
 168 There is no error value.
 169
 170 OSSL_STORE_INFO_get0_NAME(), OSSL_STORE_INFO_get0_NAME_description(),
 171 OSSL_STORE_INFO_get0_PARAMS(), OSSL_STORE_INFO_get0_PKEY(),
 172 OSSL_STORE_INFO_get0_CERT() and OSSL_STORE_INFO_get0_CRL() all return
 173 a pointer to the OpenSSL object on success, NULL otherwise.
 174
 175 OSSL_STORE_INFO_get1_NAME(), OSSL_STORE_INFO_get1_NAME_description(),
 176 OSSL_STORE_INFO_get1_PARAMS(), OSSL_STORE_INFO_get1_PKEY(),
 177 OSSL_STORE_INFO_get1_CERT() and OSSL_STORE_INFO_get1_CRL() all return
 178 a pointer to a duplicate of the OpenSSL object on success, NULL otherwise.
 179
 180 OSSL_STORE_INFO_type_string() returns a string on success, or B<NULL> on
 181 failure.
 182
 183 OSSL_STORE_INFO_new_NAME(), OSSL_STORE_INFO_new_PARAMS(),
 184 OSSL_STORE_INFO_new_PKEY(), OSSL_STORE_INFO_new_CERT() and
 185 OSSL_STORE_INFO_new_CRL() return a B<OSSL_STORE_INFO>
 186 pointer on success, or B<NULL> on failure.
 187
 188 OSSL_STORE_INFO_set0_NAME_description() returns 1 on success, or 0 on
 189 failure.
 190
 191 =head1 SEE ALSO
 192
 193 L<ossl_store(7)>, L<OSSL_STORE_open(3)>, L<OSSL_STORE_register_loader(3)>
 194
 195 =head1 HISTORY
 196
 197 The OSSL_STORE API was added in OpenSSL 1.1.1.
 198
 199 =head1 COPYRIGHT
 200
 201 Copyright 2016-2020 The OpenSSL Project Authors. All Rights Reserved.
 202
 203 Licensed under the Apache License 2.0 (the "License").  You may not use
 204 this file except in compliance with the License.  You can obtain a copy
 205 in the file LICENSE in the source distribution or at
 206 L<https://www.openssl.org/source/license.html>.
 207
 208 =cut