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