1 =pod 2 3 =head1 NAME 4 5 provider-decoder - The OSSL_DECODER library E<lt>-E<gt> provider functions 6 7 =head1 SYNOPSIS 8 9 #include <openssl/core_dispatch.h> 10 11 /* 12 * None of these are actual functions, but are displayed like this for 13 * the function signatures for functions that are offered as function 14 * pointers in OSSL_DISPATCH arrays. 15 */ 16 17 /* Decoder parameter accessor and descriptor */ 18 const OSSL_PARAM *OSSL_FUNC_decoder_gettable_params(void *provctx); 19 int OSSL_FUNC_decoder_get_params(OSSL_PARAM params[]); 20 21 /* Functions to construct / destruct / manipulate the decoder context */ 22 void *OSSL_FUNC_decoder_newctx(void *provctx); 23 void OSSL_FUNC_decoder_freectx(void *ctx); 24 const OSSL_PARAM *OSSL_FUNC_decoder_settable_ctx_params(void *provctx); 25 int OSSL_FUNC_decoder_set_ctx_params(void *ctx, const OSSL_PARAM params[]); 26 27 /* Functions to check selection support */ 28 int OSSL_FUNC_decoder_does_selection(void *provctx, int selection); 29 30 /* Functions to decode object data */ 31 int OSSL_FUNC_decoder_decode(void *ctx, OSSL_CORE_BIO *in, 32 int selection, 33 OSSL_CALLBACK *data_cb, void *data_cbarg, 34 OSSL_PASSPHRASE_CALLBACK *cb, void *cbarg); 35 36 /* Functions to export a decoded object */ 37 int OSSL_FUNC_decoder_export_object(void *ctx, 38 const void *objref, size_t objref_sz, 39 OSSL_CALLBACK *export_cb, 40 void *export_cbarg); 41 42 =head1 DESCRIPTION 43 44 I<The term "decode" is used throughout this manual. This includes but is 45 not limited to deserialization as individual decoders can also do 46 decoding into intermediate data formats.> 47 48 The DECODER operation is a generic method to create a provider-native 49 object reference or intermediate decoded data from an encoded form 50 read from the given B<OSSL_CORE_BIO>. If the caller wants to decode 51 data from memory, it should provide a L<BIO_s_mem(3)> B<BIO>. The decoded 52 data or object reference is passed along with eventual metadata 53 to the I<metadata_cb> as L<OSSL_PARAM(3)> parameters. 54 55 The decoder doesn't need to know more about the B<OSSL_CORE_BIO> 56 pointer than being able to pass it to the appropriate BIO upcalls (see 57 L<provider-base(7)/Core functions>). 58 59 The DECODER implementation may be part of a chain, where data is 60 passed from one to the next. For example, there may be an 61 implementation to decode an object from PEM to DER, and another one 62 that decodes DER to a provider-native object. 63 64 The last decoding step in the decoding chain is usually supposed to create 65 a provider-native object referenced by an object reference. To import 66 that object into a different provider the OSSL_FUNC_decoder_export_object() 67 can be called as the final step of the decoding process. 68 69 All "functions" mentioned here are passed as function pointers between 70 F<libcrypto> and the provider in L<OSSL_DISPATCH(3)> arrays via 71 L<OSSL_ALGORITHM(3)> arrays that are returned by the provider's 72 provider_query_operation() function 73 (see L<provider-base(7)/Provider Functions>). 74 75 All these "functions" have a corresponding function type definition 76 named B<OSSL_FUNC_{name}_fn>, and a helper function to retrieve the 77 function pointer from an L<OSSL_DISPATCH(3)> element named 78 B<OSSL_FUNC_{name}>. 79 For example, the "function" OSSL_FUNC_decoder_decode() has these: 80 81 typedef int 82 (OSSL_FUNC_decoder_decode_fn)(void *ctx, OSSL_CORE_BIO *in, 83 int selection, 84 OSSL_CALLBACK *data_cb, void *data_cbarg, 85 OSSL_PASSPHRASE_CALLBACK *cb, void *cbarg); 86 static ossl_inline OSSL_FUNC_decoder_decode_fn* 87 OSSL_FUNC_decoder_decode(const OSSL_DISPATCH *opf); 88 89 L<OSSL_DISPATCH(3)> arrays are indexed by numbers that are provided as 90 macros in L<openssl-core_dispatch.h(7)>, as follows: 91 92 OSSL_FUNC_decoder_get_params OSSL_FUNC_DECODER_GET_PARAMS 93 OSSL_FUNC_decoder_gettable_params OSSL_FUNC_DECODER_GETTABLE_PARAMS 94 95 OSSL_FUNC_decoder_newctx OSSL_FUNC_DECODER_NEWCTX 96 OSSL_FUNC_decoder_freectx OSSL_FUNC_DECODER_FREECTX 97 OSSL_FUNC_decoder_set_ctx_params OSSL_FUNC_DECODER_SET_CTX_PARAMS 98 OSSL_FUNC_decoder_settable_ctx_params OSSL_FUNC_DECODER_SETTABLE_CTX_PARAMS 99 100 OSSL_FUNC_decoder_does_selection OSSL_FUNC_DECODER_DOES_SELECTION 101 102 OSSL_FUNC_decoder_decode OSSL_FUNC_DECODER_DECODE 103 104 OSSL_FUNC_decoder_export_object OSSL_FUNC_DECODER_EXPORT_OBJECT 105 106 =head2 Names and properties 107 108 The name of an implementation should match the target type of object 109 it decodes. For example, an implementation that decodes an RSA key 110 should be named "RSA". Likewise, an implementation that decodes DER data 111 from PEM input should be named "DER". 112 113 Properties, as defined in the L<OSSL_ALGORITHM(3)> array element of each 114 decoder implementation, can be used to further specify details about an 115 implementation: 116 117 =over 4 118 119 =item input 120 121 This property is used to specify what format of input the implementation 122 can decode. 123 124 This property is I<mandatory>. 125 126 OpenSSL providers recognize the following input types: 127 128 =over 4 129 130 =item pem 131 132 An implementation with that input type decodes PEM formatted data. 133 134 =item der 135 136 An implementation with that input type decodes DER formatted data. 137 138 =item msblob 139 140 An implementation with that input type decodes MSBLOB formatted data. 141 142 =item pvk 143 144 An implementation with that input type decodes PVK formatted data. 145 146 =back 147 148 =item structure 149 150 This property is used to specify the structure that the decoded data is 151 expected to have. 152 153 This property is I<optional>. 154 155 Structures currently recognised by built-in decoders: 156 157 =over 4 158 159 =item "type-specific" 160 161 Type specific structure. 162 163 =item "pkcs8" 164 165 Structure according to the PKCS#8 specification. 166 167 =item "SubjectPublicKeyInfo" 168 169 Encoding of public keys according to the Subject Public Key Info of RFC 5280. 170 171 =back 172 173 =back 174 175 The possible values of both these properties is open ended. A provider may 176 very well specify input types and structures that libcrypto doesn't know 177 anything about. 178 179 =head2 Subset selections 180 181 Sometimes, an object has more than one subset of data that is interesting to 182 treat separately or together. It's possible to specify what subsets are to 183 be decoded, with a set of bits I<selection> that are passed in an B<int>. 184 185 This set of bits depend entirely on what kind of provider-side object is 186 to be decoded. For example, those bits are assumed to be the same as those 187 used with L<provider-keymgmt(7)> (see L<provider-keymgmt(7)/Key Objects>) when 188 the object is an asymmetric keypair - e.g., B<OSSL_KEYMGMT_SELECT_PRIVATE_KEY> 189 if the object to be decoded is supposed to contain private key components. 190 191 OSSL_FUNC_decoder_does_selection() should tell if a particular implementation 192 supports any of the combinations given by I<selection>. 193 194 =head2 Context functions 195 196 OSSL_FUNC_decoder_newctx() returns a context to be used with the rest of 197 the functions. 198 199 OSSL_FUNC_decoder_freectx() frees the given I<ctx> as created by 200 OSSL_FUNC_decoder_newctx(). 201 202 OSSL_FUNC_decoder_set_ctx_params() sets context data according to parameters 203 from I<params> that it recognises. Unrecognised parameters should be 204 ignored. 205 Passing NULL for I<params> should return true. 206 207 OSSL_FUNC_decoder_settable_ctx_params() returns a constant L<OSSL_PARAM(3)> 208 array describing the parameters that OSSL_FUNC_decoder_set_ctx_params() 209 can handle. 210 211 See L<OSSL_PARAM(3)> for further details on the parameters structure used by 212 OSSL_FUNC_decoder_set_ctx_params() and OSSL_FUNC_decoder_settable_ctx_params(). 213 214 =head2 Export function 215 216 When a provider-native object is created by a decoder it would be unsuitable 217 for direct use with a foreign provider. The export function allows for 218 exporting the object into that foreign provider if the foreign provider 219 supports the type of the object and provides an import function. 220 221 OSSL_FUNC_decoder_export_object() should export the object of size I<objref_sz> 222 referenced by I<objref> as an L<OSSL_PARAM(3)> array and pass that into the 223 I<export_cb> as well as the given I<export_cbarg>. 224 225 =head2 Decoding functions 226 227 OSSL_FUNC_decoder_decode() should decode the data as read from 228 the B<OSSL_CORE_BIO> I<in> to produce decoded data or an object to be 229 passed as reference in an L<OSSL_PARAM(3)> array along with possible other 230 metadata that was decoded from the input. This L<OSSL_PARAM(3)> array is 231 then passed to the I<data_cb> callback. The I<selection> bits, 232 if relevant, should determine what the input data should contain. 233 The decoding functions also take an L<OSSL_PASSPHRASE_CALLBACK(3)> function 234 pointer along with a pointer to application data I<cbarg>, which should be 235 used when a pass phrase prompt is needed. 236 237 It's important to understand that the return value from this function is 238 interpreted as follows: 239 240 =over 4 241 242 =item True (1) 243 244 This means "carry on the decoding process", and is meaningful even though 245 this function couldn't decode the input into anything, because there may be 246 another decoder implementation that can decode it into something. 247 248 The I<data_cb> callback should never be called when this function can't 249 decode the input into anything. 250 251 =item False (0) 252 253 This means "stop the decoding process", and is meaningful when the input 254 could be decoded into some sort of object that this function understands, 255 but further treatment of that object results into errors that won't be 256 possible for some other decoder implementation to get a different result. 257 258 =back 259 260 The conditions to stop the decoding process are at the discretion of the 261 implementation. 262 263 =head2 Decoder operation parameters 264 265 There are currently no operation parameters currently recognised by the 266 built-in decoders. 267 268 Parameters currently recognised by the built-in pass phrase callback: 269 270 =over 4 271 272 =item "info" (B<OSSL_PASSPHRASE_PARAM_INFO>) <UTF8 string> 273 274 A string of information that will become part of the pass phrase 275 prompt. This could be used to give the user information on what kind 276 of object it's being prompted for. 277 278 =back 279 280 =head1 RETURN VALUES 281 282 OSSL_FUNC_decoder_newctx() returns a pointer to a context, or NULL on 283 failure. 284 285 OSSL_FUNC_decoder_set_ctx_params() returns 1, unless a recognised 286 parameter was invalid or caused an error, for which 0 is returned. 287 288 OSSL_FUNC_decoder_settable_ctx_params() returns a pointer to an array of 289 constant L<OSSL_PARAM(3)> elements. 290 291 OSSL_FUNC_decoder_does_selection() returns 1 if the decoder implementation 292 supports any of the I<selection> bits, otherwise 0. 293 294 OSSL_FUNC_decoder_decode() returns 1 to signal that the decoding process 295 should continue, or 0 to signal that it should stop. 296 297 =head1 SEE ALSO 298 299 L<provider(7)> 300 301 =head1 HISTORY 302 303 The DECODER interface was introduced in OpenSSL 3.0. 304 305 =head1 COPYRIGHT 306 307 Copyright 2019-2025 The OpenSSL Project Authors. All Rights Reserved. 308 309 Licensed under the Apache License 2.0 (the "License"). You may not use 310 this file except in compliance with the License. You can obtain a copy 311 in the file LICENSE in the source distribution or at 312 L<https://www.openssl.org/source/license.html>. 313 314 =cut 315
Indexes created Thu Oct 08 00:26:19 UTC 2026