doc/man3/OSSL_DECODER_CTX_new_for_pkey.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 OSSL_DECODER_CTX_new_for_pkey,
   6 OSSL_DECODER_CTX_set_passphrase,
   7 OSSL_DECODER_CTX_set_pem_password_cb,
   8 OSSL_DECODER_CTX_set_passphrase_ui,
   9 OSSL_DECODER_CTX_set_passphrase_cb
  10 - Decoder routines to decode EVP_PKEYs
  11
  12 =head1 SYNOPSIS
  13
  14  #include <openssl/decoder.h>
  15
  16  OSSL_DECODER_CTX *
  17  OSSL_DECODER_CTX_new_for_pkey(EVP_PKEY **pkey,
  18                                const char *input_type,
  19                                const char *input_struct,
  20                                const char *keytype, int selection,
  21                                OSSL_LIB_CTX *libctx, const char *propquery);
  22
  23  int OSSL_DECODER_CTX_set_passphrase(OSSL_DECODER_CTX *ctx,
  24                                      const unsigned char *kstr,
  25                                      size_t klen);
  26  int OSSL_DECODER_CTX_set_pem_password_cb(OSSL_DECODER_CTX *ctx,
  27                                           pem_password_cb *cb,
  28                                           void *cbarg);
  29  int OSSL_DECODER_CTX_set_passphrase_ui(OSSL_DECODER_CTX *ctx,
  30                                         const UI_METHOD *ui_method,
  31                                         void *ui_data);
  32  int OSSL_DECODER_CTX_set_passphrase_cb(OSSL_DECODER_CTX *ctx,
  33                                         OSSL_PASSPHRASE_CALLBACK *cb,
  34                                         void *cbarg);
  35
  36 =head1 DESCRIPTION
  37
  38 OSSL_DECODER_CTX_new_for_pkey() is a utility function that creates a
  39 B<OSSL_DECODER_CTX>, finds all applicable decoder implementations and sets
  40 them up, so all the caller has to do next is call functions like
  41 L<OSSL_DECODER_from_bio(3)>.  The caller may use the optional I<input_type>,
  42 I<input_struct>, I<keytype> and I<selection> to specify what the input is
  43 expected to contain.  The I<pkey> must reference an B<EVP_PKEY *> variable
  44 that will be set to the newly created B<EVP_PKEY> on succesfull decoding.
  45 The referenced variable must be initialized to NULL before calling the
  46 function.
  47
  48 Internally OSSL_DECODER_CTX_new_for_pkey() searches for all available
  49 L<EVP_KEYMGMT(3)> implementations, and then builds a list of all potential
  50 decoder implementations that may be able to process the encoded input into
  51 data suitable for B<EVP_PKEY>s.  All these implementations are implicitly
  52 fetched using I<libctx> and I<propquery>.
  53
  54 The search of decoder implementations can be limited with I<input_type> and
  55 I<input_struct> which specifies a starting input type and input structure.
  56 NULL is valid for both of them and signifies that the decoder implementations
  57 will find out the input type on their own.
  58 They are set with L<OSSL_DECODER_CTX_set_input_type(3)> and
  59 L<OSSL_DECODER_CTX_set_input_structure(3)>.
  60 See L</Input Types> and L</Input Structures> below for further information.
  61
  62 The search of decoder implementations can also be limited with I<keytype>
  63 and I<selection>, which specifies the expected resulting keytype and contents.
  64 NULL and zero are valid and signify that the decoder implementations will
  65 find out the keytype and key contents on their own from the input they get.
  66
  67 If no suitable decoder implementation is found,
  68 OSSL_DECODER_CTX_new_for_pkey() still creates a B<OSSL_DECODER_CTX>, but
  69 with no associated decoder (L<OSSL_DECODER_CTX_get_num_decoders(3)> returns
  70 zero).  This helps the caller to distinguish between an error when creating
  71 the B<OSSL_ENCODER_CTX> and missing encoder implementation, and allows it to
  72 act accordingly.
  73
  74 OSSL_DECODER_CTX_set_passphrase() gives the implementation a pass phrase to
  75 use when decrypting the encoded private key. Alternatively, a pass phrase
  76 callback may be specified with the following functions.
  77
  78 OSSL_DECODER_CTX_set_pem_password_cb(), OSSL_DECODER_CTX_set_passphrase_ui()
  79 and OSSL_DECODER_CTX_set_passphrase_cb() set up a callback method that the
  80 implementation can use to prompt for a pass phrase, giving the caller the
  81 choice of prefered pass phrase callback form.  These are called indirectly,
  82 through an internal B<OSSL_PASSPHRASE_CALLBACK> function.
  83
  84 The internal B<OSSL_PASSPHRASE_CALLBACK> function caches the pass phrase, to
  85 be re-used in all decodings that are performed in the same decoding run (for
  86 example, within one L<OSSL_DECODER_from_bio(3)> call).
  87
  88 =head2 Input Types
  89
  90 Available input types depend on the implementations that available providers
  91 offer, and provider documentation should have the details.
  92
  93 Among the known input types that OpenSSL decoder implementations offer
  94 for B<EVP_PKEY>s are C<DER>, C<PEM>, C<MSBLOB> and C<PVK>.
  95 See L<openssl-glossary(7)> for further information on what these input
  96 types mean.
  97
  98 =head2 Input Structures
  99
 100 Available input structures depend on the implementations that available
 101 providers offer, and provider documentation should have the details.
 102
 103 Among the known input structures that OpenSSL decoder implementations
 104 offer for B<EVP_PKEY>s are C<pkcs8> and C<SubjectPublicKeyInfo>.
 105
 106 OpenSSL decoder implementations also support the input structure
 107 C<type-specific>.  This is the structure used for keys encoded
 108 according to key type specific specifications.  For example, RSA keys
 109 encoded according to PKCS#1.
 110
 111 =head2 Selections
 112
 113 I<selection> can be any one of the values described in
 114 L<EVP_PKEY_fromdata(3)/Selections>.
 115 Additionally I<selection> can also be set to B<0> to indicate that the code will
 116 auto detect the selection.
 117
 118 =head1 RETURN VALUES
 119
 120 OSSL_DECODER_CTX_new_for_pkey() returns a pointer to a
 121 B<OSSL_DECODER_CTX>, or NULL if it couldn't be created.
 122
 123 OSSL_DECODER_CTX_set_passphrase(), OSSL_DECODER_CTX_set_pem_password_cb(),
 124 OSSL_DECODER_CTX_set_passphrase_ui() and
 125 OSSL_DECODER_CTX_set_passphrase_cb() all return 1 on success, or 0 on
 126 failure.
 127
 128 =head1 SEE ALSO
 129
 130 L<provider(7)>, L<OSSL_DECODER(3)>, L<OSSL_DECODER_CTX(3)>
 131
 132 =head1 HISTORY
 133
 134 The functions described here were added in OpenSSL 3.0.
 135
 136 =head1 COPYRIGHT
 137
 138 Copyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved.
 139
 140 Licensed under the Apache License 2.0 (the "License").  You may not use
 141 this file except in compliance with the License.  You can obtain a copy
 142 in the file LICENSE in the source distribution or at
 143 L<https://www.openssl.org/source/license.html>.
 144
 145 =cut