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