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