OSSL_STORE_INFO_get1_NAME_description(3ssl)

1OSSL_STORE_INFO(3)                  OpenSSL                 OSSL_STORE_INFO(3)
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_PKEY, OSSL_STORE_INFO_get0_CERT,
9       OSSL_STORE_INFO_get0_CRL, OSSL_STORE_INFO_get1_NAME,
10       OSSL_STORE_INFO_get1_NAME_description, OSSL_STORE_INFO_get1_PARAMS,
11       OSSL_STORE_INFO_get1_PKEY, OSSL_STORE_INFO_get1_CERT,
12       OSSL_STORE_INFO_get1_CRL, OSSL_STORE_INFO_type_string,
13       OSSL_STORE_INFO_free, OSSL_STORE_INFO_new_NAME,
14       OSSL_STORE_INFO_set0_NAME_description, OSSL_STORE_INFO_new_PARAMS,
15       OSSL_STORE_INFO_new_PKEY, OSSL_STORE_INFO_new_CERT,
16       OSSL_STORE_INFO_new_CRL - Functions to manipulate OSSL_STORE_INFO
17       objects
18

SYNOPSIS

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_PKEY(const OSSL_STORE_INFO *store_info);
33        EVP_PKEY *OSSL_STORE_INFO_get1_PKEY(const OSSL_STORE_INFO *store_info);
34        X509 *OSSL_STORE_INFO_get0_CERT(const OSSL_STORE_INFO *store_info);
35        X509 *OSSL_STORE_INFO_get1_CERT(const OSSL_STORE_INFO *store_info);
36        X509_CRL *OSSL_STORE_INFO_get0_CRL(const OSSL_STORE_INFO *store_info);
37        X509_CRL *OSSL_STORE_INFO_get1_CRL(const OSSL_STORE_INFO *store_info);
38
39        const char *OSSL_STORE_INFO_type_string(int type);
40
41        void OSSL_STORE_INFO_free(OSSL_STORE_INFO *store_info);
42
43        OSSL_STORE_INFO *OSSL_STORE_INFO_new_NAME(char *name);
44        int OSSL_STORE_INFO_set0_NAME_description(OSSL_STORE_INFO *info, char *desc);
45        OSSL_STORE_INFO *OSSL_STORE_INFO_new_PARAMS(DSA *dsa_params);
46        OSSL_STORE_INFO *OSSL_STORE_INFO_new_PKEY(EVP_PKEY *pkey);
47        OSSL_STORE_INFO *OSSL_STORE_INFO_new_CERT(X509 *x509);
48        OSSL_STORE_INFO *OSSL_STORE_INFO_new_CRL(X509_CRL *crl);
49

DESCRIPTION

