doc/man3/OSSL_DECODER_from_bio.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 OSSL_DECODER_from_bio,
   6 OSSL_DECODER_from_fp,
   7 OSSL_DECODER_CTX_set_input_type,
   8 OSSL_DECODER_CTX_add_decoder,
   9 OSSL_DECODER_CTX_add_extra,
  10 OSSL_DECODER_CTX_num_decoders,
  11 OSSL_DECODER_INSTANCE,
  12 OSSL_DECODER_CONSTRUCT,
  13 OSSL_DECODER_CLEANUP,
  14 OSSL_DECODER_CTX_set_construct,
  15 OSSL_DECODER_CTX_set_construct_data,
  16 OSSL_DECODER_CTX_set_cleanup,
  17 OSSL_DECODER_CTX_get_construct,
  18 OSSL_DECODER_CTX_get_construct_data,
  19 OSSL_DECODER_CTX_get_cleanup,
  20 OSSL_DECODER_export,
  21 OSSL_DECODER_INSTANCE_decoder,
  22 OSSL_DECODER_INSTANCE_decoder_ctx
  23 - Routines to perform a decoding
  24
  25 =head1 SYNOPSIS
  26
  27  #include <openssl/decoder.h>
  28
  29  int OSSL_DECODER_from_bio(OSSL_DECODER_CTX *ctx, BIO *in);
  30  int OSSL_DECODER_from_fp(OSSL_DECODER_CTX *ctx, FILE *fp);
  31
  32  int OSSL_DECODER_CTX_set_input_type(OSSL_DECODER_CTX *ctx,
  33                                      const char *input_type);
  34  int OSSL_DECODER_CTX_add_decoder(OSSL_DECODER_CTX *ctx, OSSL_DECODER *decoder);
  35  int OSSL_DECODER_CTX_add_extra(OSSL_DECODER_CTX *ctx);
  36  int OSSL_DECODER_CTX_num_decoders(OSSL_DECODER_CTX *ctx);
  37
  38  typedef struct ossl_decoder_instance_st OSSL_DECODER_INSTANCE;
  39  OSSL_DECODER *
  40  OSSL_DECODER_INSTANCE_decoder(OSSL_DECODER_INSTANCE *decoder_inst);
  41  void *OSSL_DECODER_INSTANCE_decoder_ctx(OSSL_DECODER_INSTANCE *decoder_inst);
  42
  43  typedef int (OSSL_DECODER_CONSTRUCT)(OSSL_DECODER_INSTANCE *decoder_inst,
  44                                       const OSSL_PARAM *params,
  45                                       void *construct_data);
  46  typedef void (OSSL_DECODER_CLEANUP)(void *construct_data);
  47
  48  int OSSL_DECODER_CTX_set_construct(OSSL_DECODER_CTX *ctx,
  49                                     OSSL_DECODER_CONSTRUCT *construct);
  50  int OSSL_DECODER_CTX_set_construct_data(OSSL_DECODER_CTX *ctx,
  51                                          void *construct_data);
  52  int OSSL_DECODER_CTX_set_cleanup(OSSL_DECODER_CTX *ctx,
  53                                   OSSL_DECODER_CLEANUP *cleanup);
  54  OSSL_DECODER_CONSTRUCT *OSSL_DECODER_CTX_get_construct(OSSL_DECODER_CTX *ctx);
  55  void *OSSL_DECODER_CTX_get_construct_data(OSSL_DECODER_CTX *ctx);
  56  OSSL_DECODER_CLEANUP *OSSL_DECODER_CTX_get_cleanup(OSSL_DECODER_CTX *ctx);
  57
  58  int OSSL_DECODER_export(OSSL_DECODER_INSTANCE *decoder_inst,
  59                          void *reference, size_t reference_sz,
  60                          OSSL_CALLBACK *export_cb, void *export_cbarg);
  61
  62 Feature availability macros:
  63
  64 =over 4
  65
  66 =item OSSL_DECODER_from_fp() is only available when B<OPENSSL_NO_STDIO>
  67 is undefined.
  68
  69 =back
  70
  71 =head1 DESCRIPTION
  72
  73 The B<OSSL_DECODER_CTX> holds data about multiple decoders, as
  74 needed to figure out what the input data is and to attempt to unpack it into
  75 one of several possible related results.  This also includes chaining
  76 decoders, so the output from one can become the input for another.
  77 This allows having generic format decoders such as PEM to DER, as well
  78 as more specialized decoders like DER to RSA.
  79
  80 The chains may be limited by specifying an input type, which is considered a
  81 starting point.
  82 This is both considered by OSSL_DECODER_CTX_add_extra(), which will
  83 stop adding on more decoder implementations when it has already added
  84 those that take the specified input type, and OSSL_DECODER_from_bio(),
  85 which will only start the decoding process with the decoder
  86 implementations that take that input type.  For example, if the input type
  87 is set to C<DER>, a PEM to DER decoder will be ignored.
  88
  89 The input type can also be NULL, which means that the caller doesn't know
  90 what type of input they have.  In this case, OSSL_DECODER_from_bio()
  91 will simply try with one decoder implementation after the other, and
  92 thereby discover what kind of input the caller gave it.
  93
  94 For every decoding done, even an intermediary one, a constructor
  95 provided by the caller is called to attempt to construct an appropriate type
  96 / structure that the caller knows how to handle from the current
  97 decoding result.
  98 The constructor is set with OSSL_DECODER_CTX_set_construct().
  99
 100 B<OSSL_DECODER_INSTANCE> is an opaque structure that contains
 101 data about the decoder that was just used, and that may be
 102 useful for the constructor.  There are some functions to extract data
 103 from this type, described further down.
 104
 105 =head2 Functions
 106
 107 OSSL_DECODER_from_bio() runs the decoding process for the
 108 context I<ctx>, with the input coming from the B<BIO> I<in>.  Should
 109 it make a difference, it's recommended to have the BIO set in binary
 110 mode rather than text mode.
 111
 112 OSSL_DECODER_from_fp() does the same thing as OSSL_DECODER_from_bio(),
 113 except that the input is coming from the B<FILE> I<fp>.
 114
 115 OSSL_DECODER_CTX_add_decoder() populates the B<OSSL_DECODER_CTX>
 116 I<ctx> with a decoder, to be used to attempt to decode some
 117 encoded input.
 118
 119 OSSL_DECODER_CTX_add_extra() finds decoders that generate
 120 input for already added decoders, and adds them as well.  This is
 121 used to build decoder chains.
 122
 123 OSSL_DECODER_CTX_set_input_type() sets the starting input type.  This
 124 limits the decoder chains to be considered, as explained in the general
 125 description above.
 126
 127 OSSL_DECODER_CTX_num_decoders() gets the number of
 128 decoders currently added to the context I<ctx>.
 129
 130 OSSL_DECODER_CTX_set_construct() sets the constructor I<construct>.
 131
 132 OSSL_DECODER_CTX_set_construct_data() sets the constructor data that is
 133 passed to the constructor every time it's called.
 134
 135 OSSL_DECODER_CTX_set_cleanup() sets the constructor data I<cleanup>
 136 function.  This is called by L<OSSL_DECODER_CTX_free(3)>.
 137
 138 OSSL_DECODER_CTX_get_construct(),
 139 OSSL_DECODER_CTX_get_construct_data() and
 140 OSSL_DECODER_CTX_get_cleanup()
 141 return the values that have been set by
 142 OSSL_DECODER_CTX_set_construct(),
 143 OSSL_DECODER_CTX_set_construct_data() and
 144 OSSL_DECODER_CTX_set_cleanup() respectively.
 145
 146 OSSL_DECODER_export() is a fallback function for constructors that
 147 cannot use the data they get directly for diverse reasons.  It takes the same
 148 decode instance I<decoder_inst> that the constructor got and an object
 149 I<reference>, unpacks the object which it refers to, and exports it by creating
 150 an L<OSSL_PARAM(3)> array that it then passes to I<export_cb>, along with
 151 I<export_arg>.
 152
 153 OSSL_DECODER_INSTANCE_decoder() can be used to get the
 154 decoder method from a decoder instance I<decoder_inst>.
 155
 156 OSSL_DECODER_INSTANCE_decoder-ctx() can be used to get the
 157 decoder method's provider context from a decoder instance
 158 I<decoder_inst>.
 159
 160 =head2 Constructor
 161
 162 A B<OSSL_DECODER_CONSTRUCT> gets the following arguments:
 163
 164 =over 4
 165
 166 =item I<decoder_inst>
 167
 168 The B<OSSL_DECODER_INSTANCE> for the decoder from which
 169 the constructor gets its data.
 170
 171 =item I<params>
 172
 173 The data produced by the decoder, further described below.
 174
 175 =item I<construct_data>
 176
 177 The pointer that was set with OSSL_DECODE_CTX_set_construct_data().
 178
 179 =back
 180
 181 The constructor is expected to return 1 when the data it receives can
 182 be constructed, otherwise 0.
 183
 184 The globally known parameters that the constructor can get in I<params>
 185 are:
 186
 187 =over 4
 188
 189 =item "data-type" (B<OSSL_DECODER_PARAM_DATA_TYPE>) <UTF8 string>
 190
 191 This is a detected content type that some decoders may provide.
 192 For example, PEM input sometimes has a type specified in its header,
 193 and some decoders may add that information as this parameter.
 194 This is an optional parameter, but may be useful for extra checks in
 195 the constructor.
 196
 197 =item "data" (B<OSSL_DECODER_PARAM_DATA>) <octet string>
 198
 199 The decoded data itself, as an octet string.  This is produced by
 200 decoders when it's possible to pass an object in this form.  Most
 201 often, this is simply meant to be passed to the next decoder in a
 202 chain, but could be considered final data as well, at the discretion
 203 of the constructor.
 204
 205 =item "reference" (B<OSSL_DECODER_PARAM_DATA>) <octet string>
 206
 207 The decoded data itself, as a reference to an object.  The
 208 reference itself is an octet string, and can be passed to other
 209 operations and functions within the same provider as the one that
 210 provides I<decoder>.
 211
 212 =back
 213
 214 At least one of "data" or "reference" must be present, and it's
 215 possible that both can be.  A constructor should choose to use the
 216 "reference" parameter if possible, otherwise it should use the "data"
 217 parameter.
 218
 219 If it's not possible to use the "reference" parameter, but that's
 220 still what a constructor wants to do, it is possible to use
 221 OSSL_DECODER_export() as a fallback.
 222
 223 =head1 RETURN VALUES
 224
 225 OSSL_DECODER_from_bio() and OSSL_DECODER_from_fp() return 1 on
 226 success, or 0 on failure.
 227
 228 OSSL_DECODER_CTX_add_decoder(),
 229 OSSL_DECODER_CTX_add_extra(),
 230 OSSL_DECODER_CTX_set_construct(),
 231 OSSL_DECODER_CTX_set_construct_data() and
 232 OSSL_DECODER_CTX_set_cleanup() return 1 on success, or 0 on
 233 failure.
 234
 235 OSSL_DECODER_CTX_get_construct(),
 236 OSSL_DECODER_CTX_get_construct_data() and
 237 OSSL_DECODER_CTX_get_cleanup() return the current pointers to the
 238 cosntructor, the constructor data and the cleanup functions, respectively.
 239
 240 OSSL_DECODER_CTX_num_decoders() returns the current
 241 number of decoders.  It returns 0 if I<ctx> is NULL.
 242
 243 OSSL_DECODER_export() returns 1 on success, or 0 on failure.
 244
 245 OSSL_DECODER_INSTANCE_decoder() returns an
 246 B<OSSL_DECODER> pointer on success, or NULL on failure.
 247
 248 OSSL_DECODER_INSTANCE_decoder_ctx() returns a provider
 249 context pointer on success, or NULL on failure.>
 250
 251 =begin comment TODO(3.0) Add examples!
 252
 253 =head1 EXAMPLES
 254
 255 Text, because pod2xxx doesn't like empty sections
 256
 257 =end comment
 258
 259 =head1 SEE ALSO
 260
 261 L<provider(7)>, L<OSSL_DECODER_CTX(3)>
 262
 263 =head1 HISTORY
 264
 265 The functions described here were added in OpenSSL 3.0.
 266
 267 =head1 COPYRIGHT
 268
 269 Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
 270
 271 Licensed under the Apache License 2.0 (the "License").  You may not use
 272 this file except in compliance with the License.  You can obtain a copy
 273 in the file LICENSE in the source distribution or at
 274 L<https://www.openssl.org/source/license.html>.
 275
 276 =cut