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