[thirdparty/openssl.git] / doc / man7 / provider-asym_cipher.pod

=pod

=head1 NAME

provider-asym_cipher - The asym_cipher library E<lt>-E<gt> provider functions

=head1 SYNOPSIS

=for openssl multiple includes

 #include <openssl/core_dispatch.h>
 #include <openssl/core_names.h>

 /*
  * None of these are actual functions, but are displayed like this for
  * the function signatures for functions that are offered as function
  * pointers in OSSL_DISPATCH arrays.
  */

 /* Context management */
 void *OSSL_FUNC_asym_cipher_newctx(void *provctx);
 void OSSL_FUNC_asym_cipher_freectx(void *ctx);
 void *OSSL_FUNC_asym_cipher_dupctx(void *ctx);

 /* Encryption */
 int OSSL_FUNC_asym_cipher_encrypt_init(void *ctx, void *provkey);
 int OSSL_FUNC_asym_cipher_encrypt(void *ctx, unsigned char *out, size_t *outlen,
                                   size_t outsize, const unsigned char *in,
                                   size_t inlen);

 /* Decryption */
 int OSSL_FUNC_asym_cipher_decrypt_init(void *ctx, void *provkey);
 int OSSL_FUNC_asym_cipher_decrypt(void *ctx, unsigned char *out, size_t *outlen,
                                   size_t outsize, const unsigned char *in,
                                   size_t inlen);

 /* Asymmetric Cipher parameters */
 int OSSL_FUNC_asym_cipher_get_ctx_params(void *ctx, OSSL_PARAM params[]);
 const OSSL_PARAM *OSSL_FUNC_asym_cipher_gettable_ctx_params(void);
 int OSSL_FUNC_asym_cipher_set_ctx_params(void *ctx, const OSSL_PARAM params[]);
 const OSSL_PARAM *OSSL_FUNC_asym_cipher_settable_ctx_params(void);

=head1 DESCRIPTION

This documentation is primarily aimed at provider authors. See L<provider(7)>
for further information.

The asymmetric cipher (OSSL_OP_ASYM_CIPHER) operation enables providers to
implement asymmetric cipher algorithms and make them available to applications
via the API functions L<EVP_PKEY_encrypt(3)>,
L<EVP_PKEY_decrypt(3)> and
other related functions).

All "functions" mentioned here are passed as function pointers between
F<libcrypto> and the provider in B<OSSL_DISPATCH> arrays via
B<OSSL_ALGORITHM> arrays that are returned by the provider's
provider_query_operation() function
(see L<provider-base(7)/Provider Functions>).

All these "functions" have a corresponding function type definition
named B<OSSL_{name}_fn>, and a helper function to retrieve the
function pointer from an B<OSSL_DISPATCH> element named
B<OSSL_FUNC_{name}>.
For example, the "function" OSSL_FUNC_asym_cipher_newctx() has these:

 typedef void *(OSSL_FUNC_asym_cipher_newctx_fn)(void *provctx);
 static ossl_inline OSSL_FUNC_asym_cipher_newctx_fn
     OSSL_FUNC_asym_cipher_newctx(const OSSL_DISPATCH *opf);

B<OSSL_DISPATCH> arrays are indexed by numbers that are provided as
macros in L<openssl-core_dispatch.h(7)>, as follows:

 OSSL_FUNC_asym_cipher_newctx               OSSL_FUNC_ASYM_CIPHER_NEWCTX
 OSSL_FUNC_asym_cipher_freectx              OSSL_FUNC_ASYM_CIPHER_FREECTX
 OSSL_FUNC_asym_cipher_dupctx               OSSL_FUNC_ASYM_CIPHER_DUPCTX

 OSSL_FUNC_asym_cipher_encrypt_init         OSSL_FUNC_ASYM_CIPHER_ENCRYPT_INIT
 OSSL_FUNC_asym_cipher_encrypt              OSSL_FUNC_ASYM_CIPHER_ENCRYPT

 OSSL_FUNC_asym_cipher_decrypt_init         OSSL_FUNC_ASYM_CIPHER_DECRYPT_INIT
 OSSL_FUNC_asym_cipher_decrypt              OSSL_FUNC_ASYM_CIPHER_DECRYPT

 OSSL_FUNC_asym_cipher_get_ctx_params       OSSL_FUNC_ASYM_CIPHER_GET_CTX_PARAMS
 OSSL_FUNC_asym_cipher_gettable_ctx_params  OSSL_FUNC_ASYM_CIPHER_GETTABLE_CTX_PARAMS
 OSSL_FUNC_asym_cipher_set_ctx_params       OSSL_FUNC_ASYM_CIPHER_SET_CTX_PARAMS
 OSSL_FUNC_asym_cipher_settable_ctx_params  OSSL_FUNC_ASYM_CIPHER_SETTABLE_CTX_PARAMS

