doc/man3/OSSL_DECODER_CTX_new_by_EVP_PKEY.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 OSSL_DECODER_CTX_new_by_EVP_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_by_EVP_PKEY(const EVP_PKEY *pkey,
  18                                   const char *input_type, const char *keytype,
  19                                   OPENSSL_CTX *libctx, const char *propquery);
  20
  21  int OSSL_DECODER_CTX_set_passphrase(OSSL_DECODER_CTX *ctx,
  22                                      const unsigned char *kstr,
  23                                      size_t klen);
  24  int OSSL_DECODER_CTX_set_pem_password_cb(OSSL_DECODER_CTX *ctx,
  25                                           pem_password_cb *cb,
  26                                           void *cbarg);
  27  int OSSL_DECODER_CTX_set_passphrase_ui(OSSL_DECODER_CTX *ctx,
  28                                         const UI_METHOD *ui_method,
  29                                         void *ui_data);
  30  int OSSL_DECODER_CTX_set_passphrase_cb(OSSL_DECODER_CTX *ctx,
  31                                         OSSL_PASSPHRASE_CALLBACK *cb,
  32                                         void *cbarg);
  33
  34 =head1 DESCRIPTION
  35
  36 OSSL_DECODER_CTX_new_by_EVP_PKEY() is a utility function that creates a
  37 B<OSSL_DECODER_CTX>, finds all applicable decoder implementations and sets
  38 them up, so all the caller has to do next is call functions like
  39 OSSL_DECODE_from_bio().
  40
  41 Internally OSSL_DECODER_CTX_new_by_EVP_PKEY() searches for all available
  42 L<EVP_KEYMGMT(3)> implementations, and then builds a list of all potential
  43 decoder implementations that may be able to process the encoded input into
  44 data suitable for B<EVP_PKEY>s.  All these implementations are implicitly
  45 fetched using I<libctx> and I<propquery>.
  46
  47 The search of decoder implementations can be limited with I<input_type>,
  48 which specifies a starting input type.  NULL is valid input and signifies
  49 that the decoder implementations will find out the input type on their own.
  50 This is further explained in L<OSSL_DECODER_CTX_set_input_type(3)>.
  51
  52 The search of decoder implementations can also be limited with I<keytype>,
  53 which specifies the expected resulting keytype.  NULL is valid input and
  54 signifies that the decoder implementations will find out the keytype on
  55 their own from the input they get.
  56
  57 If no suitable decoder implementation is found,
  58 OSSL_DECODER_CTX_new_by_EVP_PKEY() still creates a B<OSSL_DECODER_CTX>, but
  59 with no associated decoder (L<OSSL_DECODER_CTX_get_num_decoders(3)> returns
  60 zero).  This helps the caller to distinguish between an error when creating
  61 the B<OSSL_ENCODER_CTX> and missing encoder implementation, and allows it to
  62 act accordingly.
  63
  64 OSSL_DECODER_CTX_set_passphrase() gives the implementation a pass phrase to
  65 use when decrypting the encoded private key. Alternatively, a pass phrase
  66 callback may be specified with the following functions.
  67
  68 OSSL_DECODER_CTX_set_pem_password_cb(), OSSL_DECODER_CTX_set_passphrase_ui()
  69 and OSSL_DECODER_CTX_set_passphrase_cb() set up a callback method that the
  70 implementation can use to prompt for a pass phrase, giving the caller the
  71 choice of prefered pass phrase callback form.  These are called indirectly,
  72 through an internal B<OSSL_PASSPHRASE_CALLBACK> function.
  73
  74 The internal B<OSSL_PASSPHRASE_CALLBACK> function caches the pass phrase, to
  75 be re-used in all decodings that are performed in the same decoding run (for
  76 example, within one L<OSSL_DECODER_from_bio(3)> call).
  77
  78 =head1 RETURN VALUES
  79
  80 OSSL_DECODER_CTX_new_by_EVP_PKEY() returns a pointer to a
  81 B<OSSL_DECODER_CTX>, or NULL if it couldn't be created.
  82
  83 OSSL_DECODER_CTX_set_passphrase(), OSSL_DECODER_CTX_set_pem_password_cb(),
  84 OSSL_DECODER_CTX_set_passphrase_ui() and
  85 OSSL_DECODER_CTX_set_passphrase_cb() all return 1 on success, or 0 on
  86 failure.
  87
  88 =head1 NOTES
  89
  90 Parts of the function names are made to match already existing OpenSSL
  91 names.
  92
  93 B<EVP_PKEY> in OSSL_DECODER_CTX_new_by_EVP_PKEY() matches the type name,
  94 thus making for the naming pattern B<OSSL_DECODER_CTX_new_by_I<TYPE>>() when
  95 new types are handled.
  96
  97 =head1 SEE ALSO
  98
  99 L<provider(7)>, L<OSSL_DECODER(3)>, L<OSSL_DECODER_CTX(3)>
 100
 101 =head1 HISTORY
 102
 103 The functions described here were added in OpenSSL 3.0.
 104
 105 =head1 COPYRIGHT
 106
 107 Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
 108
 109 Licensed under the Apache License 2.0 (the "License").  You may not use
 110 this file except in compliance with the License.  You can obtain a copy
 111 in the file LICENSE in the source distribution or at
 112 L<https://www.openssl.org/source/license.html>.
 113
 114 =cut