| 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-2021 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
|
|---|