An asymmetric cipher algorithm implementation may not implement all of these
functions.
In order to be a consistent set of functions a provider must implement
OSSL_FUNC_asym_cipher_newctx and OSSL_FUNC_asym_cipher_freectx.
It must also implement both of OSSL_FUNC_asym_cipher_encrypt_init and
OSSL_FUNC_asym_cipher_encrypt, or both of OSSL_FUNC_asym_cipher_decrypt_init and
OSSL_FUNC_asym_cipher_decrypt.
OSSL_FUNC_asym_cipher_get_ctx_params is optional but if it is present then so must
OSSL_FUNC_asym_cipher_gettable_ctx_params.
Similarly, OSSL_FUNC_asym_cipher_set_ctx_params is optional but if it is present then
so must OSSL_FUNC_asym_cipher_settable_ctx_params.

An asymmetric cipher algorithm must also implement some mechanism for generating,
loading or importing keys via the key management (OSSL_OP_KEYMGMT) operation.
See L<provider-keymgmt(7)> for further details.

=head2 Context Management Functions

OSSL_FUNC_asym_cipher_newctx() should create and return a pointer to a provider side
structure for holding context information during an asymmetric cipher operation.
A pointer to this context will be passed back in a number of the other
asymmetric cipher operation function calls.
The parameter I<provctx> is the provider context generated during provider
initialisation (see L<provider(7)>).

OSSL_FUNC_asym_cipher_freectx() is passed a pointer to the provider side asymmetric
cipher context in the I<ctx> parameter.
This function should free any resources associated with that context.

OSSL_FUNC_asym_cipher_dupctx() should duplicate the provider side asymmetric cipher
context in the I<ctx> parameter and return the duplicate copy.

=head2 Encryption Functions

