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

=pod

=head1 NAME

OSSL_SERIALIZER_CTX_new_by_EVP_PKEY,
OSSL_SERIALIZER_CTX_set_cipher,
OSSL_SERIALIZER_CTX_set_passphrase,
OSSL_SERIALIZER_CTX_set_passphrase_cb,
OSSL_SERIALIZER_CTX_set_passphrase_ui,
OSSL_SERIALIZER_PUBKEY_TO_PEM_PQ,
OSSL_SERIALIZER_PrivateKey_TO_PEM_PQ,
OSSL_SERIALIZER_Parameters_TO_PEM_PQ,
OSSL_SERIALIZER_PUBKEY_TO_DER_PQ,
OSSL_SERIALIZER_PrivateKey_TO_DER_PQ,
OSSL_SERIALIZER_Parameters_TO_DER_PQ,
OSSL_SERIALIZER_PUBKEY_TO_TEXT_PQ,
OSSL_SERIALIZER_PrivateKey_TO_TEXT_PQ,
OSSL_SERIALIZER_Parameters_TO_TEXT_PQ
- Serializer routines to serialize EVP_PKEYs

=head1 SYNOPSIS

 #include <openssl/serializer.h>

 OSSL_SERIALIZER_CTX *OSSL_SERIALIZER_CTX_new_by_EVP_PKEY(const EVP_PKEY *pkey,
                                                          const char *propquery);

 int OSSL_SERIALIZER_CTX_set_cipher(OSSL_SERIALIZER_CTX *ctx,
                                    const char *cipher_name,
                                    const char *propquery);
 int OSSL_SERIALIZER_CTX_set_passphrase(OSSL_SERIALIZER_CTX *ctx,
                                        const unsigned char *kstr,
                                        size_t klen);
 int OSSL_SERIALIZER_CTX_set_passphrase_cb(OSSL_SERIALIZER_CTX *ctx,
                                           pem_password_cb *cb, void *cbarg);
 int OSSL_SERIALIZER_CTX_set_passphrase_ui(OSSL_SERIALIZER_CTX *ctx,
                                           const UI_METHOD *ui_method,
                                           void *ui_data);

 #define OSSL_SERIALIZER_PUBKEY_TO_PEM_PQ "format=pem,type=public"
 #define OSSL_SERIALIZER_PrivateKey_TO_PEM_PQ "format=pem,type=private"
 #define OSSL_SERIALIZER_Parameters_TO_PEM_PQ "format=pem,type=parameters"

 #define OSSL_SERIALIZER_PUBKEY_TO_DER_PQ "format=der,type=public"
 #define OSSL_SERIALIZER_PrivateKey_TO_DER_PQ "format=der,type=private"
 #define OSSL_SERIALIZER_Parameters_TO_DER_PQ "format=der,type=parameters"

 #define OSSL_SERIALIZER_PUBKEY_TO_TEXT_PQ "format=text,type=public"
 #define OSSL_SERIALIZER_PrivateKey_TO_TEXT_PQ "format=text,type=private"
 #define OSSL_SERIALIZER_Parameters_TO_TEXT_PQ "format=text,type=parameters"

=head1 DESCRIPTION

OSSL_SERIALIZER_CTX_new_by_EVP_PKEY() creates a B<OSSL_SERIALIZER_CTX>
with a suitable attached output routine for B<EVP_PKEY>s.  It will
search for a serializer implementation that matches the algorithm of
the B<EVP_PKEY> and the property query given with I<propquery>.  It
will prefer to find a serializer from the same provider as the key
data of the B<EVP_PKEY> itself, but failing that, it will choose the
first serializer that supplies a generic serializing function.

If no suitable serializer was found, OSSL_SERIALIZER_CTX_new_by_EVP_PKEY()
still creates a B<OSSL_SERIALIZER_CTX>, but with no associated
serializer (L<OSSL_SERIALIZER_CTX_get_serializer(3)> returns NULL).
This helps the caller distinguish between an error when creating
the B<OSSL_SERIALIZER_CTX>, and the lack the serializer support and
act accordingly.

