Debian Codegraph @

upstream/debian-unstable/man3/OSSL_STORE_INFO.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "OSSL_STORE_INFO 3SSL"
58 .TH OSSL_STORE_INFO 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 OSSL_STORE_INFO, OSSL_STORE_INFO_get_type, OSSL_STORE_INFO_get0_NAME,
65 OSSL_STORE_INFO_get0_NAME_description,
66 OSSL_STORE_INFO_get0_PARAMS, OSSL_STORE_INFO_get0_PUBKEY,
67 OSSL_STORE_INFO_get0_PKEY, OSSL_STORE_INFO_get0_CERT, OSSL_STORE_INFO_get0_CRL,
68 OSSL_STORE_INFO_get1_NAME, OSSL_STORE_INFO_get1_NAME_description,
69 OSSL_STORE_INFO_get1_PARAMS, OSSL_STORE_INFO_get1_PUBKEY,
70 OSSL_STORE_INFO_get1_PKEY, OSSL_STORE_INFO_get1_CERT, OSSL_STORE_INFO_get1_CRL,
71 OSSL_STORE_INFO_type_string, OSSL_STORE_INFO_free,
72 OSSL_STORE_INFO_new_NAME, OSSL_STORE_INFO_set0_NAME_description,
73 OSSL_STORE_INFO_new_PARAMS, OSSL_STORE_INFO_new_PUBKEY,
74 OSSL_STORE_INFO_new_PKEY, OSSL_STORE_INFO_new_CERT, OSSL_STORE_INFO_new_CRL,
75 OSSL_STORE_INFO_new, OSSL_STORE_INFO_get0_data
76 \&\- Functions to manipulate OSSL_STORE_INFO objects
77 .SH SYNOPSIS
78 .IX Header "SYNOPSIS"
79 .Vb 1
80 \& #include <openssl/store.h>
81 \&
82 \& typedef struct ossl_store_info_st OSSL_STORE_INFO;
83 \&
84 \& int OSSL_STORE_INFO_get_type(const OSSL_STORE_INFO *store_info);
85 \& const char *OSSL_STORE_INFO_get0_NAME(const OSSL_STORE_INFO *store_info);
86 \& char *OSSL_STORE_INFO_get1_NAME(const OSSL_STORE_INFO *store_info);
87 \& const char *OSSL_STORE_INFO_get0_NAME_description(const OSSL_STORE_INFO
88 \& *store_info);
89 \& char *OSSL_STORE_INFO_get1_NAME_description(const OSSL_STORE_INFO *store_info);
90 \& EVP_PKEY *OSSL_STORE_INFO_get0_PARAMS(const OSSL_STORE_INFO *store_info);
91 \& EVP_PKEY *OSSL_STORE_INFO_get1_PARAMS(const OSSL_STORE_INFO *store_info);
92 \& EVP_PKEY *OSSL_STORE_INFO_get0_PUBKEY(const OSSL_STORE_INFO *info);
93 \& EVP_PKEY *OSSL_STORE_INFO_get1_PUBKEY(const OSSL_STORE_INFO *info);
94 \& EVP_PKEY *OSSL_STORE_INFO_get0_PKEY(const OSSL_STORE_INFO *store_info);
95 \& EVP_PKEY *OSSL_STORE_INFO_get1_PKEY(const OSSL_STORE_INFO *store_info);
96 \& X509 *OSSL_STORE_INFO_get0_CERT(const OSSL_STORE_INFO *store_info);
97 \& X509 *OSSL_STORE_INFO_get1_CERT(const OSSL_STORE_INFO *store_info);
98 \& X509_CRL *OSSL_STORE_INFO_get0_CRL(const OSSL_STORE_INFO *store_info);
99 \& X509_CRL *OSSL_STORE_INFO_get1_CRL(const OSSL_STORE_INFO *store_info);
100 \&
101 \& const char *OSSL_STORE_INFO_type_string(int type);
102 \&
103 \& void OSSL_STORE_INFO_free(OSSL_STORE_INFO *store_info);
104 \&
105 \& OSSL_STORE_INFO *OSSL_STORE_INFO_new_NAME(char *name);
106 \& int OSSL_STORE_INFO_set0_NAME_description(OSSL_STORE_INFO *info, char *desc);
107 \& OSSL_STORE_INFO *OSSL_STORE_INFO_new_PARAMS(DSA *dsa_params);
108 \& OSSL_STORE_INFO *OSSL_STORE_INFO_new_PUBKEY(EVP_PKEY *pubkey);
109 \& OSSL_STORE_INFO *OSSL_STORE_INFO_new_PKEY(EVP_PKEY *pkey);
110 \& OSSL_STORE_INFO *OSSL_STORE_INFO_new_CERT(X509 *x509);
111 \& OSSL_STORE_INFO *OSSL_STORE_INFO_new_CRL(X509_CRL *crl);
112 \&
113 \& OSSL_STORE_INFO *OSSL_STORE_INFO_new(int type, void *data);
114 \& void *OSSL_STORE_INFO_get0_data(int type, const OSSL_STORE_INFO *info);
115 .Ve
116 .SH DESCRIPTION
117 .IX Header "DESCRIPTION"
118 These functions are primarily useful for applications to retrieve
119 supported objects from \fBOSSL_STORE_INFO\fR objects and for scheme specific
120 loaders to create \fBOSSL_STORE_INFO\fR holders.
121 .SS Types
122 .IX Subsection "Types"
123 \&\fBOSSL_STORE_INFO\fR is an opaque type that's just an intermediary holder for
124 the objects that have been retrieved by \fBOSSL_STORE_load()\fR and similar functions.
125 Supported OpenSSL type object can be extracted using one of
126 STORE_INFO_get0_<TYPE>() where <TYPE> can be NAME, PARAMS, PKEY, CERT, or CRL.
127 The life time of this extracted object is as long as the life time of
128 the \fBOSSL_STORE_INFO\fR it was extracted from, so care should be taken not
129 to free the latter too early.
130 As an alternative, STORE_INFO_get1_<TYPE>() extracts a duplicate (or the
131 same object with its reference count increased), which can be used
132 after the containing \fBOSSL_STORE_INFO\fR has been freed.
133 The object returned by STORE_INFO_get1_<TYPE>() must be freed separately
134 by the caller.
135 See "SUPPORTED OBJECTS" for more information on the types that are supported.
136 .SS Functions
137 .IX Subsection "Functions"
138 \&\fBOSSL_STORE_INFO_get_type()\fR takes a \fBOSSL_STORE_INFO\fR and returns the STORE
139 type number for the object inside.
140 .PP
141 \&\fBSTORE_INFO_get_type_string()\fR takes a STORE type number and returns a
142 short string describing it.
143 .PP
144 \&\fBOSSL_STORE_INFO_get0_NAME()\fR, \fBOSSL_STORE_INFO_get0_NAME_description()\fR,
145 \&\fBOSSL_STORE_INFO_get0_PARAMS()\fR, \fBOSSL_STORE_INFO_get0_PUBKEY()\fR,
146 \&\fBOSSL_STORE_INFO_get0_PKEY()\fR, \fBOSSL_STORE_INFO_get0_CERT()\fR,
147 \&\fBOSSL_STORE_INFO_get0_CRL()\fR
148 all take a \fBOSSL_STORE_INFO\fR and return the object it holds if the
149 \&\fBOSSL_STORE_INFO\fR type (as returned by \fBOSSL_STORE_INFO_get_type()\fR)
150 matches the function, otherwise NULL.
151 .PP
152 \&\fBOSSL_STORE_INFO_get1_NAME()\fR, \fBOSSL_STORE_INFO_get1_NAME_description()\fR,
153 \&\fBOSSL_STORE_INFO_get1_PARAMS()\fR, \fBOSSL_STORE_INFO_get1_PUBKEY()\fR,
154 \&\fBOSSL_STORE_INFO_get1_PKEY()\fR, \fBOSSL_STORE_INFO_get1_CERT()\fR and
155 \&\fBOSSL_STORE_INFO_get1_CRL()\fR
156 all take a \fBOSSL_STORE_INFO\fR and return a duplicate the object it
157 holds if the \fBOSSL_STORE_INFO\fR type (as returned by
158 \&\fBOSSL_STORE_INFO_get_type()\fR) matches the function, otherwise NULL.
159 .PP
160 \&\fBOSSL_STORE_INFO_free()\fR frees a \fBOSSL_STORE_INFO\fR and its contained type.
161 If the argument is NULL, nothing is done.
162 .PP
163 \&\fBOSSL_STORE_INFO_new_NAME()\fR , \fBOSSL_STORE_INFO_new_PARAMS()\fR,
164 , \fBOSSL_STORE_INFO_new_PUBKEY()\fR, \fBOSSL_STORE_INFO_new_PKEY()\fR,
165 \&\fBOSSL_STORE_INFO_new_CERT()\fR and \fBOSSL_STORE_INFO_new_CRL()\fR
166 create a \fBOSSL_STORE_INFO\fR object to hold the given input object.
167 On success the input object is consumed.
168 .PP
169 Additionally, for \fBOSSL_STORE_INFO_NAME\fR objects,
170 \&\fBOSSL_STORE_INFO_set0_NAME_description()\fR can be used to add an extra
171 description.
172 This description is meant to be human readable and should be used for
173 information printout.
174 .PP
175 \&\fBOSSL_STORE_INFO_new()\fR creates a \fBOSSL_STORE_INFO\fR with an arbitrary \fItype\fR
176 number and \fIdata\fR structure. It's the responsibility of the caller to
177 define type numbers other than the ones defined by \fI<openssl/store.h>\fR,
178 and to handle freeing the associated data structure on their own.
179 \&\fIUsing type numbers that are defined by <openssl/store.h> may cause
180 undefined behaviours, including crashes\fR.
181 .PP
182 \&\fBOSSL_STORE_INFO_get0_data()\fR returns the data pointer that was passed to
183 \&\fBOSSL_STORE_INFO_new()\fR if \fItype\fR matches the type number in \fIinfo\fR.
184 .PP
185 \&\fBOSSL_STORE_INFO_new()\fR and \fBOSSL_STORE_INFO_get0_data()\fR may be useful for
186 applications that define their own STORE data, but must be used with care.
187 .SH "SUPPORTED OBJECTS"
188 .IX Header "SUPPORTED OBJECTS"
189 Currently supported object types are:
190 .IP OSSL_STORE_INFO_NAME 4
191 .IX Item "OSSL_STORE_INFO_NAME"
192 A name is exactly that, a name.
193 It's like a name in a directory, but formatted as a complete URI.
194 For example, the path in URI \f(CW\*(C`file:/foo/bar/\*(C'\fR could include a file
195 named \f(CW\*(C`cookie.pem\*(C'\fR, and in that case, the returned \fBOSSL_STORE_INFO_NAME\fR
196 object would have the URI \f(CW\*(C`file:/foo/bar/cookie.pem\*(C'\fR, which can be
197 used by the application to get the objects in that file.
198 This can be applied to all schemes that can somehow support a listing
199 of object URIs.
200 .Sp
201 For \f(CW\*(C`file:\*(C'\fR URIs that are used without the explicit scheme, the
202 returned name will be the path of each object, so if \f(CW\*(C`/foo/bar\*(C'\fR was
203 given and that path has the file \f(CW\*(C`cookie.pem\*(C'\fR, the name
204 \&\f(CW\*(C`/foo/bar/cookie.pem\*(C'\fR will be returned.
205 .Sp
206 The returned URI is considered canonical and must be unique and permanent
207 for the storage where the object (or collection of objects) resides.
208 Each loader is responsible for ensuring that it only returns canonical
209 URIs.
210 However, it's possible that certain schemes allow an object (or collection
211 thereof) to be reached with alternative URIs; just because one URI is
212 canonical doesn't mean that other variants can't be used.
213 .Sp
214 At the discretion of the loader that was used to get these names, an
215 extra description may be attached as well.
216 .IP OSSL_STORE_INFO_PARAMS 4
217 .IX Item "OSSL_STORE_INFO_PARAMS"
218 Key parameters.
219 .IP OSSL_STORE_INFO_PKEY 4
220 .IX Item "OSSL_STORE_INFO_PKEY"
221 A keypair or just a private key (possibly with key parameters).
222 .IP OSSL_STORE_INFO_PUBKEY 4
223 .IX Item "OSSL_STORE_INFO_PUBKEY"
224 A public key (possibly with key parameters).
225 .IP OSSL_STORE_INFO_CERT 4
226 .IX Item "OSSL_STORE_INFO_CERT"
227 An X.509 certificate.
228 .IP OSSL_STORE_INFO_CRL 4
229 .IX Item "OSSL_STORE_INFO_CRL"
230 A X.509 certificate revocation list.
231 .SH "RETURN VALUES"
232 .IX Header "RETURN VALUES"
233 \&\fBOSSL_STORE_INFO_get_type()\fR returns the STORE type number of the given
234 \&\fBOSSL_STORE_INFO\fR.
235 There is no error value.
236 .PP
237 \&\fBOSSL_STORE_INFO_get0_NAME()\fR, \fBOSSL_STORE_INFO_get0_NAME_description()\fR,
238 \&\fBOSSL_STORE_INFO_get0_PARAMS()\fR, \fBOSSL_STORE_INFO_get0_PKEY()\fR,
239 \&\fBOSSL_STORE_INFO_get0_CERT()\fR and \fBOSSL_STORE_INFO_get0_CRL()\fR all return
240 a pointer to the OpenSSL object on success, NULL otherwise.
241 .PP
242 \&\fBOSSL_STORE_INFO_get1_NAME()\fR, \fBOSSL_STORE_INFO_get1_NAME_description()\fR,
243 \&\fBOSSL_STORE_INFO_get1_PARAMS()\fR, \fBOSSL_STORE_INFO_get1_PKEY()\fR,
244 \&\fBOSSL_STORE_INFO_get1_CERT()\fR and \fBOSSL_STORE_INFO_get1_CRL()\fR all return
245 a pointer to a duplicate of the OpenSSL object on success, NULL otherwise.
246 .PP
247 \&\fBOSSL_STORE_INFO_type_string()\fR returns a string on success, or NULL on
248 failure.
249 .PP
250 \&\fBOSSL_STORE_INFO_new_NAME()\fR, \fBOSSL_STORE_INFO_new_PARAMS()\fR,
251 \&\fBOSSL_STORE_INFO_new_PKEY()\fR, \fBOSSL_STORE_INFO_new_CERT()\fR and
252 \&\fBOSSL_STORE_INFO_new_CRL()\fR return a \fBOSSL_STORE_INFO\fR
253 pointer on success, or NULL on failure.
254 .PP
255 \&\fBOSSL_STORE_INFO_set0_NAME_description()\fR returns 1 on success, or 0 on
256 failure.
257 .SH "SEE ALSO"
258 .IX Header "SEE ALSO"
259 \&\fBossl_store\fR\|(7), \fBOSSL_STORE_open\fR\|(3), \fBOSSL_STORE_register_loader\fR\|(3)
260 .SH HISTORY
261 .IX Header "HISTORY"
262 The OSSL_STORE API was added in OpenSSL 1.1.1.
263 .PP
264 The OSSL_STORE_INFO_PUBKEY object type was added in OpenSSL 3.0.
265 .SH COPYRIGHT
266 .IX Header "COPYRIGHT"
267 Copyright 2016\-2024 The OpenSSL Project Authors. All Rights Reserved.
268 .PP
269 Licensed under the Apache License 2.0 (the "License"). You may not use
270 this file except in compliance with the License. You can obtain a copy
271 in the file LICENSE in the source distribution or at
272 <https://www.openssl.org/source/license.html>.