OSSL_STORE_INFO_new_PARAMS(3ossl)

1OSSL_STORE_INFO(3ossl)              OpenSSL             OSSL_STORE_INFO(3ossl)
2
3
4

NAME

6       OSSL_STORE_INFO, OSSL_STORE_INFO_get_type, OSSL_STORE_INFO_get0_NAME,
7       OSSL_STORE_INFO_get0_NAME_description, OSSL_STORE_INFO_get0_PARAMS,
8       OSSL_STORE_INFO_get0_PUBKEY, OSSL_STORE_INFO_get0_PKEY,
9       OSSL_STORE_INFO_get0_CERT, OSSL_STORE_INFO_get0_CRL,
10       OSSL_STORE_INFO_get1_NAME, OSSL_STORE_INFO_get1_NAME_description,
11       OSSL_STORE_INFO_get1_PARAMS, OSSL_STORE_INFO_get1_PUBKEY,
12       OSSL_STORE_INFO_get1_PKEY, OSSL_STORE_INFO_get1_CERT,
13       OSSL_STORE_INFO_get1_CRL, OSSL_STORE_INFO_type_string,
14       OSSL_STORE_INFO_free, OSSL_STORE_INFO_new_NAME,
15       OSSL_STORE_INFO_set0_NAME_description, OSSL_STORE_INFO_new_PARAMS,
16       OSSL_STORE_INFO_new_PUBKEY, OSSL_STORE_INFO_new_PKEY,
17       OSSL_STORE_INFO_new_CERT, OSSL_STORE_INFO_new_CRL, OSSL_STORE_INFO_new,
18       OSSL_STORE_INFO_get0_data - Functions to manipulate OSSL_STORE_INFO
19       objects
20

SYNOPSIS

22        #include <openssl/store.h>
23
24        typedef struct ossl_store_info_st OSSL_STORE_INFO;
25
26        int OSSL_STORE_INFO_get_type(const OSSL_STORE_INFO *store_info);
27        const char *OSSL_STORE_INFO_get0_NAME(const OSSL_STORE_INFO *store_info);
28        char *OSSL_STORE_INFO_get1_NAME(const OSSL_STORE_INFO *store_info);
29        const char *OSSL_STORE_INFO_get0_NAME_description(const OSSL_STORE_INFO
30                                                          *store_info);
31        char *OSSL_STORE_INFO_get1_NAME_description(const OSSL_STORE_INFO *store_info);
32        EVP_PKEY *OSSL_STORE_INFO_get0_PARAMS(const OSSL_STORE_INFO *store_info);
33        EVP_PKEY *OSSL_STORE_INFO_get1_PARAMS(const OSSL_STORE_INFO *store_info);
34        EVP_PKEY *OSSL_STORE_INFO_get0_PUBKEY(const OSSL_STORE_INFO *info);
35        EVP_PKEY *OSSL_STORE_INFO_get1_PUBKEY(const OSSL_STORE_INFO *info);
36        EVP_PKEY *OSSL_STORE_INFO_get0_PKEY(const OSSL_STORE_INFO *store_info);
37        EVP_PKEY *OSSL_STORE_INFO_get1_PKEY(const OSSL_STORE_INFO *store_info);
38        X509 *OSSL_STORE_INFO_get0_CERT(const OSSL_STORE_INFO *store_info);
39        X509 *OSSL_STORE_INFO_get1_CERT(const OSSL_STORE_INFO *store_info);
40        X509_CRL *OSSL_STORE_INFO_get0_CRL(const OSSL_STORE_INFO *store_info);
41        X509_CRL *OSSL_STORE_INFO_get1_CRL(const OSSL_STORE_INFO *store_info);
42
43        const char *OSSL_STORE_INFO_type_string(int type);
44
45        void OSSL_STORE_INFO_free(OSSL_STORE_INFO *store_info);
46
47        OSSL_STORE_INFO *OSSL_STORE_INFO_new_NAME(char *name);
48        int OSSL_STORE_INFO_set0_NAME_description(OSSL_STORE_INFO *info, char *desc);
49        OSSL_STORE_INFO *OSSL_STORE_INFO_new_PARAMS(DSA *dsa_params);
50        OSSL_STORE_INFO *OSSL_STORE_INFO_new_PUBKEY(EVP_PKEY *pubkey);
51        OSSL_STORE_INFO *OSSL_STORE_INFO_new_PKEY(EVP_PKEY *pkey);
52        OSSL_STORE_INFO *OSSL_STORE_INFO_new_CERT(X509 *x509);
53        OSSL_STORE_INFO *OSSL_STORE_INFO_new_CRL(X509_CRL *crl);
54
55        OSSL_STORE_INFO *OSSL_STORE_INFO_new(int type, void *data);
56        void *OSSL_STORE_INFO_get0_data(int type, const OSSL_STORE_INFO *info);
57

