doc/man7/provider-encoder.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 provider-encoder - The ENCODER 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  /* Functions to construct / destruct / manipulate the encoder context */
  18  void *OSSL_FUNC_encoder_newctx(void *provctx);
  19  void OSSL_FUNC_encoder_freectx(void *ctx);
  20  int OSSL_FUNC_encoder_set_ctx_params(void *ctx, const OSSL_PARAM params[]);
  21  const OSSL_PARAM *OSSL_FUNC_encoder_settable_ctx_params(void *provctx)
  22
  23  /* Functions to encode object data */
  24  int OSSL_FUNC_encoder_encode_data(void *ctx, const OSSL_PARAM *data,
  25                                          OSSL_CORE_BIO *out,
  26                                          OSSL_PASSPHRASE_CALLBACK *cb,
  27                                          void *cbarg);
  28  int OSSL_FUNC_encoder_encode_object(void *ctx, void *obj, OSSL_CORE_BIO *out,
  29                                            OSSL_PASSPHRASE_CALLBACK *cb,
  30                                            void *cbarg);
  31
  32 =head1 DESCRIPTION
  33
  34 I<We use the wide term "encode" in this manual.  This includes but is
  35 not limited to serialization.>
  36
  37 The ENCODER is a generic method to encode any set of object data
  38 in L<OSSL_PARAM(3)> array form, or any provider side object into
  39 encoded form, and write it to the given OSSL_CORE_BIO.  If the caller wants
  40 to get the encoded stream to memory, it should provide a
  41 L<BIO_s_membuf(3)>.
  42
  43 The encoder doesn't need to know more about the B<OSSL_CORE_BIO> pointer than
  44 being able to pass it to the appropriate BIO upcalls (see
  45 L<provider-base(7)/Core functions>).
  46
  47 The encoding using the L<OSSL_PARAM(3)> array form allows a
  48 encoder to be used for data that's been exported from another
  49 provider, and thereby allow them to exist independently of each
  50 other.
  51
  52 The encoding using a provider side object can only be safely used
  53 with provider data coming from the same provider, for example keys
  54 with the L<KEYMGMT|provider-keymgmt(7)> provider.
  55
  56 All "functions" mentioned here are passed as function pointers between
  57 F<libcrypto> and the provider in B<OSSL_DISPATCH> arrays via
  58 B<OSSL_ALGORITHM> arrays that are returned by the provider's
  59 provider_query_operation() function
  60 (see L<provider-base(7)/Provider Functions>).
  61
  62 All these "functions" have a corresponding function type definition
  63 named B<OSSL_{name}_fn>, and a helper function to retrieve the
  64 function pointer from a B<OSSL_DISPATCH> element named
  65 B<OSSL_FUNC_{name}>.
  66 For example, the "function" OSSL_FUNC_encoder_encode_data() has these:
  67
  68  typedef int
  69      (OSSL_FUNC_encoder_encode_data_fn)(void *provctx,
  70                                             const OSSL_PARAM params[],
  71                                             OSSL_CORE_BIO *out);
  72  static ossl_inline OSSL_FUNC_encoder_encode_data_fn
  73      OSSL_FUNC_encoder_encode_data(const OSSL_DISPATCH *opf);
  74
  75 B<OSSL_DISPATCH> arrays are indexed by numbers that are provided as
  76 macros in L<openssl-core_dispatch.h(7)>, as follows:
  77
  78  OSSL_FUNC_encoder_newctx              OSSL_FUNC_ENCODER_NEWCTX
  79  OSSL_FUNC_encoder_freectx             OSSL_FUNC_ENCODER_FREECTX
  80  OSSL_FUNC_encoder_set_ctx_params      OSSL_FUNC_ENCODER_SET_CTX_PARAMS
  81  OSSL_FUNC_encoder_settable_ctx_params OSSL_FUNC_ENCODER_SETTABLE_CTX_PARAMS
  82
  83  OSSL_FUNC_encoder_encode_data      OSSL_FUNC_ENCODER_ENCODE_DATA
  84  OSSL_FUNC_encoder_encode_object    OSSL_FUNC_ENCODER_ENCODE_OBJECT
  85
  86 =head2 Names and properties
  87
  88 The name of an implementation should match the type of object it
  89 handles.  For example, an implementation that encodes an RSA key
  90 should be named accordingly.
  91
  92 To be able to specify exactly what encoding format and what type
  93 of data a encoder implementation is expected to handle, two
  94 additional properties may be given:
  95
  96 =over 4
  97
  98 =item format
  99
 100 This property is used to specify what kind of output format the
 101 implementation produces.  Currently known formats are:
 102
 103 =over 4
 104
 105 =item text
 106
 107 An implementation with that format property value outputs human
 108 readable text, making that implementation suitable for C<-text> output
 109 in diverse L<openssl(1)> commands.
 110
 111 =item pem
 112
 113 An implementation with that format property value outputs PEM
 114 formatted data.
 115
 116 =item der
 117
 118 An implementation with that format property value outputs DER
 119 formatted data.
 120
 121 =back
 122
 123 =item type
 124
 125 With objects that have multiple purposes, this can be used to specify
 126 the purpose type.  The currently known use cases are asymmetric keys
 127 and key parameters, where the type can be one of:
 128
 129 =over 4
 130
 131 =item private
 132
 133 An implementation with that format property value outputs a private
 134 key.
 135
 136 =item public
 137
 138 An implementation with that format property value outputs a public
 139 key.
 140
 141 =item parameters
 142
 143 An implementation with that format property value outputs key
 144 parameters.
 145
 146 =back
 147
 148 =back
 149
 150 The possible values of both these properties is open ended.  A
 151 provider may very well specify other formats that libcrypto doesn't
 152 know anything about.
 153
 154 =head2 Context functions
 155
 156 OSSL_FUNC_encoder_newctx() returns a context to be used with the rest of
 157 the functions.
 158
 159 OSSL_FUNC_encoder_freectx() frees the given I<ctx>, if it was created by
 160 OSSL_FUNC_encoder_newctx().
 161
 162 OSSL_FUNC_encoder_set_ctx_params() sets context data according to
 163 parameters from I<params> that it recognises.  Unrecognised parameters
 164 should be ignored.
 165
 166 OSSL_FUNC_encoder_settable_ctx_params() returns a constant B<OSSL_PARAM>
 167 array describing the parameters that OSSL_FUNC_encoder_set_ctx_params()
 168 can handle.
 169
 170 See L<OSSL_PARAM(3)> for further details on the parameters structure used
 171 by OSSL_FUNC_encoder_set_ctx_params() and OSSL_FUNC_encoder_settable_ctx_params().
 172
 173 =head2 Encoding functions
 174
 175 =for comment There will be a "Decoding functions" title as well
 176
 177 OSSL_FUNC_encoder_encode_data() should take an array of B<OSSL_PARAM>,
 178 I<data>, and if it contains the data necessary for the object type
 179 that the implementation handles, it should output the object in
 180 encoded form to the B<OSSL_CORE_BIO>.
 181
 182 OSSL_FUNC_encoder_encode_object() should take a pointer to an object
 183 that it knows intimately, and output that object in encoded form to
 184 the B<OSSL_CORE_BIO>.  The caller I<must> ensure that this function is called
 185 with a pointer that the provider of this function is familiar with.
 186 It is not suitable to use with object pointers coming from other
 187 providers.
 188
 189 Both encoding functions also take an B<OSSL_PASSPHRASE_CALLBACK>
 190 function pointer along with a pointer to application data I<cbarg>,
 191 which should be used when a pass phrase prompt is needed.
 192
 193 =head2 Encoder parameters
 194
 195 Parameters currently recognised by built-in encoders are as
 196 follows:
 197
 198 =over 4
 199
 200 =item "cipher" (B<OSSL_ENCODER_PARAM_CIPHER>) <UTF8 string>
 201
 202 The name of the encryption cipher to be used when generating encrypted
 203 encoding.  This is used when encoding private keys, as well as
 204 other objects that need protection.
 205
 206 If this name is invalid for the encoding implementation, the
 207 implementation should refuse to perform the encoding, i.e.
 208 OSSL_FUNC_encoder_encode_data() and OSSL_FUNC_encoder_encode_object()
 209 should return an error.
 210
 211 =item "properties" (B<OSSL_ENCODER_PARAM_PROPERTIES>) <UTF8 string>
 212
 213 The properties to be queried when trying to fetch the algorithm given
 214 with the "cipher" parameter.
 215 This must be given together with the "cipher" parameter to be
 216 considered valid.
 217
 218 The encoding implementation isn't obligated to use this value.
 219 However, it is recommended that implementations that do not handle
 220 property strings return an error on receiving this parameter unless
 221 its value NULL or the empty string.
 222
 223 =item "passphrase" (B<OSSL_ENCODER_PARAM_PASS>) <octet string>
 224
 225 A pass phrase provided by the application.  When this is given, the
 226 built-in encoders will not attempt to use the passphrase callback.
 227
 228 =back
 229
 230 Parameters currently recognised by the built-in pass phrase callback:
 231
 232 =over 4
 233
 234 =item "info" (B<OSSL_PASSPHRASE_PARAM_INFO>) <UTF8 string>
 235
 236 A string of information that will become part of the pass phrase
 237 prompt.  This could be used to give the user information on what kind
 238 of object it's being prompted for.
 239
 240 =back
 241
 242 =head1 RETURN VALUES
 243
 244 OSSL_FUNC_encoder_newctx() returns a pointer to a context, or NULL on
 245 failure.
 246
 247 OSSL_FUNC_encoder_set_ctx_params() returns 1, unless a recognised
 248 parameters was invalid or caused an error, for which 0 is returned.
 249
 250 OSSL_FUNC_encoder_settable_ctx_params() returns a pointer to an array of
 251 constant B<OSSL_PARAM> elements.
 252
 253 OSSL_FUNC_encoder_encode_data() and OSSL_FUNC_encoder_encode_object()
 254 return 1 on success, or 0 on failure.
 255
 256 =head1 SEE ALSO
 257
 258 L<provider(7)>
 259
 260 =head1 HISTORY
 261
 262 The ENCODER interface was introduced in OpenSSL 3.0.
 263
 264 =head1 COPYRIGHT
 265
 266 Copyright 2019-2020 The OpenSSL Project Authors. All Rights Reserved.
 267
 268 Licensed under the Apache License 2.0 (the "License").  You may not use
 269 this file except in compliance with the License.  You can obtain a copy
 270 in the file LICENSE in the source distribution or at
 271 L<https://www.openssl.org/source/license.html>.
 272
 273 =cut