51       These functions are primarily useful for applications to retrieve
52       supported objects from OSSL_STORE_INFO objects and for scheme specific
53       loaders to create OSSL_STORE_INFO holders.
54
55   Types
56       OSSL_STORE_INFO is an opaque type that's just an intermediary holder
57       for the objects that have been retrieved by OSSL_STORE_load() and
58       similar functions.  Supported OpenSSL type object can be extracted
59       using one of STORE_INFO_get0_TYPE().  The life time of this extracted
60       object is as long as the life time of the OSSL_STORE_INFO it was
61       extracted from, so care should be taken not to free the latter too
62       early.  As an alternative, STORE_INFO_get1_TYPE() extracts a duplicate
63       (or the same object with its reference count increased), which can be
64       used after the containing OSSL_STORE_INFO has been freed.  The object
65       returned by STORE_INFO_get1_TYPE() must be freed separately by the
66       caller.  See "SUPPORTED OBJECTS" for more information on the types that
67       are supported.
68
69   Functions
70       OSSL_STORE_INFO_get_type() takes a OSSL_STORE_INFO and returns the
71       STORE type number for the object inside.  STORE_INFO_get_type_string()
72       takes a STORE type number and returns a short string describing it.
73
74       OSSL_STORE_INFO_get0_NAME(), OSSL_STORE_INFO_get0_NAME_description(),
75       OSSL_STORE_INFO_get0_PARAMS(), OSSL_STORE_INFO_get0_PKEY(),
76       OSSL_STORE_INFO_get0_CERT() and OSSL_STORE_INFO_get0_CRL() all take a
77       OSSL_STORE_INFO and return the held object of the appropriate OpenSSL
78       type provided that's what's held.
79
80       OSSL_STORE_INFO_get1_NAME(), OSSL_STORE_INFO_get1_NAME_description(),
81       OSSL_STORE_INFO_get1_PARAMS(), OSSL_STORE_INFO_get1_PKEY(),
82       OSSL_STORE_INFO_get1_CERT() and OSSL_STORE_INFO_get1_CRL() all take a
83       OSSL_STORE_INFO and return a duplicate of the held object of the
84       appropriate OpenSSL type provided that's what's held.
85
86       OSSL_STORE_INFO_free() frees a OSSL_STORE_INFO and its contained type.
87
88       OSSL_STORE_INFO_new_NAME() , OSSL_STORE_INFO_new_PARAMS(),
89       OSSL_STORE_INFO_new_PKEY(), OSSL_STORE_INFO_new_CERT() and
90       OSSL_STORE_INFO_new_CRL() create a OSSL_STORE_INFO object to hold the
91       given input object.  Additionally, for OSSL_STORE_INFO_NAME` objects,
92       OSSL_STORE_INFO_set0_NAME_description() can be used to add an extra
93       description.  This description is meant to be human readable and should
94       be used for information printout.
95

SUPPORTED OBJECTS

97       Currently supported object types are:
98
99       OSSL_STORE_INFO_NAME
100           A name is exactly that, a name.  It's like a name in a directory,
101           but formatted as a complete URI.  For example, the path in URI
102           "file:/foo/bar/" could include a file named "cookie.pem", and in
103           that case, the returned OSSL_STORE_INFO_NAME object would have the
104           URI "file:/foo/bar/cookie.pem", which can be used by the
105           application to get the objects in that file.  This can be applied
106           to all schemes that can somehow support a listing of object URIs.
107
108           For "file:" URIs that are used without the explicit scheme, the
109           returned name will be the path of each object, so if "/foo/bar" was
110           given and that path has the file "cookie.pem", the name
111           "/foo/bar/cookie.pem" will be returned.
112
113           The returned URI is considered canonical and must be unique and
114           permanent for the storage where the object (or collection of
115           objects) resides.  Each loader is responsible for ensuring that it
116           only returns canonical URIs.  However, it's possible that certain
117           schemes allow an object (or collection thereof) to be reached with
118           alternative URIs; just because one URI is canonical doesn't mean
119           that other variants can't be used.
120
121           At the discretion of the loader that was used to get these names,
122           an extra description may be attached as well.
123
124       OSSL_STORE_INFO_PARAMS
125           Key parameters.
126
127       OSSL_STORE_INFO_PKEY
128           A private/public key of some sort.
129
130       OSSL_STORE_INFO_CERT
131           An X.509 certificate.
132
133       OSSL_STORE_INFO_CRL
134           A X.509 certificate revocation list.
135

RETURN VALUES

137       OSSL_STORE_INFO_get_type() returns the STORE type number of the given
138       OSSL_STORE_INFO.  There is no error value.
139
140       OSSL_STORE_INFO_get0_NAME(), OSSL_STORE_INFO_get0_NAME_description(),
141       OSSL_STORE_INFO_get0_PARAMS(), OSSL_STORE_INFO_get0_PKEY(),
142       OSSL_STORE_INFO_get0_CERT() and OSSL_STORE_INFO_get0_CRL() all return a
143       pointer to the OpenSSL object on success, NULL otherwise.
144
145       OSSL_STORE_INFO_get0_NAME(), OSSL_STORE_INFO_get0_NAME_description(),
146       OSSL_STORE_INFO_get0_PARAMS(), OSSL_STORE_INFO_get0_PKEY(),
147       OSSL_STORE_INFO_get0_CERT() and OSSL_STORE_INFO_get0_CRL() all return a
148       pointer to a duplicate of the OpenSSL object on success, NULL
149       otherwise.
150
151       OSSL_STORE_INFO_type_string() returns a string on success, or NULL on
152       failure.
153
154       OSSL_STORE_INFO_new_NAME(), OSSL_STORE_INFO_new_PARAMS(),
155       OSSL_STORE_INFO_new_PKEY(), OSSL_STORE_INFO_new_CERT() and
156       OSSL_STORE_INFO_new_CRL() return a OSSL_STORE_INFO pointer on success,
157       or NULL on failure.
158
159       OSSL_STORE_INFO_set0_NAME_description() returns 1 on success, or 0 on
160       failure.
161

HISTORY

166       OSSL_STORE_INFO(), OSSL_STORE_INFO_get_type(),
167       OSSL_STORE_INFO_get0_NAME(), OSSL_STORE_INFO_get0_PARAMS(),
168       OSSL_STORE_INFO_get0_PKEY(), OSSL_STORE_INFO_get0_CERT(),
169       OSSL_STORE_INFO_get0_CRL(), OSSL_STORE_INFO_type_string(),
170       OSSL_STORE_INFO_free(), OSSL_STORE_INFO_new_NAME(),
171       OSSL_STORE_INFO_new_PARAMS(), OSSL_STORE_INFO_new_PKEY(),
172       OSSL_STORE_INFO_new_CERT() and OSSL_STORE_INFO_new_CRL() were added in
173       OpenSSL 1.1.1.
174

COPYRIGHT

176       Copyright 2016-2017 The OpenSSL Project Authors. All Rights Reserved.
177
178       Licensed under the OpenSSL license (the "License").  You may not use
179       this file except in compliance with the License.  You can obtain a copy
180       in the file LICENSE in the source distribution or at
181       <https://www.openssl.org/source/license.html>.
182
183
184
1851.1.1k                            2021-03-26                OSSL_STORE_INFO(3)