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