[thirdparty/openssl.git] / doc / man3 / OSSL_DECODER_CTX_new_for_pkey.pod

=pod

=head1 NAME

OSSL_DECODER_CTX_new_for_pkey,
OSSL_DECODER_CTX_set_passphrase,
OSSL_DECODER_CTX_set_pem_password_cb,
OSSL_DECODER_CTX_set_passphrase_ui,
OSSL_DECODER_CTX_set_passphrase_cb
- Decoder routines to decode EVP_PKEYs

=head1 SYNOPSIS

 #include <openssl/decoder.h>

 OSSL_DECODER_CTX *
 OSSL_DECODER_CTX_new_for_pkey(EVP_PKEY **pkey,
                               const char *input_type,
                               const char *input_struct,
                               const char *keytype, int selection,
                               OSSL_LIB_CTX *libctx, const char *propquery);

 int OSSL_DECODER_CTX_set_passphrase(OSSL_DECODER_CTX *ctx,
                                     const unsigned char *kstr,
                                     size_t klen);
 int OSSL_DECODER_CTX_set_pem_password_cb(OSSL_DECODER_CTX *ctx,
                                          pem_password_cb *cb,
                                          void *cbarg);
 int OSSL_DECODER_CTX_set_passphrase_ui(OSSL_DECODER_CTX *ctx,
                                        const UI_METHOD *ui_method,
                                        void *ui_data);
 int OSSL_DECODER_CTX_set_passphrase_cb(OSSL_DECODER_CTX *ctx,
                                        OSSL_PASSPHRASE_CALLBACK *cb,
                                        void *cbarg);

=head1 DESCRIPTION

OSSL_DECODER_CTX_new_for_pkey() is a utility function that creates a
B<OSSL_DECODER_CTX>, finds all applicable decoder implementations and sets
them up, so all the caller has to do next is call functions like
L<OSSL_DECODER_from_bio(3)>.  The caller may use the optional I<input_type>,
I<input_struct>, I<keytype> and I<selection> to specify what the input is
expected to contain.  The I<pkey> must reference an B<EVP_PKEY *> variable
that will be set to the newly created B<EVP_PKEY> on successful decoding.
The referenced variable must be initialized to NULL before calling the
function.

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

The search of decoder implementations can be limited with I<input_type> and
I<input_struct> which specifies a starting input type and input structure.
NULL is valid for both of them and signifies that the decoder implementations
will find out the input type on their own.
They are set with L<OSSL_DECODER_CTX_set_input_type(3)> and
L<OSSL_DECODER_CTX_set_input_structure(3)>.
See L</Input Types> and L</Input Structures> below for further information.

The search of decoder implementations can also be limited with I<keytype>
and I<selection>, which specifies the expected resulting keytype and contents.
NULL and zero are valid and signify that the decoder implementations will
find out the keytype and key contents on their own from the input they get.

If no suitable decoder implementation is found,
OSSL_DECODER_CTX_new_for_pkey() still creates a B<OSSL_DECODER_CTX>, but
with no associated decoder (L<OSSL_DECODER_CTX_get_num_decoders(3)> returns
zero).  This helps the caller to distinguish between an error when creating
the B<OSSL_ENCODER_CTX> and missing encoder implementation, and allows it to
act accordingly.

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

OSSL_DECODER_CTX_set_pem_password_cb(), OSSL_DECODER_CTX_set_passphrase_ui()
and OSSL_DECODER_CTX_set_passphrase_cb() set up a callback method that the
implementation can use to prompt for a pass phrase, giving the caller the
choice of preferred 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 decodings that are performed in the same decoding run (for
example, within one L<OSSL_DECODER_from_bio(3)> call).

=head2 Input Types

Available input types depend on the implementations that available providers
offer, and provider documentation should have the details.

Among the known input types that OpenSSL decoder implementations offer
for B<EVP_PKEY>s are C<DER>, C<PEM>, C<MSBLOB> and C<PVK>.
See L<openssl-glossary(7)> for further information on what these input
types mean.

=head2 Input Structures

Available input structures depend on the implementations that available
providers offer, and provider documentation should have the details.

Among the known input structures that OpenSSL decoder implementations
offer for B<EVP_PKEY>s are C<pkcs8> and C<SubjectPublicKeyInfo>.

OpenSSL decoder implementations also support the input structure
C<type-specific>.  This is the structure used for keys encoded
according to key type specific specifications.  For example, RSA keys
encoded according to PKCS#1.

