1=pod 2 3=head1 NAME 4 5OSSL_DECODER_CTX, 6OSSL_DECODER_CTX_new, 7OSSL_DECODER_settable_ctx_params, 8OSSL_DECODER_CTX_set_params, 9OSSL_DECODER_CTX_free, 10OSSL_DECODER_CTX_set_selection, 11OSSL_DECODER_CTX_set_input_type, 12OSSL_DECODER_CTX_set_input_structure, 13OSSL_DECODER_CTX_add_decoder, 14OSSL_DECODER_CTX_add_extra, 15OSSL_DECODER_CTX_get_num_decoders, 16OSSL_DECODER_INSTANCE, 17OSSL_DECODER_CONSTRUCT, 18OSSL_DECODER_CLEANUP, 19OSSL_DECODER_CTX_set_construct, 20OSSL_DECODER_CTX_set_construct_data, 21OSSL_DECODER_CTX_set_cleanup, 22OSSL_DECODER_CTX_get_construct, 23OSSL_DECODER_CTX_get_construct_data, 24OSSL_DECODER_CTX_get_cleanup, 25OSSL_DECODER_export, 26OSSL_DECODER_INSTANCE_get_decoder, 27OSSL_DECODER_INSTANCE_get_decoder_ctx, 28OSSL_DECODER_INSTANCE_get_input_type, 29OSSL_DECODER_INSTANCE_get_input_structure 30- Decoder context routines 31 32=head1 SYNOPSIS 33 34 #include <openssl/decoder.h> 35 36 typedef struct ossl_decoder_ctx_st OSSL_DECODER_CTX; 37 38 OSSL_DECODER_CTX *OSSL_DECODER_CTX_new(void); 39 const OSSL_PARAM *OSSL_DECODER_settable_ctx_params(OSSL_DECODER *decoder); 40 int OSSL_DECODER_CTX_set_params(OSSL_DECODER_CTX *ctx, 41 const OSSL_PARAM params[]); 42 void OSSL_DECODER_CTX_free(OSSL_DECODER_CTX *ctx); 43 44 int OSSL_DECODER_CTX_set_selection(OSSL_DECODER_CTX *ctx, int selection); 45 int OSSL_DECODER_CTX_set_input_type(OSSL_DECODER_CTX *ctx, 46 const char *input_type); 47 int OSSL_DECODER_CTX_set_input_structure(OSSL_DECODER_CTX *ctx, 48 const char *input_structure); 49 int OSSL_DECODER_CTX_add_decoder(OSSL_DECODER_CTX *ctx, OSSL_DECODER *decoder); 50 int OSSL_DECODER_CTX_add_extra(OSSL_DECODER_CTX *ctx, 51 OSSL_LIB_CTX *libctx, 52 const char *propq); 53 int OSSL_DECODER_CTX_get_num_decoders(OSSL_DECODER_CTX *ctx); 54 55 typedef struct ossl_decoder_instance_st OSSL_DECODER_INSTANCE; 56 OSSL_DECODER * 57 OSSL_DECODER_INSTANCE_get_decoder(OSSL_DECODER_INSTANCE *decoder_inst); 58 void * 59 OSSL_DECODER_INSTANCE_get_decoder_ctx(OSSL_DECODER_INSTANCE *decoder_inst); 60 const char * 61 OSSL_DECODER_INSTANCE_get_input_type(OSSL_DECODER_INSTANCE *decoder_inst); 62 OSSL_DECODER_INSTANCE_get_input_structure(OSSL_DECODER_INSTANCE *decoder_inst, 63 int *was_set); 64 65 typedef int OSSL_DECODER_CONSTRUCT(OSSL_DECODER_INSTANCE *decoder_inst, 66 const OSSL_PARAM *object, 67 void *construct_data); 68 typedef void OSSL_DECODER_CLEANUP(void *construct_data); 69 70 int OSSL_DECODER_CTX_set_construct(OSSL_DECODER_CTX *ctx, 71 OSSL_DECODER_CONSTRUCT *construct); 72 int OSSL_DECODER_CTX_set_construct_data(OSSL_DECODER_CTX *ctx, 73 void *construct_data); 74 int OSSL_DECODER_CTX_set_cleanup(OSSL_DECODER_CTX *ctx, 75 OSSL_DECODER_CLEANUP *cleanup); 76 OSSL_DECODER_CONSTRUCT *OSSL_DECODER_CTX_get_construct(OSSL_DECODER_CTX *ctx); 77 void *OSSL_DECODER_CTX_get_construct_data(OSSL_DECODER_CTX *ctx); 78 OSSL_DECODER_CLEANUP *OSSL_DECODER_CTX_get_cleanup(OSSL_DECODER_CTX *ctx); 79 80 int OSSL_DECODER_export(OSSL_DECODER_INSTANCE *decoder_inst, 81 void *reference, size_t reference_sz, 82 OSSL_CALLBACK *export_cb, void *export_cbarg); 83 84=head1 DESCRIPTION 85 86The B<OSSL_DECODER_CTX> holds data about multiple decoders, as needed to 87figure out what the input data is and to attempt to unpack it into one of 88several possible related results. This also includes chaining decoders, so 89the output from one can become the input for another. This allows having 90generic format decoders such as PEM to DER, as well as more specialized 91decoders like DER to RSA. 92 93The chains may be limited by specifying an input type, which is considered a 94starting point. This is both considered by OSSL_DECODER_CTX_add_extra(), 95which will stop adding one more decoder implementations when it has already 96added those that take the specified input type, and functions like 97L<OSSL_DECODER_from_bio(3)>, which will only start the decoding process with 98the decoder implementations that take that input type. For example, if the 99input type is set to C<DER>, a PEM to DER decoder will be ignored. 100 101The input type can also be NULL, which means that the caller doesn't know 102what type of input they have. In this case, OSSL_DECODER_from_bio() will 103simply try with one decoder implementation after the other, and thereby 104discover what kind of input the caller gave it. 105 106For every decoding done, even an intermediary one, a constructor provided by 107the caller is called to attempt to construct an appropriate type / structure 108that the caller knows how to handle from the current decoding result. 109The constructor is set with OSSL_DECODER_CTX_set_construct(). 110 111B<OSSL_DECODER_INSTANCE> is an opaque structure that contains data about the 112decoder that was just used, and that may be useful for the constructor. 113There are some functions to extract data from this type, described further 114down. 115 116=head2 Functions 117 118OSSL_DECODER_CTX_new() creates a new empty B<OSSL_DECODER_CTX>. 119 120OSSL_DECODER_settable_ctx_params() returns an L<OSSL_PARAM(3)> array of 121parameter descriptors. 122 123OSSL_DECODER_CTX_set_params() attempts to set parameters specified with an 124L<OSSL_PARAM(3)> array I<params>. These parameters are passed to all 125decoders that have been added to the I<ctx> so far. Parameters that an 126implementation doesn't recognise should be ignored by it. 127 128OSSL_DECODER_CTX_free() frees the given context I<ctx>. 129If the argument is NULL, nothing is done. 130 131OSSL_DECODER_CTX_add_decoder() populates the B<OSSL_DECODER_CTX> I<ctx> with 132a decoder, to be used to attempt to decode some encoded input. 133 134OSSL_DECODER_CTX_add_extra() finds decoders that generate input for already 135added decoders, and adds them as well. This is used to build decoder 136chains. 137 138OSSL_DECODER_CTX_set_input_type() sets the starting input type. This limits 139the decoder chains to be considered, as explained in the general description 140above. 141 142OSSL_DECODER_CTX_set_input_structure() sets the name of the structure that 143the input is expected to have. This may be used to determines what decoder 144implementations may be used. NULL is a valid input structure, when it's not 145relevant, or when the decoder implementations are expected to figure it out. 146 147OSSL_DECODER_CTX_get_num_decoders() gets the number of decoders currently 148added to the context I<ctx>. 149 150OSSL_DECODER_CTX_set_construct() sets the constructor I<construct>. 151 152OSSL_DECODER_CTX_set_construct_data() sets the constructor data that is 153passed to the constructor every time it's called. 154 155OSSL_DECODER_CTX_set_cleanup() sets the constructor data I<cleanup> 156function. This is called by L<OSSL_DECODER_CTX_free(3)>. 157 158OSSL_DECODER_CTX_get_construct(), OSSL_DECODER_CTX_get_construct_data() and 159OSSL_DECODER_CTX_get_cleanup() return the values that have been set by 160OSSL_DECODER_CTX_set_construct(), OSSL_DECODER_CTX_set_construct_data() and 161OSSL_DECODER_CTX_set_cleanup() respectively. 162 163OSSL_DECODER_export() is a fallback function for constructors that cannot 164use the data they get directly for diverse reasons. It takes the same 165decode instance I<decoder_inst> that the constructor got and an object 166I<reference>, unpacks the object which it refers to, and exports it by 167creating an L<OSSL_PARAM(3)> array that it then passes to I<export_cb>, 168along with I<export_arg>. 169 170=head2 Constructor 171 172A B<OSSL_DECODER_CONSTRUCT> gets the following arguments: 173 174=over 4 175 176=item I<decoder_inst> 177 178The B<OSSL_DECODER_INSTANCE> for the decoder from which the constructor gets 179its data. 180 181=item I<object> 182 183A provider-native object abstraction produced by the decoder. Further 184information on the provider-native object abstraction can be found in 185L<provider-object(7)>. 186 187=item I<construct_data> 188 189The pointer that was set with OSSL_DECODE_CTX_set_construct_data(). 190 191=back 192 193The constructor is expected to return 1 when the data it receives can be 194constructed, otherwise 0. 195 196These utility functions may be used by a constructor: 197 198OSSL_DECODER_INSTANCE_get_decoder() can be used to get the decoder 199implementation from a decoder instance I<decoder_inst>. 200 201OSSL_DECODER_INSTANCE_get_decoder_ctx() can be used to get the decoder 202implementation's provider context from a decoder instance I<decoder_inst>. 203 204OSSL_DECODER_INSTANCE_get_input_type() can be used to get the decoder 205implementation's input type from a decoder instance I<decoder_inst>. 206 207OSSL_DECODER_INSTANCE_get_input_structure() can be used to get the input 208structure for the decoder implementation from a decoder instance 209I<decoder_inst>. 210This may be NULL. 211 212=head1 RETURN VALUES 213 214OSSL_DECODER_CTX_new() returns a pointer to a B<OSSL_DECODER_CTX>, or NULL 215if the context structure couldn't be allocated. 216 217OSSL_DECODER_settable_ctx_params() returns an L<OSSL_PARAM(3)> array, or 218NULL if none is available. 219 220OSSL_DECODER_CTX_set_params() returns 1 if all recognised parameters were 221valid, or 0 if one of them was invalid or caused some other failure in the 222implementation. 223 224OSSL_DECODER_CTX_add_decoder(), OSSL_DECODER_CTX_add_extra(), 225OSSL_DECODER_CTX_set_construct(), OSSL_DECODER_CTX_set_construct_data() and 226OSSL_DECODER_CTX_set_cleanup() return 1 on success, or 0 on failure. 227 228OSSL_DECODER_CTX_get_construct(), OSSL_DECODER_CTX_get_construct_data() and 229OSSL_DECODER_CTX_get_cleanup() return the current pointers to the 230constructor, the constructor data and the cleanup functions, respectively. 231 232OSSL_DECODER_CTX_num_decoders() returns the current number of decoders. It 233returns 0 if I<ctx> is NULL. 234 235OSSL_DECODER_export() returns 1 on success, or 0 on failure. 236 237OSSL_DECODER_INSTANCE_decoder() returns an B<OSSL_DECODER> pointer on 238success, or NULL on failure. 239 240OSSL_DECODER_INSTANCE_decoder_ctx() returns a provider context pointer on 241success, or NULL on failure. 242 243=head1 SEE ALSO 244 245L<provider(7)>, L<OSSL_DECODER(3)>, L<OSSL_DECODER_from_bio(3)> 246 247=head1 HISTORY 248 249The functions described here were added in OpenSSL 3.0. 250 251=head1 COPYRIGHT 252 253Copyright 2020-2024 The OpenSSL Project Authors. All Rights Reserved. 254 255Licensed under the Apache License 2.0 (the "License"). You may not use 256this file except in compliance with the License. You can obtain a copy 257in the file LICENSE in the source distribution or at 258L<https://www.openssl.org/source/license.html>. 259 260=cut 261