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