OSSL_SERIALIZER_CTX_set_cipher() tells the implementation what cipher
should be used to encrypt serialized keys.  The cipher is given by
name I<cipher_name>.  The interpretation of that I<cipher_name> is
implementation dependent.  The implementation may implement the digest
directly itself or by other implementations, or it may choose to fetch
it.  If the implementation supports fetching the cipher, then it may
use I<propquery> as properties to be queried for when fetching.
I<cipher_name> may also be NULL, which will result in unencrypted
serialization.

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

OSSL_SERIALIZER_CTX_set_passphrase_cb() and
OSSL_SERIALIZER_CTX_set_passphrase_ui() sets up a callback method that
the implementation can use to prompt for a pass phrase.

=for comment Note that the callback method is called indirectly,
through an internal B<OSSL_PASSPHRASE_CALLBACK> function.

The macros B<OSSL_SERIALIZER_PUBKEY_TO_PEM_PQ>,
B<OSSL_SERIALIZER_PrivateKey_TO_PEM_PQ>,
B<OSSL_SERIALIZER_Parameters_TO_PEM_PQ>,
B<OSSL_SERIALIZER_PUBKEY_TO_DER_PQ>,
B<OSSL_SERIALIZER_PrivateKey_TO_DER_PQ>,
B<OSSL_SERIALIZER_Parameters_TO_DER_PQ>,
B<OSSL_SERIALIZER_PUBKEY_TO_TEXT_PQ>,
B<OSSL_SERIALIZER_PrivateKey_TO_TEXT_PQ>,
B<OSSL_SERIALIZER_Parameters_TO_TEXT_PQ> are convenience macros with
property queries to serialize the B<EVP_PKEY> as a public key, private
key or parameters to B<PEM>, to B<DER>, or to text.

=head1 RETURN VALUES

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

OSSL_SERIALIZER_CTX_set_cipher(),
OSSL_SERIALIZER_CTX_set_passphrase(),
OSSL_SERIALIZER_CTX_set_passphrase_cb(), and
OSSL_SERIALIZER_CTX_set_passphrase_ui() all return 1 on success, or 0
on failure.

=head1 NOTES

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

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

B<PUBKEY>, B<PrivateKey> and B<Parameters> in the macro names match
the B<I<TYPE>> part of B<PEM_write_bio_I<TYPE>> functions as well
as B<i2d_I<TYPE>_bio> functions.

=head1 SEE ALSO

L<provider(7)>, L<OSSL_SERIALIZER(3)>, L<OSSL_SERIALIZER_CTX(3)>

=head1 HISTORY

The functions described here were added in OpenSSL 3.0.

=head1 COPYRIGHT

Copyright 2019-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
Commit	Line	Data
866234ac RL	1	=pod
	2
	3	=head1 NAME
	4
	5	OSSL_SERIALIZER_CTX_new_by_EVP_PKEY,
	6	OSSL_SERIALIZER_CTX_set_cipher,
	7	OSSL_SERIALIZER_CTX_set_passphrase,
	8	OSSL_SERIALIZER_CTX_set_passphrase_cb,
	9	OSSL_SERIALIZER_CTX_set_passphrase_ui,
	10	OSSL_SERIALIZER_PUBKEY_TO_PEM_PQ,
	11	OSSL_SERIALIZER_PrivateKey_TO_PEM_PQ,
	12	OSSL_SERIALIZER_Parameters_TO_PEM_PQ,
9ea59241 RL	13	OSSL_SERIALIZER_PUBKEY_TO_DER_PQ,
	14	OSSL_SERIALIZER_PrivateKey_TO_DER_PQ,
	15	OSSL_SERIALIZER_Parameters_TO_DER_PQ,