=head2 Selections

I<selection> can be any one of the values described in
L<EVP_PKEY_fromdata(3)/Selections>.
Additionally I<selection> can also be set to B<0> to indicate that the code will
auto detect the selection.

=head1 RETURN VALUES

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

OSSL_DECODER_CTX_set_passphrase(), OSSL_DECODER_CTX_set_pem_password_cb(),
OSSL_DECODER_CTX_set_passphrase_ui() and
OSSL_DECODER_CTX_set_passphrase_cb() all return 1 on success, or 0 on
failure.

=head1 SEE ALSO

L<provider(7)>, L<OSSL_DECODER(3)>, L<OSSL_DECODER_CTX(3)>

=head1 HISTORY

The functions described here were added in OpenSSL 3.0.

=head1 COPYRIGHT

Copyright 2020-2022 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
Commit	Line	Data
ece9304c RL	1	=pod
	2
	3	=head1 NAME
	4
fe75766c	5	OSSL_DECODER_CTX_new_for_pkey,
ece9304c RL	6	OSSL_DECODER_CTX_set_passphrase,
ece9304c RL	7	OSSL_DECODER_CTX_set_pem_password_cb,
4fd39782 RL	8	OSSL_DECODER_CTX_set_passphrase_ui,
4fd39782 RL	9	OSSL_DECODER_CTX_set_passphrase_cb
ece9304c RL	10	- Decoder routines to decode EVP_PKEYs
	11
	12	=head1 SYNOPSIS
	13
	14	#include <openssl/decoder.h>
	15
	16	OSSL_DECODER_CTX *
fe75766c TM	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);
ece9304c RL	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);
4fd39782 RL	32	int OSSL_DECODER_CTX_set_passphrase_cb(OSSL_DECODER_CTX *ctx,
	33	OSSL_PASSPHRASE_CALLBACK *cb,
	34	void *cbarg);
ece9304c RL	35
	36	=head1 DESCRIPTION
	37
fe75766c	38	OSSL_DECODER_CTX_new_for_pkey() is a utility function that creates a
48b62fb3 RL	39	B<OSSL_DECODER_CTX>, finds all applicable decoder implementations and sets
48b62fb3 RL	40	them up, so all the caller has to do next is call functions like
19ad83f6 RL	41	L<OSSL_DECODER_from_bio(3)>. The caller may use the optional I<input_type>,
19ad83f6 RL	42	I<input_struct>, I<keytype> and I<selection> to specify what the input is
fe75766c	43	expected to contain. The I<pkey> must reference an B<EVP_PKEY *> variable
e304aa87	44	that will be set to the newly created B<EVP_PKEY> on successful decoding.
fe75766c TM	45	The referenced variable must be initialized to NULL before calling the
fe75766c TM	46	function.
48b62fb3	47
fe75766c	48	Internally OSSL_DECODER_CTX_new_for_pkey() searches for all available
48b62fb3 RL	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
19ad83f6 RL	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.
70c06aaf	61
19ad83f6 RL	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.
48b62fb3 RL	66
48b62fb3 RL	67	If no suitable decoder implementation is found,
fe75766c	68	OSSL_DECODER_CTX_new_for_pkey() still creates a B<OSSL_DECODER_CTX>, but
48b62fb3 RL	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
e304aa87	81	choice of preferred pass phrase callback form. These are called indirectly,
48b62fb3 RL	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).
ece9304c	87
19ad83f6 RL	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
00b8706c SL	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
ece9304c RL	118	=head1 RETURN VALUES
ece9304c RL	119
fe75766c	120	OSSL_DECODER_CTX_new_for_pkey() returns a pointer to a
ece9304c RL	121	B<OSSL_DECODER_CTX>, or NULL if it couldn't be created.
ece9304c RL	122
48b62fb3	123	OSSL_DECODER_CTX_set_passphrase(), OSSL_DECODER_CTX_set_pem_password_cb(),
4fd39782	124	OSSL_DECODER_CTX_set_passphrase_ui() and
48b62fb3 RL	125	OSSL_DECODER_CTX_set_passphrase_cb() all return 1 on success, or 0 on
48b62fb3 RL	126	failure.
ece9304c	127
ece9304c RL	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
fecb3aae	138	Copyright 2020-2022 The OpenSSL Project Authors. All Rights Reserved.
ece9304c RL	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