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