866234ac RL	16	OSSL_SERIALIZER_PUBKEY_TO_TEXT_PQ,
	17	OSSL_SERIALIZER_PrivateKey_TO_TEXT_PQ,
	18	OSSL_SERIALIZER_Parameters_TO_TEXT_PQ
	19	- Serializer routines to serialize EVP_PKEYs
	20
	21	=head1 SYNOPSIS
	22
	23	#include <openssl/serializer.h>
	24
	25	OSSL_SERIALIZER_CTX OSSL_SERIALIZER_CTX_new_by_EVP_PKEY(const EVP_PKEY pkey,
	26	const char *propquery);
	27
	28	int OSSL_SERIALIZER_CTX_set_cipher(OSSL_SERIALIZER_CTX *ctx,
	29	const char *cipher_name,
	30	const char *propquery);
	31	int OSSL_SERIALIZER_CTX_set_passphrase(OSSL_SERIALIZER_CTX *ctx,
	32	const unsigned char *kstr,
	33	size_t klen);
45396db0	34	int OSSL_SERIALIZER_CTX_set_passphrase_cb(OSSL_SERIALIZER_CTX *ctx,
866234ac RL	35	pem_password_cb cb, void cbarg);
	36	int OSSL_SERIALIZER_CTX_set_passphrase_ui(OSSL_SERIALIZER_CTX *ctx,
	37	const UI_METHOD *ui_method,
	38	void *ui_data);
	39
	40	#define OSSL_SERIALIZER_PUBKEY_TO_PEM_PQ "format=pem,type=public"
	41	#define OSSL_SERIALIZER_PrivateKey_TO_PEM_PQ "format=pem,type=private"
b305452f	42	#define OSSL_SERIALIZER_Parameters_TO_PEM_PQ "format=pem,type=parameters"
866234ac	43
9ea59241 RL	44	#define OSSL_SERIALIZER_PUBKEY_TO_DER_PQ "format=der,type=public"
	45	#define OSSL_SERIALIZER_PrivateKey_TO_DER_PQ "format=der,type=private"
	46	#define OSSL_SERIALIZER_Parameters_TO_DER_PQ "format=der,type=parameters"
	47
866234ac RL	48	#define OSSL_SERIALIZER_PUBKEY_TO_TEXT_PQ "format=text,type=public"
866234ac RL	49	#define OSSL_SERIALIZER_PrivateKey_TO_TEXT_PQ "format=text,type=private"
b305452f	50	#define OSSL_SERIALIZER_Parameters_TO_TEXT_PQ "format=text,type=parameters"
866234ac RL	51
	52	=head1 DESCRIPTION
	53
	54	OSSL_SERIALIZER_CTX_new_by_EVP_PKEY() creates a B<OSSL_SERIALIZER_CTX>
	55	with a suitable attached output routine for B<EVP_PKEY>s. It will
	56	search for a serializer implementation that matches the algorithm of
	57	the B<EVP_PKEY> and the property query given with I<propquery>. It
	58	will prefer to find a serializer from the same provider as the key
	59	data of the B<EVP_PKEY> itself, but failing that, it will choose the
	60	first serializer that supplies a generic serializing function.
	61
	62	If no suitable serializer was found, OSSL_SERIALIZER_CTX_new_by_EVP_PKEY()
	63	still creates a B<OSSL_SERIALIZER_CTX>, but with no associated
	64	serializer (L<OSSL_SERIALIZER_CTX_get_serializer(3)> returns NULL).
	65	This helps the caller distinguish between an error when creating
	66	the B<OSSL_SERIALIZER_CTX>, and the lack the serializer support and
	67	act accordingly.
	68
	69	OSSL_SERIALIZER_CTX_set_cipher() tells the implementation what cipher
	70	should be used to encrypt serialized keys. The cipher is given by
	71	name I<cipher_name>. The interpretation of that I<cipher_name> is
	72	implementation dependent. The implementation may implement the digest
	73	directly itself or by other implementations, or it may choose to fetch
	74	it. If the implementation supports fetching the cipher, then it may
	75	use I<propquery> as properties to be queried for when fetching.
	76	I<cipher_name> may also be NULL, which will result in unencrypted
	77	serialization.
	78
	79	OSSL_SERIALIZER_CTX_set_passphrase() gives the implementation a
	80	pass phrase to use when encrypting the serialized private key.
	81	Alternatively, a pass phrase callback may be specified with the
	82	following functions.
	83
	84	OSSL_SERIALIZER_CTX_set_passphrase_cb() and
	85	OSSL_SERIALIZER_CTX_set_passphrase_ui() sets up a callback method that
	86	the implementation can use to prompt for a pass phrase.
	87
	88	=for comment Note that the callback method is called indirectly,
	89	through an internal B<OSSL_PASSPHRASE_CALLBACK> function.
	90
	91	The macros B<OSSL_SERIALIZER_PUBKEY_TO_PEM_PQ>,
	92	B<OSSL_SERIALIZER_PrivateKey_TO_PEM_PQ>,
	93	B<OSSL_SERIALIZER_Parameters_TO_PEM_PQ>,