OSSL_FUNC_asym_cipher_encrypt_init() initialises a context for an asymmetric encryption
given a provider side asymmetric cipher context in the I<ctx> parameter, and a
pointer to a provider key object in the I<provkey> parameter.
The key object should have been previously generated, loaded or imported into
the provider using the key management (OSSL_OP_KEYMGMT) operation (see
provider-keymgmt(7)>.

OSSL_FUNC_asym_cipher_encrypt() performs the actual encryption itself.
A previously initialised asymmetric cipher context is passed in the I<ctx>
parameter.
The data to be encrypted is pointed to by the I<in> parameter which is I<inlen>
bytes long.
Unless I<out> is NULL, the encrypted data should be written to the location
pointed to by the I<out> parameter and it should not exceed I<outsize> bytes in
length.
The length of the encrypted data should be written to I<*outlen>.
If I<out> is NULL then the maximum length of the encrypted data should be
written to I<*outlen>.

=head2 Decryption Functions

OSSL_FUNC_asym_cipher_decrypt_init() initialises a context for an asymmetric decryption
given a provider side asymmetric cipher context in the I<ctx> parameter, and a
pointer to a provider key object in the I<provkey> parameter.
The key object should have been previously generated, loaded or imported into
the provider using the key management (OSSL_OP_KEYMGMT) operation (see
provider-keymgmt(7)>.

OSSL_FUNC_asym_cipher_decrypt() performs the actual decryption itself.
A previously initialised asymmetric cipher context is passed in the I<ctx>
parameter.
The data to be decrypted is pointed to by the I<in> parameter which is I<inlen>
bytes long.
Unless I<out> is NULL, the decrypted data should be written to the location
pointed to by the I<out> parameter and it should not exceed I<outsize> bytes in
length.
The length of the decrypted data should be written to I<*outlen>.
If I<out> is NULL then the maximum length of the decrypted data should be
written to I<*outlen>.

=head2 Asymmetric Cipher Parameters

See L<OSSL_PARAM(3)> for further details on the parameters structure used by
the OSSL_FUNC_asym_cipher_get_ctx_params() and OSSL_FUNC_asym_cipher_set_ctx_params()
functions.

OSSL_FUNC_asym_cipher_get_ctx_params() gets asymmetric cipher parameters associated
with the given provider side asymmetric cipher context I<ctx> and stores them in
I<params>.
OSSL_FUNC_asym_cipher_set_ctx_params() sets the asymmetric cipher parameters associated
with the given provider side asymmetric cipher context I<ctx> to I<params>.
Any parameter settings are additional to any that were previously set.

Parameters currently recognised by built-in asymmetric cipher algorithms are as
follows.
Not all parameters are relevant to, or are understood by all asymmetric cipher
algorithms:

=over 4

=item "pad-mode" (B<OSSL_ASYM_CIPHER_PARAM_PAD_MODE>) <integer>

The type of padding to be used. The interpretation of this value will depend
on the algorithm in use. The default provider understands these RSA padding
modes: 1 (RSA_PKCS1_PADDING), 2 (RSA_SSLV23_PADDING), 3 (RSA_NO_PADDING),
4 (RSA_PKCS1_OAEP_PADDING), 5 (RSA_X931_PADDING), 6 (RSA_PKCS1_PSS_PADDING) and
7 (RSA_PKCS1_WITH_TLS_PADDING). See L<EVP_PKEY_CTX_set_rsa_padding(3)> for
further details.

=item "digest" (B<OSSL_ASYM_CIPHER_PARAM_OAEP_DIGEST>) <UTF8 string>

Gets or sets the name of the OAEP digest algorithm used when OAEP padding is in
use.

=item "digest-props" (B<OSSL_ASYM_CIPHER_PARAM_OAEP_DIGEST_PROPS>) <UTF8 string>

Gets or sets the properties to use when fetching the OAEP digest algorithm.

=item "mgf1-digest" (B<OSSL_ASYM_CIPHER_PARAM_MGF1_DIGEST>) <UTF8 string>

Gets or sets the name of the MGF1 digest algorithm used when OAEP or PSS padding
is in use.

=item "mgf1-digest-props" (B<OSSL_ASYM_CIPHER_PARAM_MGF1_DIGEST_PROPS>) <UTF8 string>

Gets or sets the properties to use when fetching the MGF1 digest algorithm.

=item "oaep-label" (B<OSSL_ASYM_CIPHER_PARAM_OAEP_LABEL>) <octet string>

Gets or sets the OAEP label used when OAEP padding is in use.

=item "oaep-label-len" (B<OSSL_ASYM_CIPHER_PARAM_OAEP_LABEL_LEN>) <size_t>

Gets the length of an OAEP label when OAEP padding is in use.

=item "tls-client-version" (B<OSSL_ASYM_CIPHER_PARAM_TLS_CLIENT_VERSION>) <unsigned integer>

The TLS protocol version first requested by the client. See
B<RSA_PKCS1_WITH_TLS_PADDING> on the page L<EVP_PKEY_CTX_set_rsa_padding(3)>.

=item "tls-negotiated-version" (B<OSSL_ASYM_CIPHER_PARAM_TLS_CLIENT_VERSION>) <unsigned integer>

The negotiated TLS protocol version. See
B<RSA_PKCS1_WITH_TLS_PADDING> on the page L<EVP_PKEY_CTX_set_rsa_padding(3)>.

=back

OSSL_FUNC_asym_cipher_gettable_ctx_params() and OSSL_FUNC_asym_cipher_settable_ctx_params()
get a constant B<OSSL_PARAM> array that describes the gettable and settable
parameters, i.e. parameters that can be used with OSSL_FUNC_asym_cipherget_ctx_params()
and OSSL_FUNC_asym_cipher_set_ctx_params() respectively.
See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as parameter descriptor.

=head1 RETURN VALUES

OSSL_FUNC_asym_cipher_newctx() and OSSL_FUNC_asym_cipher_dupctx() should return the newly
created provider side asymmetric cipher context, or NULL on failure.

All other functions should return 1 for success or 0 on error.

=head1 SEE ALSO

L<provider(7)>

=head1 HISTORY

The provider ASYM_CIPHER interface was introduced 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
11d876df MC	1	=pod
	2
	3	=head1 NAME
	4
	5	provider-asym_cipher - The asym_cipher library E<lt>-E<gt> provider functions
	6
	7	=head1 SYNOPSIS
	8
	9	=for openssl multiple includes
	10
23c48d94	11	#include <openssl/core_dispatch.h>
11d876df MC	12	#include <openssl/core_names.h>
	13
	14	/*
	15	* None of these are actual functions, but are displayed like this for
	16	* the function signatures for functions that are offered as function
	17	* pointers in OSSL_DISPATCH arrays.
	18	*/
	19
	20	/* Context management */
363b1e5d DMSP	21	void OSSL_FUNC_asym_cipher_newctx(void provctx);
	22	void OSSL_FUNC_asym_cipher_freectx(void *ctx);
	23	void OSSL_FUNC_asym_cipher_dupctx(void ctx);
11d876df MC	24
11d876df MC	25	/* Encryption */
363b1e5d DMSP	26	int OSSL_FUNC_asym_cipher_encrypt_init(void ctx, void provkey);
	27	int OSSL_FUNC_asym_cipher_encrypt(void ctx, unsigned char out, size_t *outlen,
	28	size_t outsize, const unsigned char *in,
	29	size_t inlen);
11d876df MC	30
11d876df MC	31	/* Decryption */
363b1e5d DMSP	32	int OSSL_FUNC_asym_cipher_decrypt_init(void ctx, void provkey);
	33	int OSSL_FUNC_asym_cipher_decrypt(void ctx, unsigned char out, size_t *outlen,
	34	size_t outsize, const unsigned char *in,
	35	size_t inlen);
11d876df MC	36
11d876df MC	37	/* Asymmetric Cipher parameters */
363b1e5d DMSP	38	int OSSL_FUNC_asym_cipher_get_ctx_params(void *ctx, OSSL_PARAM params[]);
	39	const OSSL_PARAM *OSSL_FUNC_asym_cipher_gettable_ctx_params(void);
	40	int OSSL_FUNC_asym_cipher_set_ctx_params(void *ctx, const OSSL_PARAM params[]);
	41	const OSSL_PARAM *OSSL_FUNC_asym_cipher_settable_ctx_params(void);
11d876df MC	42
	43	=head1 DESCRIPTION
	44
	45	This documentation is primarily aimed at provider authors. See L<provider(7)>
	46	for further information.
	47
	48	The asymmetric cipher (OSSL_OP_ASYM_CIPHER) operation enables providers to
	49	implement asymmetric cipher algorithms and make them available to applications
fadb57e5 RS	50	via the API functions L<EVP_PKEY_encrypt(3)>,
	51	L<EVP_PKEY_decrypt(3)> and
	52	other related functions).
11d876df MC	53
	54	All "functions" mentioned here are passed as function pointers between
	55	F<libcrypto> and the provider in B<OSSL_DISPATCH> arrays via
	56	B<OSSL_ALGORITHM> arrays that are returned by the provider's
	57	provider_query_operation() function
	58	(see L<provider-base(7)/Provider Functions>).
	59
	60	All these "functions" have a corresponding function type definition
	61	named B<OSSL_{name}_fn>, and a helper function to retrieve the
	62	function pointer from an B<OSSL_DISPATCH> element named
363b1e5d DMSP	63	B<OSSL_FUNC_{name}>.
363b1e5d DMSP	64	For example, the "function" OSSL_FUNC_asym_cipher_newctx() has these:
11d876df	65
363b1e5d DMSP	66	typedef void (OSSL_FUNC_asym_cipher_newctx_fn)(void provctx);
	67	static ossl_inline OSSL_FUNC_asym_cipher_newctx_fn
	68	OSSL_FUNC_asym_cipher_newctx(const OSSL_DISPATCH *opf);
11d876df MC	69
11d876df MC	70	B<OSSL_DISPATCH> arrays are indexed by numbers that are provided as
23c48d94	71	macros in L<openssl-core_dispatch.h(7)>, as follows:
11d876df	72
363b1e5d DMSP	73	OSSL_FUNC_asym_cipher_newctx OSSL_FUNC_ASYM_CIPHER_NEWCTX
	74	OSSL_FUNC_asym_cipher_freectx OSSL_FUNC_ASYM_CIPHER_FREECTX
	75	OSSL_FUNC_asym_cipher_dupctx OSSL_FUNC_ASYM_CIPHER_DUPCTX
11d876df	76
363b1e5d DMSP	77	OSSL_FUNC_asym_cipher_encrypt_init OSSL_FUNC_ASYM_CIPHER_ENCRYPT_INIT
363b1e5d DMSP	78	OSSL_FUNC_asym_cipher_encrypt OSSL_FUNC_ASYM_CIPHER_ENCRYPT
11d876df	79
363b1e5d DMSP	80	OSSL_FUNC_asym_cipher_decrypt_init OSSL_FUNC_ASYM_CIPHER_DECRYPT_INIT
363b1e5d DMSP	81	OSSL_FUNC_asym_cipher_decrypt OSSL_FUNC_ASYM_CIPHER_DECRYPT
11d876df	82
363b1e5d DMSP	83	OSSL_FUNC_asym_cipher_get_ctx_params OSSL_FUNC_ASYM_CIPHER_GET_CTX_PARAMS
	84	OSSL_FUNC_asym_cipher_gettable_ctx_params OSSL_FUNC_ASYM_CIPHER_GETTABLE_CTX_PARAMS
	85	OSSL_FUNC_asym_cipher_set_ctx_params OSSL_FUNC_ASYM_CIPHER_SET_CTX_PARAMS
	86	OSSL_FUNC_asym_cipher_settable_ctx_params OSSL_FUNC_ASYM_CIPHER_SETTABLE_CTX_PARAMS
11d876df MC	87
	88	An asymmetric cipher algorithm implementation may not implement all of these
	89	functions.
	90	In order to be a consistent set of functions a provider must implement
363b1e5d DMSP	91	OSSL_FUNC_asym_cipher_newctx and OSSL_FUNC_asym_cipher_freectx.
	92	It must also implement both of OSSL_FUNC_asym_cipher_encrypt_init and
	93	OSSL_FUNC_asym_cipher_encrypt, or both of OSSL_FUNC_asym_cipher_decrypt_init and
	94	OSSL_FUNC_asym_cipher_decrypt.
	95	OSSL_FUNC_asym_cipher_get_ctx_params is optional but if it is present then so must
	96	OSSL_FUNC_asym_cipher_gettable_ctx_params.
	97	Similarly, OSSL_FUNC_asym_cipher_set_ctx_params is optional but if it is present then
	98	so must OSSL_FUNC_asym_cipher_settable_ctx_params.
11d876df MC	99
	100	An asymmetric cipher algorithm must also implement some mechanism for generating,
	101	loading or importing keys via the key management (OSSL_OP_KEYMGMT) operation.
	102	See L<provider-keymgmt(7)> for further details.
	103
	104	=head2 Context Management Functions
	105
363b1e5d	106	OSSL_FUNC_asym_cipher_newctx() should create and return a pointer to a provider side
11d876df MC	107	structure for holding context information during an asymmetric cipher operation.
	108	A pointer to this context will be passed back in a number of the other
	109	asymmetric cipher operation function calls.
	110	The parameter I<provctx> is the provider context generated during provider
fadb57e5	111	initialisation (see L<provider(7)>).
11d876df	112
363b1e5d	113	OSSL_FUNC_asym_cipher_freectx() is passed a pointer to the provider side asymmetric
11d876df MC	114	cipher context in the I<ctx> parameter.
	115	This function should free any resources associated with that context.
	116
363b1e5d	117	OSSL_FUNC_asym_cipher_dupctx() should duplicate the provider side asymmetric cipher
11d876df MC	118	context in the I<ctx> parameter and return the duplicate copy.
	119
	120	=head2 Encryption Functions
	121
363b1e5d	122	OSSL_FUNC_asym_cipher_encrypt_init() initialises a context for an asymmetric encryption
11d876df MC	123	given a provider side asymmetric cipher context in the I<ctx> parameter, and a
	124	pointer to a provider key object in the I<provkey> parameter.
	125	The key object should have been previously generated, loaded or imported into
	126	the provider using the key management (OSSL_OP_KEYMGMT) operation (see
	127	provider-keymgmt(7)>.
	128
363b1e5d	129	OSSL_FUNC_asym_cipher_encrypt() performs the actual encryption itself.
11d876df MC	130	A previously initialised asymmetric cipher context is passed in the I<ctx>
	131	parameter.
	132	The data to be encrypted is pointed to by the I<in> parameter which is I<inlen>
	133	bytes long.
	134	Unless I<out> is NULL, the encrypted data should be written to the location
	135	pointed to by the I<out> parameter and it should not exceed I<outsize> bytes in
	136	length.
	137	The length of the encrypted data should be written to I<*outlen>.
	138	If I<out> is NULL then the maximum length of the encrypted data should be
	139	written to I<*outlen>.
	140
	141	=head2 Decryption Functions
	142
363b1e5d	143	OSSL_FUNC_asym_cipher_decrypt_init() initialises a context for an asymmetric decryption
11d876df MC	144	given a provider side asymmetric cipher context in the I<ctx> parameter, and a
	145	pointer to a provider key object in the I<provkey> parameter.
	146	The key object should have been previously generated, loaded or imported into
	147	the provider using the key management (OSSL_OP_KEYMGMT) operation (see
	148	provider-keymgmt(7)>.
	149
363b1e5d	150	OSSL_FUNC_asym_cipher_decrypt() performs the actual decryption itself.
11d876df MC	151	A previously initialised asymmetric cipher context is passed in the I<ctx>
	152	parameter.
	153	The data to be decrypted is pointed to by the I<in> parameter which is I<inlen>
	154	bytes long.
	155	Unless I<out> is NULL, the decrypted data should be written to the location
	156	pointed to by the I<out> parameter and it should not exceed I<outsize> bytes in
	157	length.
	158	The length of the decrypted data should be written to I<*outlen>.
	159	If I<out> is NULL then the maximum length of the decrypted data should be
	160	written to I<*outlen>.
	161
	162	=head2 Asymmetric Cipher Parameters
	163
	164	See L<OSSL_PARAM(3)> for further details on the parameters structure used by
363b1e5d	165	the OSSL_FUNC_asym_cipher_get_ctx_params() and OSSL_FUNC_asym_cipher_set_ctx_params()
11d876df MC	166	functions.
11d876df MC	167
363b1e5d	168	OSSL_FUNC_asym_cipher_get_ctx_params() gets asymmetric cipher parameters associated
11d876df MC	169	with the given provider side asymmetric cipher context I<ctx> and stores them in
11d876df MC	170	I<params>.
363b1e5d	171	OSSL_FUNC_asym_cipher_set_ctx_params() sets the asymmetric cipher parameters associated
11d876df MC	172	with the given provider side asymmetric cipher context I<ctx> to I<params>.
	173	Any parameter settings are additional to any that were previously set.
	174
	175	Parameters currently recognised by built-in asymmetric cipher algorithms are as
	176	follows.
	177	Not all parameters are relevant to, or are understood by all asymmetric cipher
	178	algorithms:
	179
	180	=over 4
	181
	182	=item "pad-mode" (B<OSSL_ASYM_CIPHER_PARAM_PAD_MODE>) <integer>
	183
350c9235 MC	184	The type of padding to be used. The interpretation of this value will depend
	185	on the algorithm in use. The default provider understands these RSA padding
	186	modes: 1 (RSA_PKCS1_PADDING), 2 (RSA_SSLV23_PADDING), 3 (RSA_NO_PADDING),
	187	4 (RSA_PKCS1_OAEP_PADDING), 5 (RSA_X931_PADDING), 6 (RSA_PKCS1_PSS_PADDING) and
	188	7 (RSA_PKCS1_WITH_TLS_PADDING). See L<EVP_PKEY_CTX_set_rsa_padding(3)> for
	189	further details.
	190
11d876df MC	191	=item "digest" (B<OSSL_ASYM_CIPHER_PARAM_OAEP_DIGEST>) <UTF8 string>
	192
	193	Gets or sets the name of the OAEP digest algorithm used when OAEP padding is in
	194	use.
	195
	196	=item "digest-props" (B<OSSL_ASYM_CIPHER_PARAM_OAEP_DIGEST_PROPS>) <UTF8 string>
	197
	198	Gets or sets the properties to use when fetching the OAEP digest algorithm.
	199
	200	=item "mgf1-digest" (B<OSSL_ASYM_CIPHER_PARAM_MGF1_DIGEST>) <UTF8 string>
	201
	202	Gets or sets the name of the MGF1 digest algorithm used when OAEP or PSS padding
	203	is in use.
	204
	205	=item "mgf1-digest-props" (B<OSSL_ASYM_CIPHER_PARAM_MGF1_DIGEST_PROPS>) <UTF8 string>
	206
	207	Gets or sets the properties to use when fetching the MGF1 digest algorithm.
	208
	209	=item "oaep-label" (B<OSSL_ASYM_CIPHER_PARAM_OAEP_LABEL>) <octet string>
	210
	211	Gets or sets the OAEP label used when OAEP padding is in use.
	212
	213	=item "oaep-label-len" (B<OSSL_ASYM_CIPHER_PARAM_OAEP_LABEL_LEN>) <size_t>
	214
	215	Gets the length of an OAEP label when OAEP padding is in use.
	216
350c9235 MC	217	=item "tls-client-version" (B<OSSL_ASYM_CIPHER_PARAM_TLS_CLIENT_VERSION>) <unsigned integer>
	218
	219	The TLS protocol version first requested by the client. See
	220	B<RSA_PKCS1_WITH_TLS_PADDING> on the page L<EVP_PKEY_CTX_set_rsa_padding(3)>.
	221
	222	=item "tls-negotiated-version" (B<OSSL_ASYM_CIPHER_PARAM_TLS_CLIENT_VERSION>) <unsigned integer>
	223
	224	The negotiated TLS protocol version. See
	225	B<RSA_PKCS1_WITH_TLS_PADDING> on the page L<EVP_PKEY_CTX_set_rsa_padding(3)>.
	226
11d876df MC	227	=back
11d876df MC	228
363b1e5d	229	OSSL_FUNC_asym_cipher_gettable_ctx_params() and OSSL_FUNC_asym_cipher_settable_ctx_params()
11d876df	230	get a constant B<OSSL_PARAM> array that describes the gettable and settable
363b1e5d DMSP	231	parameters, i.e. parameters that can be used with OSSL_FUNC_asym_cipherget_ctx_params()
363b1e5d DMSP	232	and OSSL_FUNC_asym_cipher_set_ctx_params() respectively.
11d876df MC	233	See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as parameter descriptor.
	234
	235	=head1 RETURN VALUES
	236
363b1e5d	237	OSSL_FUNC_asym_cipher_newctx() and OSSL_FUNC_asym_cipher_dupctx() should return the newly
11d876df MC	238	created provider side asymmetric cipher context, or NULL on failure.
	239
	240	All other functions should return 1 for success or 0 on error.
	241
	242	=head1 SEE ALSO
	243
	244	L<provider(7)>
	245
	246	=head1 HISTORY
	247
	248	The provider ASYM_CIPHER interface was introduced in OpenSSL 3.0.
	249
	250	=head1 COPYRIGHT
	251
33388b44	252	Copyright 2019-2020 The OpenSSL Project Authors. All Rights Reserved.
11d876df MC	253
	254	Licensed under the Apache License 2.0 (the "License"). You may not use
	255	this file except in compliance with the License. You can obtain a copy
	256	in the file LICENSE in the source distribution or at
	257	L<https://www.openssl.org/source/license.html>.
	258
	259	=cut