Debian Codegraph @

upstream/debian-unstable/man7/provider-object.7ssl

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 "PROVIDER-OBJECT 7SSL"
58 .TH PROVIDER-OBJECT 7SSL 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 provider\-object \- A specification for a provider\-native object abstraction
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 2
68 \& #include <openssl/core_object.h>
69 \& #include <openssl/core_names.h>
70 .Ve
71 .SH DESCRIPTION
72 .IX Header "DESCRIPTION"
73 The provider-native object abstraction is a set of \fBOSSL_PARAM\fR\|(3) keys and
74 values that can be used to pass provider-native objects to OpenSSL library
75 code or between different provider operation implementations with the help
76 of OpenSSL library code.
77 .PP
78 The intention is that certain provider-native operations can pass any sort
79 of object that belong with other operations, or with OpenSSL library code.
80 .PP
81 An object may be passed in the following manners:
82 .IP 1. 4
83 \&\fIBy value\fR
84 .Sp
85 This means that the \fIobject data\fR is passed as an octet string or an UTF8
86 string, which can be handled in diverse ways by other provided implementations.
87 The encoding of the object depends on the context it's used in; for example,
88 \&\fBOSSL_DECODER\fR\|(3) allows multiple encodings, depending on existing decoders.
89 If central OpenSSL library functionality is to handle the data directly, it
90 \&\fBmust\fR be encoded in DER for all object types except for \fBOSSL_OBJECT_NAME\fR
91 (see "Parameter reference" below), where it's assumed to a plain UTF8 string.
92 .IP 2. 4
93 \&\fIBy reference\fR
94 .Sp
95 This means that the \fIobject data\fR isn't passed directly, an \fIobject
96 reference\fR is passed instead. It's an octet string that only the correct
97 provider understands correctly.
98 .PP
99 Objects \fIby value\fR can be used by anything that handles DER encoded
100 objects.
101 .PP
102 Objects \fIby reference\fR need a higher level of cooperation from the
103 implementation where the object originated (let's call it X) and its target
104 implementation (let's call it Y):
105 .IP 1. 4
106 \&\fIAn object loading function in the target implementation\fR
107 .Sp
108 The target implementation (Y) may have a function that can take an \fIobject
109 reference\fR. This can only be used if the target implementation is from the
110 same provider as the one originating the object abstraction in question (X).
111 .Sp
112 The exact target implementation to use is determined from the \fIobject type\fR
113 and possibly the \fIobject data type\fR.
114 For example, when the OpenSSL library receives an object abstraction with the
115 \&\fIobject type\fR \fBOSSL_OBJECT_PKEY\fR, it will fetch a \fBprovider\-keymgmt\fR\|(7)
116 using the \fIobject data type\fR as its key type (the second argument in
117 \&\fBEVP_KEYMGMT_fetch\fR\|(3)).
118 .IP 2. 4
119 \&\fIAn object exporter in the originating implementation\fR
120 .Sp
121 The originating implementation (X) may have an exporter function. This
122 exporter function can be used to export the object in \fBOSSL_PARAM\fR\|(3) form,
123 that can then be imported by the target implementation's imported function.
124 .Sp
125 This can be used when it's not possible to fetch the target implementation
126 (Y) from the same provider.
127 .SS "Parameter reference"
128 .IX Subsection "Parameter reference"
129 A provider-native object abstraction is an \fBOSSL_PARAM\fR\|(3) with a selection
130 of the following parameters:
131 .IP """data"" (\fBOSSL_OBJECT_PARAM_DATA\fR) <octet string> or <UTF8 string>" 4
132 .IX Item """data"" (OSSL_OBJECT_PARAM_DATA) <octet string> or <UTF8 string>"
133 The object data \fIpassed by value\fR.
134 .IP """reference"" (\fBOSSL_OBJECT_PARAM_REFERENCE\fR) <octet string>" 4
135 .IX Item """reference"" (OSSL_OBJECT_PARAM_REFERENCE) <octet string>"
136 The object data \fIpassed by reference\fR.
137 .IP """type"" (\fBOSSL_OBJECT_PARAM_TYPE\fR) <integer>" 4
138 .IX Item """type"" (OSSL_OBJECT_PARAM_TYPE) <integer>"
139 The \fIobject type\fR, a number that may have any of the following values (all
140 defined in \fI<openssl/core_object.h>\fR):
141 .RS 4
142 .IP \fBOSSL_OBJECT_NAME\fR 4
143 .IX Item "OSSL_OBJECT_NAME"
144 The object data may only be \fIpassed by value\fR, and should be a UTF8
145 string.
146 .Sp
147 This is useful for \fBprovider\-storemgmt\fR\|(7) when a URI load results in new
148 URIs.
149 .IP \fBOSSL_OBJECT_PKEY\fR 4
150 .IX Item "OSSL_OBJECT_PKEY"
151 The object data is suitable as provider-native \fBEVP_PKEY\fR key data. The
152 object data may be \fIpassed by value\fR or \fIpassed by reference\fR.
153 .IP \fBOSSL_OBJECT_CERT\fR 4
154 .IX Item "OSSL_OBJECT_CERT"
155 The object data is suitable as \fBX509\fR data. The object data for this
156 object type can only be \fIpassed by value\fR, and should be an octet string.
157 .Sp
158 Since there's no provider-native X.509 object, OpenSSL libraries that
159 receive this object abstraction are expected to convert the data to a
160 \&\fBX509\fR object with \fBd2i_X509()\fR.
161 .IP \fBOSSL_OBJECT_CRL\fR 4
162 .IX Item "OSSL_OBJECT_CRL"
163 The object data is suitable as \fBX509_CRL\fR data. The object data can
164 only be \fIpassed by value\fR, and should be an octet string.
165 .Sp
166 Since there's no provider-native X.509 CRL object, OpenSSL libraries that
167 receive this object abstraction are expected to convert the data to a
168 \&\fBX509_CRL\fR object with \fBd2i_X509_CRL()\fR.
169 .RE
170 .RS 4
171 .RE
172 .IP """data-type"" (\fBOSSL_OBJECT_PARAM_DATA_TYPE\fR) <UTF8 string>" 4
173 .IX Item """data-type"" (OSSL_OBJECT_PARAM_DATA_TYPE) <UTF8 string>"
174 The specific type of the object content. Legitimate values depend on the
175 object type; if it is \fBOSSL_OBJECT_PKEY\fR, the data type is expected to be a
176 key type suitable for fetching a \fBprovider\-keymgmt\fR\|(7) that can handle the
177 data.
178 .IP """data-structure"" (\fBOSSL_OBJECT_PARAM_DATA_STRUCTURE\fR) <UTF8 string>" 4
179 .IX Item """data-structure"" (OSSL_OBJECT_PARAM_DATA_STRUCTURE) <UTF8 string>"
180 The outermost structure of the object content. Legitimate values depend on
181 the object type.
182 .IP """desc"" (\fBOSSL_OBJECT_PARAM_DESC\fR) <UTF8 string>" 4
183 .IX Item """desc"" (OSSL_OBJECT_PARAM_DESC) <UTF8 string>"
184 A human readable text that describes extra details on the object.
185 .PP
186 When a provider-native object abstraction is used, it \fImust\fR contain object
187 data in at least one form (object data \fIpassed by value\fR, i.e. the "data"
188 item, or object data \fIpassed by reference\fR, i.e. the "reference" item).
189 Both may be present at once, in which case the OpenSSL library code that
190 receives this will use the most optimal variant.
191 .PP
192 For objects with the object type \fBOSSL_OBJECT_NAME\fR, that object type
193 \&\fImust\fR be given.
194 .SH "SEE ALSO"
195 .IX Header "SEE ALSO"
196 \&\fBprovider\fR\|(7), \fBOSSL_DECODER\fR\|(3)
197 .SH HISTORY
198 .IX Header "HISTORY"
199 The concept of providers and everything surrounding them was
200 introduced in OpenSSL 3.0.
201 .SH COPYRIGHT
202 .IX Header "COPYRIGHT"
203 Copyright 2020\-2022 The OpenSSL Project Authors. All Rights Reserved.
204 .PP
205 Licensed under the Apache License 2.0 (the "License"). You may not use
206 this file except in compliance with the License. You can obtain a copy
207 in the file LICENSE in the source distribution or at
208 <https://www.openssl.org/source/license.html>.