doc/man7/provider-decoder.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 provider-decoder - The OSSL_DECODER library E<lt>-E<gt> provider functions
   6
   7 =head1 SYNOPSIS
   8
   9  #include <openssl/core_dispatch.h>
  10
  11  /*
  12   * None of these are actual functions, but are displayed like this for
  13   * the function signatures for functions that are offered as function
  14   * pointers in OSSL_DISPATCH arrays.
  15   */
  16
  17  /* Decoder parameter accessor and descriptor */
  18  const OSSL_PARAM *OSSL_FUNC_decoder_gettable_params(void *provctx);
  19  int OSSL_FUNC_decoder_get_params(OSSL_PARAM params[]);
  20
  21  /* Functions to construct / destruct / manipulate the decoder context */
  22  void *OSSL_FUNC_decoder_newctx(void *provctx);
  23  void OSSL_FUNC_decoder_freectx(void *ctx);
  24  const OSSL_PARAM *OSSL_FUNC_decoder_settable_ctx_params(void *provctx);
  25  int OSSL_FUNC_decoder_set_ctx_params(void *ctx, const OSSL_PARAM params[]);
  26
  27  /* Functions to check selection support */
  28  int OSSL_FUNC_decoder_does_selection(void *provctx, int selection);
  29
  30  /* Functions to decode object data */
  31  int OSSL_FUNC_decoder_decode(void *ctx, OSSL_CORE_BIO *in,
  32                               int selection,
  33                               OSSL_CALLBACK *data_cb, void *data_cbarg,
  34                               OSSL_PASSPHRASE_CALLBACK *cb, void *cbarg);
  35
  36  /* Functions to export a decoded object */
  37  void *OSSL_FUNC_decoder_export_object(void *ctx,
  38                                        const void *objref, size_t objref_sz,
  39                                        OSSL_CALLBACK *export_cb,
  40                                        void *export_cbarg);
  41
  42 =head1 DESCRIPTION
  43
  44 I<The term "decode" is used throughout this manual.  This includes but is
  45 not limited to deserialization as individual decoders can also do
  46 decoding into intermediate data formats.>
  47
  48 The DECODER operation is a generic method to create a provider-native
  49 object reference or intermediate decoded data from an encoded form
  50 read from the given B<OSSL_CORE_BIO>. If the caller wants to decode
  51 data from memory, it should provide a L<BIO_s_mem(3)> B<BIO>. The decoded
  52 data or object reference is passed along with eventual metadata
  53 to the I<metadata_cb> as B<OSSL_PARAM> parameters.
  54
  55 The decoder doesn't need to know more about the B<OSSL_CORE_BIO>
  56 pointer than being able to pass it to the appropriate BIO upcalls (see
  57 L<provider-base(7)/Core functions>).
  58
  59 The DECODER implementation may be part of a chain, where data is
  60 passed from one to the next.  For example, there may be an
  61 implementation to decode an object from PEM to DER, and another one
  62 that decodes DER to a provider-native object.
  63
  64 The last decoding step in the decoding chain is usually supposed to create
  65 a provider-native object referenced by an object reference. To import
  66 that object into a different provider the OSSL_FUNC_decoder_export_object()
  67 can be called as the final step of the decoding process.
  68
  69 All "functions" mentioned here are passed as function pointers between
  70 F<libcrypto> and the provider in B<OSSL_DISPATCH> arrays via
  71 B<OSSL_ALGORITHM> arrays that are returned by the provider's
  72 provider_query_operation() function
  73 (see L<provider-base(7)/Provider Functions>).
  74
  75 All these "functions" have a corresponding function type definition
  76 named B<OSSL_FUNC_{name}_fn>, and a helper function to retrieve the
  77 function pointer from an B<OSSL_DISPATCH> element named
  78 B<OSSL_FUNC_{name}>.
  79 For example, the "function" OSSL_FUNC_decoder_decode() has these:
  80
  81  typedef int
  82      (OSSL_FUNC_decoder_decode_fn)(void *ctx, OSSL_CORE_BIO *in,
  83                                    int selection,
  84                                    OSSL_CALLBACK *data_cb, void *data_cbarg,
  85                                    OSSL_PASSPHRASE_CALLBACK *cb, void *cbarg);
  86  static ossl_inline OSSL_FUNC_decoder_decode_fn
  87      OSSL_FUNC_decoder_decode(const OSSL_DISPATCH *opf);
  88
  89 B<OSSL_DISPATCH> arrays are indexed by numbers that are provided as
  90 macros in L<openssl-core_dispatch.h(7)>, as follows:
  91
  92  OSSL_FUNC_decoder_get_params          OSSL_FUNC_DECODER_GET_PARAMS
  93  OSSL_FUNC_decoder_gettable_params     OSSL_FUNC_DECODER_GETTABLE_PARAMS
  94
  95  OSSL_FUNC_decoder_newctx              OSSL_FUNC_DECODER_NEWCTX
  96  OSSL_FUNC_decoder_freectx             OSSL_FUNC_DECODER_FREECTX
  97  OSSL_FUNC_decoder_set_ctx_params      OSSL_FUNC_DECODER_SET_CTX_PARAMS
  98  OSSL_FUNC_decoder_settable_ctx_params OSSL_FUNC_DECODER_SETTABLE_CTX_PARAMS
  99
 100  OSSL_FUNC_decoder_does_selection      OSSL_FUNC_DECODER_DOES_SELECTION
 101
 102  OSSL_FUNC_decoder_decode              OSSL_FUNC_DECODER_DECODE
 103
 104  OSSL_FUNC_decoder_export_object       OSSL_FUNC_DECODER_EXPORT_OBJECT
 105
 106 =head2 Names and properties
 107
 108 The name of an implementation should match the target type of object
 109 it decodes. For example, an implementation that decodes an RSA key
 110 should be named "RSA". Likewise, an implementation that decodes DER data
 111 from PEM input should be named "DER".
 112
 113 Properties can be used to further specify details about an implementation:
 114
 115 =over 4
 116
 117 =item input
 118
 119 This property is used to specify what format of input the implementation
 120 can decode.
 121
 122 This property is I<mandatory>.
 123
 124 OpenSSL providers recognize the following input types:
 125
 126 =over 4
 127
 128 =item pem
 129
 130 An implementation with that input type decodes PEM formatted data.
 131
 132 =item der
 133
 134 An implementation with that input type decodes DER formatted data.
 135
 136 =item msblob
 137
 138 An implementation with that input type decodes MSBLOB formatted data.
 139
 140 =item pvk
 141
 142 An implementation with that input type decodes PVK formatted data.
 143
 144 =back
 145
 146 =item structure
 147
 148 This property is used to specify the structure that the decoded data is
 149 expected to have.
 150
 151 This property is I<optional>.
 152
 153 Structures currently recognised by built-in decoders:
 154
 155 =over 4
 156
 157 =item "type-specific"
 158
 159 Type specific structure.
 160
 161 =item "pkcs8"
 162
 163 Structure according to the PKCS#8 specification.
 164
 165 =item "SubjectPublicKeyInfo"
 166
 167 Encoding of public keys according to the Subject Public Key Info of RFC 5280.
 168
 169 =back
 170
 171 =back
 172
 173 The possible values of both these properties is open ended.  A provider may
 174 very well specify input types and structures that libcrypto doesn't know
 175 anything about.
 176
 177 =head2 Subset selections
 178
 179 Sometimes, an object has more than one subset of data that is interesting to
 180 treat separately or together.  It's possible to specify what subsets are to
 181 be decoded, with a set of bits I<selection> that are passed in an B<int>.
 182
 183 This set of bits depend entirely on what kind of provider-side object is
 184 to be decoded.  For example, those bits are assumed to be the same as those
 185 used with L<provider-keymgmt(7)> (see L<provider-keymgmt(7)/Key Objects>) when
 186 the object is an asymmetric keypair - e.g., B<OSSL_KEYMGMT_SELECT_PRIVATE_KEY>
 187 if the object to be decoded is supposed to contain private key components.
 188
 189 OSSL_FUNC_decoder_does_selection() should tell if a particular implementation
 190 supports any of the combinations given by I<selection>.
 191
 192 =head2 Context functions
 193
 194 OSSL_FUNC_decoder_newctx() returns a context to be used with the rest of
 195 the functions.
 196
 197 OSSL_FUNC_decoder_freectx() frees the given I<ctx> as created by
 198 OSSL_FUNC_decoder_newctx().
 199
 200 OSSL_FUNC_decoder_set_ctx_params() sets context data according to parameters
 201 from I<params> that it recognises.  Unrecognised parameters should be
 202 ignored.
 203 Passing NULL for I<params> should return true.
 204
 205 OSSL_FUNC_decoder_settable_ctx_params() returns a constant B<OSSL_PARAM>
 206 array describing the parameters that OSSL_FUNC_decoder_set_ctx_params()
 207 can handle.
 208
 209 See L<OSSL_PARAM(3)> for further details on the parameters structure used by
 210 OSSL_FUNC_decoder_set_ctx_params() and OSSL_FUNC_decoder_settable_ctx_params().
 211
 212 =head2 Export function
 213
 214 When a provider-native object is created by a decoder it would be unsuitable
 215 for direct use with a foreign provider. The export function allows for
 216 exporting the object into that foreign provider if the foreign provider
 217 supports the type of the object and provides an import function.
 218
 219 OSSL_FUNC_decoder_export_object() should export the object of size I<objref_sz>
 220 referenced by I<objref> as an B<OSSL_PARAM> array and pass that into the
 221 I<export_cb> as well as the given I<export_cbarg>.
 222
 223 =head2 Decoding functions
 224
 225 OSSL_FUNC_decoder_decode() should decode the data as read from
 226 the B<OSSL_CORE_BIO> I<in> to produce decoded data or an object to be
 227 passed as reference in an B<OSSL_PARAM> array along with possible other
 228 metadata that was decoded from the input. This B<OSSL_PARAM> array is
 229 then passed to the I<data_cb> callback.  The I<selection> bits,
 230 if relevant, should determine what the input data should contain.
 231 The decoding functions also take an B<OSSL_PASSPHRASE_CALLBACK> function
 232 pointer along with a pointer to application data I<cbarg>, which should be
 233 used when a pass phrase prompt is needed.
 234
 235 It's important to understand that the return value from this function is
 236 interpreted as follows:
 237
 238 =over 4
 239
 240 =item True (1)
 241
 242 This means "carry on the decoding process", and is meaningful even though
 243 this function couldn't decode the input into anything, because there may be
 244 another decoder implementation that can decode it into something.
 245
 246 The I<data_cb> callback should never be called when this function can't
 247 decode the input into anything.
 248
 249 =item False (0)
 250
 251 This means "stop the decoding process", and is meaningful when the input
 252 could be decoded into some sort of object that this function understands,
 253 but further treatment of that object results into errors that won't be
 254 possible for some other decoder implementation to get a different result.
 255
 256 =back
 257
 258 The conditions to stop the decoding process are at the discretion of the
 259 implementation.
 260
 261 =head2 Decoder operation parameters
 262
 263 There are currently no operation parameters currently recognised by the
 264 built-in decoders.
 265
 266 Parameters currently recognised by the built-in pass phrase callback:
 267
 268 =over 4
 269
 270 =item "info" (B<OSSL_PASSPHRASE_PARAM_INFO>) <UTF8 string>
 271
 272 A string of information that will become part of the pass phrase
 273 prompt.  This could be used to give the user information on what kind
 274 of object it's being prompted for.
 275
 276 =back
 277
 278 =head1 RETURN VALUES
 279
 280 OSSL_FUNC_decoder_newctx() returns a pointer to a context, or NULL on
 281 failure.
 282
 283 OSSL_FUNC_decoder_set_ctx_params() returns 1, unless a recognised
 284 parameter was invalid or caused an error, for which 0 is returned.
 285
 286 OSSL_FUNC_decoder_settable_ctx_params() returns a pointer to an array of
 287 constant B<OSSL_PARAM> elements.
 288
 289 OSSL_FUNC_decoder_does_selection() returns 1 if the decoder implementation
 290 supports any of the I<selection> bits, otherwise 0.
 291
 292 OSSL_FUNC_decoder_decode() returns 1 to signal that the decoding process
 293 should continue, or 0 to signal that it should stop.
 294
 295 =head1 SEE ALSO
 296
 297 L<provider(7)>
 298
 299 =head1 HISTORY
 300
 301 The DECODER interface was introduced in OpenSSL 3.0.
 302
 303 =head1 COPYRIGHT
 304
 305 Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved.
 306
 307 Licensed under the Apache License 2.0 (the "License").  You may not use
 308 this file except in compliance with the License.  You can obtain a copy
 309 in the file LICENSE in the source distribution or at
 310 L<https://www.openssl.org/source/license.html>.
 311
 312 =cut