doc/man3/OSSL_DECODER_CTX.pod

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