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