9ea59241 RL	94	B<OSSL_SERIALIZER_PUBKEY_TO_DER_PQ>,
	95	B<OSSL_SERIALIZER_PrivateKey_TO_DER_PQ>,
	96	B<OSSL_SERIALIZER_Parameters_TO_DER_PQ>,
866234ac RL	97	B<OSSL_SERIALIZER_PUBKEY_TO_TEXT_PQ>,
	98	B<OSSL_SERIALIZER_PrivateKey_TO_TEXT_PQ>,
	99	B<OSSL_SERIALIZER_Parameters_TO_TEXT_PQ> are convenience macros with
	100	property queries to serialize the B<EVP_PKEY> as a public key, private
9ea59241	101	key or parameters to B<PEM>, to B<DER>, or to text.
866234ac RL	102
	103	=head1 RETURN VALUES
	104
	105	OSSL_SERIALIZER_CTX_new_by_EVP_PKEY() returns a pointer to a
	106	B<OSSL_SERIALIZER_CTX>, or NULL if it couldn't be created.
	107
	108	OSSL_SERIALIZER_CTX_set_cipher(),
	109	OSSL_SERIALIZER_CTX_set_passphrase(),
	110	OSSL_SERIALIZER_CTX_set_passphrase_cb(), and
	111	OSSL_SERIALIZER_CTX_set_passphrase_ui() all return 1 on success, or 0
	112	on failure.
	113
	114	=head1 NOTES
	115
	116	Parts of the function and macro names are made to match already
	117	existing OpenSSL names.
	118
	119	B<EVP_PKEY> in OSSL_SERIALIZER_CTX_new_by_EVP_PKEY() matches the type
	120	name, thus making for the naming pattern
	121	B<OSSL_SERIALIZER_CTX_new_by_I<TYPE>>() when new types are handled.
	122
	123	B<PUBKEY>, B<PrivateKey> and B<Parameters> in the macro names match
8c1cbc72	124	the B<I<TYPE>> part of B<PEM_write_bio_I<TYPE>> functions as well
866234ac RL	125	as B<i2d_I<TYPE>_bio> functions.
	126
	127	=head1 SEE ALSO
	128
	129	L<provider(7)>, L<OSSL_SERIALIZER(3)>, L<OSSL_SERIALIZER_CTX(3)>
	130
	131	=head1 HISTORY
	132
	133	The functions described here were added in OpenSSL 3.0.
	134
	135	=head1 COPYRIGHT
	136
33388b44	137	Copyright 2019-2020 The OpenSSL Project Authors. All Rights Reserved.
866234ac RL	138
	139	Licensed under the Apache License 2.0 (the "License"). You may not use
	140	this file except in compliance with the License. You can obtain a copy
	141	in the file LICENSE in the source distribution or at
	142	L<https://www.openssl.org/source/license.html>.
	143
	144	=cut