[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,
                                        const OSSL_PARAM params[]);
 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,
                                        const OSSL_PARAM params[]);
 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 *provctx);
 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 *provctx);

=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 I<params>, if not NULL, should be set on the context in a manner similar to
using OSSL_FUNC_asym_cipher_set_ctx_params().
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 I<params>, if not NULL, should be set on the context in a manner similar to
using OSSL_FUNC_asym_cipher_set_ctx_params().
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>.
Passing NULL for I<params> should return true.

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.
Passing NULL for I<params> should return true.

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), 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" (B<OSSL_ASYM_CIPHER_PARAM_DIGEST>) <UTF8 string>

Gets or sets the name of the digest algorithm used by the algorithm (where
applicable).

=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 "digest-props" (B<OSSL_ASYM_CIPHER_PARAM_DIGEST_PROPS>) <UTF8 string>

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