doc/man3/OSSL_DESERIALIZER_CTX_new_by_EVP_PKEY.pod

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