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>. 129 130OSSL_DECODER_CTX_add_decoder() populates the B<OSSL_DECODER_CTX> I<ctx> with 131a decoder, to be used to attempt to decode some encoded input. 132 133OSSL_DECODER_CTX_add_extra() finds decoders that generate input for already 134added decoders, and adds them as well. This is used to build decoder 135chains. 136 137OSSL_DECODER_CTX_set_input_type() sets the starting input type. This limits 138the decoder chains to be considered, as explained in the general description 139above. 140 141OSSL_DECODER_CTX_set_input_structure() sets the name of the structure that 142the input is expected to have. This may be used to determines what decoder 143implementations may be used. NULL is a valid input structure, when it's not 144relevant, or when the decoder implementations are expected to figure it out. 145 146OSSL_DECODER_CTX_get_num_decoders() gets the number of decoders currently 147added to the context I<ctx>. 148 149OSSL_DECODER_CTX_set_construct() sets the constructor I<construct>. 150 151OSSL_DECODER_CTX_set_construct_data() sets the constructor data that is 152passed to the constructor every time it's called. 153 154OSSL_DECODER_CTX_set_cleanup() sets the constructor data I<cleanup> 155function. This is called by L<OSSL_DECODER_CTX_free(3)>. 156 157OSSL_DECODER_CTX_get_construct(), OSSL_DECODER_CTX_get_construct_data() and 158OSSL_DECODER_CTX_get_cleanup() return the values that have been set by 159OSSL_DECODER_CTX_set_construct(), OSSL_DECODER_CTX_set_construct_data() and 160OSSL_DECODER_CTX_set_cleanup() respectively. 161 162OSSL_DECODER_export() is a fallback function for constructors that cannot 163use the data they get directly for diverse reasons. It takes the same 164decode instance I<decoder_inst> that the constructor got and an object 165I<reference>, unpacks the object which it refers to, and exports it by 166creating an L<OSSL_PARAM(3)> array that it then passes to I<export_cb>, 167along with I<export_arg>. 168 169=head2 Constructor 170 171A B<OSSL_DECODER_CONSTRUCT> gets the following arguments: 172 173=over 4 174 175=item I<decoder_inst> 176 177The B<OSSL_DECODER_INSTANCE> for the decoder from which the constructor gets 178its data. 179 180=item I<object> 181 182A provider-native object abstraction produced by the decoder. Further 183information on the provider-native object abstraction can be found in 184L<provider-object(7)>. 185 186=item I<construct_data> 187 188The pointer that was set with OSSL_DECODE_CTX_set_construct_data(). 189 190=back 191 192The constructor is expected to return 1 when the data it receives can be 193constructed, otherwise 0. 194 195These utility functions may be used by a constructor: 196 197OSSL_DECODER_INSTANCE_get_decoder() can be used to get the decoder 198implementation from a decoder instance I<decoder_inst>. 199 200OSSL_DECODER_INSTANCE_get_decoder_ctx() can be used to get the decoder 201implementation's provider context from a decoder instance I<decoder_inst>. 202 203OSSL_DECODER_INSTANCE_get_input_type() can be used to get the decoder 204implementation's input type from a decoder instance I<decoder_inst>. 205 206OSSL_DECODER_INSTANCE_get_input_structure() can be used to get the input 207structure for the decoder implementation from a decoder instance 208I<decoder_inst>. 209This may be NULL. 210 211=head1 RETURN VALUES 212 213OSSL_DECODER_CTX_new() returns a pointer to a B<OSSL_DECODER_CTX>, or NULL 214if the context structure couldn't be allocated. 215 216OSSL_DECODER_settable_ctx_params() returns an L<OSSL_PARAM(3)> array, or 217NULL if none is available. 218 219OSSL_DECODER_CTX_set_params() returns 1 if all recognised parameters were 220valid, or 0 if one of them was invalid or caused some other failure in the 221implementation. 222 223OSSL_DECODER_CTX_add_decoder(), OSSL_DECODER_CTX_add_extra(), 224OSSL_DECODER_CTX_set_construct(), OSSL_DECODER_CTX_set_construct_data() and 225OSSL_DECODER_CTX_set_cleanup() return 1 on success, or 0 on failure. 226 227OSSL_DECODER_CTX_get_construct(), OSSL_DECODER_CTX_get_construct_data() and 228OSSL_DECODER_CTX_get_cleanup() return the current pointers to the 229constructor, the constructor data and the cleanup functions, respectively. 230 231OSSL_DECODER_CTX_num_decoders() returns the current number of decoders. It 232returns 0 if I<ctx> is NULL. 233 234OSSL_DECODER_export() returns 1 on success, or 0 on failure. 235 236OSSL_DECODER_INSTANCE_decoder() returns an B<OSSL_DECODER> pointer on 237success, or NULL on failure. 238 239OSSL_DECODER_INSTANCE_decoder_ctx() returns a provider context pointer on 240success, or NULL on failure. 241 242=head1 SEE ALSO 243 244L<provider(7)>, L<OSSL_DECODER(3)>, L<OSSL_DECODER_from_bio(3)> 245 246=head1 HISTORY 247 248The functions described here were added in OpenSSL 3.0. 249 250=head1 COPYRIGHT 251 252Copyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved. 253 254Licensed under the Apache License 2.0 (the "License"). You may not use 255this file except in compliance with the License. You can obtain a copy 256in the file LICENSE in the source distribution or at 257L<https://www.openssl.org/source/license.html>. 258 259=cut 260