DESCRIPTION

59       These functions are primarily useful for applications to retrieve
60       supported objects from OSSL_STORE_INFO objects and for scheme specific
61       loaders to create OSSL_STORE_INFO holders.
62
63   Types
64       OSSL_STORE_INFO is an opaque type that's just an intermediary holder
65       for the objects that have been retrieved by OSSL_STORE_load() and
66       similar functions.  Supported OpenSSL type object can be extracted
67       using one of STORE_INFO_get0_<TYPE>() where <TYPE> can be NAME, PARAMS,
68       PKEY, CERT, or CRL.  The life time of this extracted object is as long
69       as the life time of the OSSL_STORE_INFO it was extracted from, so care
70       should be taken not to free the latter too early.  As an alternative,
71       STORE_INFO_get1_<TYPE>() extracts a duplicate (or the same object with
72       its reference count increased), which can be used after the containing
73       OSSL_STORE_INFO has been freed.  The object returned by
74       STORE_INFO_get1_<TYPE>() must be freed separately by the caller.  See
75       "SUPPORTED OBJECTS" for more information on the types that are
76       supported.
77
78   Functions
79       OSSL_STORE_INFO_get_type() takes a OSSL_STORE_INFO and returns the
80       STORE type number for the object inside.
81
82       STORE_INFO_get_type_string() takes a STORE type number and returns a
83       short string describing it.
84
85       OSSL_STORE_INFO_get0_NAME(), OSSL_STORE_INFO_get0_NAME_description(),
86       OSSL_STORE_INFO_get0_PARAMS(), OSSL_STORE_INFO_get0_PUBKEY(),
87       OSSL_STORE_INFO_get0_PKEY(), OSSL_STORE_INFO_get0_CERT(),
88       OSSL_STORE_INFO_get0_CRL() all take a OSSL_STORE_INFO and return the
89       object it holds if the OSSL_STORE_INFO type (as returned by
90       OSSL_STORE_INFO_get_type()) matches the function, otherwise NULL.
91
92       OSSL_STORE_INFO_get1_NAME(), OSSL_STORE_INFO_get1_NAME_description(),
93       OSSL_STORE_INFO_get1_PARAMS(), OSSL_STORE_INFO_get1_PUBKEY(),
94       OSSL_STORE_INFO_get1_PKEY(), OSSL_STORE_INFO_get1_CERT() and
95       OSSL_STORE_INFO_get1_CRL() all take a OSSL_STORE_INFO and return a
96       duplicate the object it holds if the OSSL_STORE_INFO type (as returned
97       by OSSL_STORE_INFO_get_type()) matches the function, otherwise NULL.
98
99       OSSL_STORE_INFO_free() frees a 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() create a
104       OSSL_STORE_INFO object to hold the given input object.  On success the
105       input object is consumed.
106
107       Additionally, for OSSL_STORE_INFO_NAME objects,
108       OSSL_STORE_INFO_set0_NAME_description() can be used to add an extra
109       description.  This description is meant to be human readable and should
110       be used for information printout.
111
112       OSSL_STORE_INFO_new() creates a OSSL_STORE_INFO with an arbitrary type
113       number and data structure.  It's the responsibility of the caller to
114       define type numbers other than the ones defined by <openssl/store.h>,
115       and to handle freeing the associated data structure on their own.
116       Using type numbers that are defined by <openssl/store.h> may cause
117       undefined behaviours, including crashes.
118
119       OSSL_STORE_INFO_get0_data() returns the data pointer that was passed to
120       OSSL_STORE_INFO_new() if type matches the type number in info.
121
122       OSSL_STORE_INFO_new() and OSSL_STORE_INFO_get0_data() may be useful for
123       applications that define their own STORE data, but must be used with
124       care.
125

