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 If the argument is NULL, nothing is done. 105 106 OSSL_STORE_INFO_new_NAME() , OSSL_STORE_INFO_new_PARAMS(), 107 , OSSL_STORE_INFO_new_PUBKEY(), OSSL_STORE_INFO_new_PKEY(), 108 OSSL_STORE_INFO_new_CERT() and OSSL_STORE_INFO_new_CRL() 109 create a B<OSSL_STORE_INFO> object to hold the given input object. 110 On success the input object is consumed. 111 112 Additionally, for B<OSSL_STORE_INFO_NAME> objects, 113 OSSL_STORE_INFO_set0_NAME_description() can be used to add an extra 114 description. 115 This description is meant to be human readable and should be used for 116 information printout. 117 118 OSSL_STORE_INFO_new() creates a B<OSSL_STORE_INFO> with an arbitrary I<type> 119 number and I<data> structure. It's the responsibility of the caller to 120 define type numbers other than the ones defined by F<< <openssl/store.h> >>, 121 and to handle freeing the associated data structure on their own. 122 I<Using type numbers that are defined by F<< <openssl/store.h> >> may cause 123 undefined behaviours, including crashes>. 124 125 OSSL_STORE_INFO_get0_data() returns the data pointer that was passed to 126 OSSL_STORE_INFO_new() if I<type> matches the type number in I<info>. 127 128 OSSL_STORE_INFO_new() and OSSL_STORE_INFO_get0_data() may be useful for 129 applications that define their own STORE data, but must be used with care. 130 131 =head1 SUPPORTED OBJECTS 132 133 Currently supported object types are: 134 135 =over 4 136 137 =item OSSL_STORE_INFO_NAME 138 139 A name is exactly that, a name. 140 It's like a name in a directory, but formatted as a complete URI. 141 For example, the path in URI C<file:/foo/bar/> could include a file 142 named C<cookie.pem>, and in that case, the returned B<OSSL_STORE_INFO_NAME> 143 object would have the URI C<file:/foo/bar/cookie.pem>, which can be 144 used by the application to get the objects in that file. 145 This can be applied to all schemes that can somehow support a listing 146 of object URIs. 147 148 For C<file:> URIs that are used without the explicit scheme, the 149 returned name will be the path of each object, so if C</foo/bar> was 150 given and that path has the file C<cookie.pem>, the name 151 C</foo/bar/cookie.pem> will be returned. 152 153 The returned URI is considered canonical and must be unique and permanent 154 for the storage where the object (or collection of objects) resides. 155 Each loader is responsible for ensuring that it only returns canonical 156 URIs. 157 However, it's possible that certain schemes allow an object (or collection 158 thereof) to be reached with alternative URIs; just because one URI is 159 canonical doesn't mean that other variants can't be used. 160 161 At the discretion of the loader that was used to get these names, an 162 extra description may be attached as well. 163 164 =item OSSL_STORE_INFO_PARAMS 165 166 Key parameters. 167 168 =item OSSL_STORE_INFO_PKEY 169 170 A keypair or just a private key (possibly with key parameters). 171 172 =item OSSL_STORE_INFO_PUBKEY 173 174 A public key (possibly with key parameters). 175 176 =item OSSL_STORE_INFO_CERT 177 178 An X.509 certificate. 179 180 =item OSSL_STORE_INFO_CRL 181 182 A X.509 certificate revocation list. 183 184 =back 185 186 =head1 RETURN VALUES 187 188 OSSL_STORE_INFO_get_type() returns the STORE type number of the given 189 B<OSSL_STORE_INFO>. 190 There is no error value. 191 192 OSSL_STORE_INFO_get0_NAME(), OSSL_STORE_INFO_get0_NAME_description(), 193 OSSL_STORE_INFO_get0_PARAMS(), OSSL_STORE_INFO_get0_PKEY(), 194 OSSL_STORE_INFO_get0_CERT() and OSSL_STORE_INFO_get0_CRL() all return 195 a pointer to the OpenSSL object on success, NULL otherwise. 196 197 OSSL_STORE_INFO_get1_NAME(), OSSL_STORE_INFO_get1_NAME_description(), 198 OSSL_STORE_INFO_get1_PARAMS(), OSSL_STORE_INFO_get1_PKEY(), 199 OSSL_STORE_INFO_get1_CERT() and OSSL_STORE_INFO_get1_CRL() all return 200 a pointer to a duplicate of the OpenSSL object on success, NULL otherwise. 201 202 OSSL_STORE_INFO_type_string() returns a string on success, or NULL on 203 failure. 204 205 OSSL_STORE_INFO_new_NAME(), OSSL_STORE_INFO_new_PARAMS(), 206 OSSL_STORE_INFO_new_PKEY(), OSSL_STORE_INFO_new_CERT() and 207 OSSL_STORE_INFO_new_CRL() return a B<OSSL_STORE_INFO> 208 pointer on success, or NULL on failure. 209 210 OSSL_STORE_INFO_set0_NAME_description() returns 1 on success, or 0 on 211 failure. 212 213 =head1 SEE ALSO 214 215 L<ossl_store(7)>, L<OSSL_STORE_open(3)>, L<OSSL_STORE_register_loader(3)> 216 217 =head1 HISTORY 218 219 The OSSL_STORE API was added in OpenSSL 1.1.1. 220 221 The OSSL_STORE_INFO_PUBKEY object type was added in OpenSSL 3.0. 222 223 =head1 COPYRIGHT 224 225 Copyright 2016-2024 The OpenSSL Project Authors. All Rights Reserved. 226 227 Licensed under the Apache License 2.0 (the "License"). You may not use 228 this file except in compliance with the License. You can obtain a copy 229 in the file LICENSE in the source distribution or at 230 L<https://www.openssl.org/source/license.html>. 231 232 =cut 233
Indexes created Sat Jun 27 00:24:51 UTC 2026