=pod

=head1 NAME

OSSL_DESERIALIZER_CTX_new_by_EVP_PKEY,
OSSL_DESERIALIZER_CTX_set_passphrase,
OSSL_DESERIALIZER_CTX_set_pem_password_cb,
OSSL_DESERIALIZER_CTX_set_passphrase_ui
- Deserializer routines to deserialize EVP_PKEYs

=head1 SYNOPSIS

 #include <openssl/deserializer.h>

 OSSL_DESERIALIZER_CTX *
 OSSL_DESERIALIZER_CTX_new_by_EVP_PKEY(const EVP_PKEY *pkey,
                                       const char *input_type,
                                       OPENSSL_CTX *libctx,
                                       const char *propquery);

 int OSSL_DESERIALIZER_CTX_set_passphrase(OSSL_DESERIALIZER_CTX *ctx,
                                          const unsigned char *kstr,
                                          size_t klen);
 int OSSL_DESERIALIZER_CTX_set_pem_password_cb(OSSL_DESERIALIZER_CTX *ctx,
                                               pem_password_cb *cb,
                                               void *cbarg);
 int OSSL_DESERIALIZER_CTX_set_passphrase_ui(OSSL_DESERIALIZER_CTX *ctx,
                                             const UI_METHOD *ui_method,
                                             void *ui_data);

=head1 DESCRIPTION

OSSL_DESERIALIZER_CTX_new_by_EVP_PKEY() is a utility function that
creates a B<OSSL_DESERIALIZER_CTX>, finds all applicable deserializer
implementations and sets them up, so all the caller has to do next is
call functions like OSSL_DESERIALIZE_from_bio().

Internally OSSL_DESERIALIZER_CTX_new_by_EVP_PKEY() searches for all
available L<EVP_KEYMGMT(3)> implementations, and then builds a list of all
potential deserializer implementations that may be able to process the
serialized input into data suitable for B<EVP_PKEY>s.  All these
implementations are implicitly fetched using I<libctx> and I<propquery>.

The search of deserializer implementations can be limited with
I<input_type>, which specifies a starting input type.  This is further
explained in L<OSSL_DESERIALIZER_CTX_set_input_type(3)>.

If no suitable deserializer was found, OSSL_DESERIALIZER_CTX_new_by_EVP_PKEY()
still creates a B<OSSL_DESERIALIZER_CTX>, but with no associated
deserializer (L<OSSL_DESERIALIZER_CTX_num_deserializers(3)> returns
zero).  This helps the caller distinguish between an error when
creating the B<OSSL_DESERIALIZER_CTX>, and the lack the deserializer
support and act accordingly.

OSSL_DESERIALIZER_CTX_set_passphrase() gives the implementation a
pass phrase to use when decrypting the serialized private key.
Alternatively, a pass phrase callback may be specified with the
following functions.

OSSL_DESERIALIZER_CTX_set_pem_password_cb() and
OSSL_DESERIALIZER_CTX_set_passphrase_ui() set up a callback method that
the implementation can use to prompt for a pass phrase, giving the caller
the choice of prefered pass phrase callback form.  These are called
indirectly, through an internal B<OSSL_PASSPHRASE_CALLBACK> function.

The internal B<OSSL_PASSPHRASE_CALLBACK> function caches the pass phrase, to
be re-used in all deserializations that are performed in the same
deserialization run
(for example, within one L<OSSL_DESERIALIZER_from_bio(3)> call).

=for comment the name OSSL_DESERIALIZER_CTX_set_pem_password_cb() leaves
open the future possibility of having a function where the caller can set a
B<OSSL_PASSPHRASE_CALLBACK> method as another option.

=head1 RETURN VALUES

OSSL_DESERIALIZER_CTX_new_by_EVP_PKEY() returns a pointer to a
B<OSSL_DESERIALIZER_CTX>, or NULL if it couldn't be created.

OSSL_DESERIALIZER_CTX_set_passphrase(),
OSSL_DESERIALIZER_CTX_set_pem_password_cb() and
OSSL_DESERIALIZER_CTX_set_passphrase_ui()
all return 1 on success, or 0 on failure.

=head1 NOTES

Parts of the function names are made to match already existing OpenSSL
names.

B<EVP_PKEY> in OSSL_DESERIALIZER_CTX_new_by_EVP_PKEY() matches the type
name, thus making for the naming pattern
B<OSSL_DESERIALIZER_CTX_new_by_I<TYPE>>() when new types are handled.

=head1 SEE ALSO

L<provider(7)>, L<OSSL_DESERIALIZER(3)>, L<OSSL_DESERIALIZER_CTX(3)>

=head1 HISTORY

The functions described here were added in OpenSSL 3.0.

=head1 COPYRIGHT

Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the "License").  You may not use
this file except in compliance with the License.  You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.

=cut