SUPPORTED OBJECTS

127       Currently supported object types are:
128
129       OSSL_STORE_INFO_NAME
130           A name is exactly that, a name.  It's like a name in a directory,
131           but formatted as a complete URI.  For example, the path in URI
132           "file:/foo/bar/" could include a file named "cookie.pem", and in
133           that case, the returned OSSL_STORE_INFO_NAME object would have the
134           URI "file:/foo/bar/cookie.pem", which can be used by the
135           application to get the objects in that file.  This can be applied
136           to all schemes that can somehow support a listing of object URIs.
137
138           For "file:" URIs that are used without the explicit scheme, the
139           returned name will be the path of each object, so if "/foo/bar" was
140           given and that path has the file "cookie.pem", the name
141           "/foo/bar/cookie.pem" will be returned.
142
143           The returned URI is considered canonical and must be unique and
144           permanent for the storage where the object (or collection of
145           objects) resides.  Each loader is responsible for ensuring that it
146           only returns canonical URIs.  However, it's possible that certain
147           schemes allow an object (or collection thereof) to be reached with
148           alternative URIs; just because one URI is canonical doesn't mean
149           that other variants can't be used.
150
151           At the discretion of the loader that was used to get these names,
152           an extra description may be attached as well.
153
154       OSSL_STORE_INFO_PARAMS
155           Key parameters.
156
157       OSSL_STORE_INFO_PKEY
158           A keypair or just a private key (possibly with key parameters).
159
160       OSSL_STORE_INFO_PUBKEY
161           A public key (possibly with key parameters).
162
163       OSSL_STORE_INFO_CERT
164           An X.509 certificate.
165
166       OSSL_STORE_INFO_CRL
167           A X.509 certificate revocation list.
168

RETURN VALUES

170       OSSL_STORE_INFO_get_type() returns the STORE type number of the given
171       OSSL_STORE_INFO.  There is no error value.
172
173       OSSL_STORE_INFO_get0_NAME(), OSSL_STORE_INFO_get0_NAME_description(),
174       OSSL_STORE_INFO_get0_PARAMS(), OSSL_STORE_INFO_get0_PKEY(),
175       OSSL_STORE_INFO_get0_CERT() and OSSL_STORE_INFO_get0_CRL() all return a
176       pointer to the OpenSSL object on success, NULL otherwise.
177
178       OSSL_STORE_INFO_get1_NAME(), OSSL_STORE_INFO_get1_NAME_description(),
179       OSSL_STORE_INFO_get1_PARAMS(), OSSL_STORE_INFO_get1_PKEY(),
180       OSSL_STORE_INFO_get1_CERT() and OSSL_STORE_INFO_get1_CRL() all return a
181       pointer to a duplicate of the OpenSSL object on success, NULL
182       otherwise.
183
184       OSSL_STORE_INFO_type_string() returns a string on success, or NULL on
185       failure.
186
187       OSSL_STORE_INFO_new_NAME(), OSSL_STORE_INFO_new_PARAMS(),
188       OSSL_STORE_INFO_new_PKEY(), OSSL_STORE_INFO_new_CERT() and
189       OSSL_STORE_INFO_new_CRL() return a OSSL_STORE_INFO pointer on success,
190       or NULL on failure.
191
192       OSSL_STORE_INFO_set0_NAME_description() returns 1 on success, or 0 on
193       failure.
194

HISTORY

199       The OSSL_STORE API was added in OpenSSL 1.1.1.
200
201       The OSSL_STORE_INFO_PUBKEY object type was added in OpenSSL 3.0.
202

COPYRIGHT

204       Copyright 2016-2021 The OpenSSL Project Authors. All Rights Reserved.
205
206       Licensed under the Apache License 2.0 (the "License").  You may not use
207       this file except in compliance with the License.  You can obtain a copy
208       in the file LICENSE in the source distribution or at
209       <https://www.openssl.org/source/license.html>.
210
211
212
2133.0.5                             2022-07-05            OSSL_STORE_INFO(3ossl)