doc/man3/OSSL_DESERIALIZER_from_bio.pod

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