1PROVIDER-ASYM_CIPHER(7ossl) OpenSSL PROVIDER-ASYM_CIPHER(7ossl)
2
6 provider-asym_cipher - The asym_cipher library <-> provider functions
7
9 #include <openssl/core_dispatch.h>
10 #include <openssl/core_names.h>
11 /*
13 * None of these are actual functions, but are displayed like this for
14 * the function signatures for functions that are offered as function
15 * pointers in OSSL_DISPATCH arrays.
16 */
17 /* Context management */
19 void *OSSL_FUNC_asym_cipher_newctx(void *provctx);
20 void OSSL_FUNC_asym_cipher_freectx(void *ctx);
21 void *OSSL_FUNC_asym_cipher_dupctx(void *ctx);
22 /* Encryption */
24 int OSSL_FUNC_asym_cipher_encrypt_init(void *ctx, void *provkey,
25 const OSSL_PARAM params[]);
26 int OSSL_FUNC_asym_cipher_encrypt(void *ctx, unsigned char *out, size_t *outlen,
27 size_t outsize, const unsigned char *in,
28 size_t inlen);
29 /* Decryption */
31 int OSSL_FUNC_asym_cipher_decrypt_init(void *ctx, void *provkey,
32 const OSSL_PARAM params[]);
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);
36 /* Asymmetric Cipher parameters */
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 *provctx);
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 *provctx);
42
44 This documentation is primarily aimed at provider authors. See
45 provider(7) for further information.
46 The asymmetric cipher (OSSL_OP_ASYM_CIPHER) operation enables providers
48 to implement asymmetric cipher algorithms and make them available to
49 applications via the API functions EVP_PKEY_encrypt(3),
50 EVP_PKEY_decrypt(3) and other related functions).
51 All "functions" mentioned here are passed as function pointers between
53 libcrypto and the provider in OSSL_DISPATCH(3) arrays via
54 OSSL_ALGORITHM(3) arrays that are returned by the provider's
55 provider_query_operation() function (see "Provider Functions" in
56 provider-base(7)).
57 All these "functions" have a corresponding function type definition
59 named OSSL_FUNC_{name}_fn, and a helper function to retrieve the
60 function pointer from an OSSL_DISPATCH(3) element named
61 OSSL_FUNC_{name}. For example, the "function"
62 OSSL_FUNC_asym_cipher_newctx() has these:
63 typedef void *(OSSL_FUNC_asym_cipher_newctx_fn)(void *provctx);
65 static ossl_inline OSSL_FUNC_asym_cipher_newctx_fn
66 OSSL_FUNC_asym_cipher_newctx(const OSSL_DISPATCH *opf);
67 OSSL_DISPATCH(3) arrays are indexed by numbers that are provided as
69 macros in openssl-core_dispatch.h(7), as follows:
70 OSSL_FUNC_asym_cipher_newctx OSSL_FUNC_ASYM_CIPHER_NEWCTX
72 OSSL_FUNC_asym_cipher_freectx OSSL_FUNC_ASYM_CIPHER_FREECTX
73 OSSL_FUNC_asym_cipher_dupctx OSSL_FUNC_ASYM_CIPHER_DUPCTX
74 OSSL_FUNC_asym_cipher_encrypt_init OSSL_FUNC_ASYM_CIPHER_ENCRYPT_INIT
76 OSSL_FUNC_asym_cipher_encrypt OSSL_FUNC_ASYM_CIPHER_ENCRYPT
77 OSSL_FUNC_asym_cipher_decrypt_init OSSL_FUNC_ASYM_CIPHER_DECRYPT_INIT
79 OSSL_FUNC_asym_cipher_decrypt OSSL_FUNC_ASYM_CIPHER_DECRYPT
80 OSSL_FUNC_asym_cipher_get_ctx_params OSSL_FUNC_ASYM_CIPHER_GET_CTX_PARAMS
82 OSSL_FUNC_asym_cipher_gettable_ctx_params OSSL_FUNC_ASYM_CIPHER_GETTABLE_CTX_PARAMS
83 OSSL_FUNC_asym_cipher_set_ctx_params OSSL_FUNC_ASYM_CIPHER_SET_CTX_PARAMS
84 OSSL_FUNC_asym_cipher_settable_ctx_params OSSL_FUNC_ASYM_CIPHER_SETTABLE_CTX_PARAMS
85 An asymmetric cipher algorithm implementation may not implement all of
87 these functions. In order to be a consistent set of functions a
88 provider must implement OSSL_FUNC_asym_cipher_newctx and
89 OSSL_FUNC_asym_cipher_freectx. It must also implement both of
90 OSSL_FUNC_asym_cipher_encrypt_init and OSSL_FUNC_asym_cipher_encrypt,
91 or both of OSSL_FUNC_asym_cipher_decrypt_init and
92 OSSL_FUNC_asym_cipher_decrypt. OSSL_FUNC_asym_cipher_get_ctx_params is
93 optional but if it is present then so must
94 OSSL_FUNC_asym_cipher_gettable_ctx_params. Similarly,
95 OSSL_FUNC_asym_cipher_set_ctx_params is optional but if it is present
96 then so must OSSL_FUNC_asym_cipher_settable_ctx_params.
97 An asymmetric cipher algorithm must also implement some mechanism for
99 generating, loading or importing keys via the key management
100 (OSSL_OP_KEYMGMT) operation. See provider-keymgmt(7) for further
101 details.
102 Context Management Functions
104 OSSL_FUNC_asym_cipher_newctx() should create and return a pointer to a
105 provider side structure for holding context information during an
106 asymmetric cipher operation. A pointer to this context will be passed
107 back in a number of the other asymmetric cipher operation function
108 calls. The parameter provctx is the provider context generated during
109 provider initialisation (see provider(7)).
110 OSSL_FUNC_asym_cipher_freectx() is passed a pointer to the provider
112 side asymmetric cipher context in the ctx parameter. This function
113 should free any resources associated with that context.
114 OSSL_FUNC_asym_cipher_dupctx() should duplicate the provider side
116 asymmetric cipher context in the ctx parameter and return the duplicate
117 copy.
118 Encryption Functions
120 OSSL_FUNC_asym_cipher_encrypt_init() initialises a context for an
121 asymmetric encryption given a provider side asymmetric cipher context
122 in the ctx parameter, and a pointer to a provider key object in the
123 provkey parameter. The params, if not NULL, should be set on the
124 context in a manner similar to using
125 OSSL_FUNC_asym_cipher_set_ctx_params(). The key object should have
126 been previously generated, loaded or imported into the provider using
127 the key management (OSSL_OP_KEYMGMT) operation (see
128 provider-keymgmt(7)). OSSL_FUNC_asym_cipher_encrypt() performs the
129 actual encryption itself. A previously initialised asymmetric cipher
130 context is passed in the ctx parameter. The data to be encrypted is
131 pointed to by the in parameter which is inlen bytes long. Unless out
132 is NULL, the encrypted data should be written to the location pointed
133 to by the out parameter and it should not exceed outsize bytes in
134 length. The length of the encrypted data should be written to *outlen.
135 If out is NULL then the maximum length of the encrypted data should be
136 written to *outlen.
137 Decryption Functions
139 OSSL_FUNC_asym_cipher_decrypt_init() initialises a context for an
140 asymmetric decryption given a provider side asymmetric cipher context
141 in the ctx parameter, and a pointer to a provider key object in the
142 provkey parameter. The params, if not NULL, should be set on the
143 context in a manner similar to using
144 OSSL_FUNC_asym_cipher_set_ctx_params(). The key object should have
145 been previously generated, loaded or imported into the provider using
146 the key management (OSSL_OP_KEYMGMT) operation (see
147 provider-keymgmt(7)).
148 OSSL_FUNC_asym_cipher_decrypt() performs the actual decryption itself.
150 A previously initialised asymmetric cipher context is passed in the ctx
151 parameter. The data to be decrypted is pointed to by the in parameter
152 which is inlen bytes long. Unless out is NULL, the decrypted data
153 should be written to the location pointed to by the out parameter and
154 it should not exceed outsize bytes in length. The length of the
155 decrypted data should be written to *outlen. If out is NULL then the
156 maximum length of the decrypted data should be written to *outlen.
157 Asymmetric Cipher Parameters
159 See OSSL_PARAM(3) for further details on the parameters structure used
160 by the OSSL_FUNC_asym_cipher_get_ctx_params() and
161 OSSL_FUNC_asym_cipher_set_ctx_params() functions.
162 OSSL_FUNC_asym_cipher_get_ctx_params() gets asymmetric cipher
164 parameters associated with the given provider side asymmetric cipher
165 context ctx and stores them in params. Passing NULL for params should
166 return true.
167 OSSL_FUNC_asym_cipher_set_ctx_params() sets the asymmetric cipher
169 parameters associated with the given provider side asymmetric cipher
170 context ctx to params. Any parameter settings are additional to any
171 that were previously set. Passing NULL for params should return true.
172 Parameters currently recognised by built-in asymmetric cipher
174 algorithms are as follows. Not all parameters are relevant to, or are
175 understood by all asymmetric cipher algorithms:
176 "pad-mode" (OSSL_ASYM_CIPHER_PARAM_PAD_MODE) <UTF8 string> OR <integer>
178 The type of padding to be used. The interpretation of this value
179 will depend on the algorithm in use.
180 "digest" (OSSL_ASYM_CIPHER_PARAM_OAEP_DIGEST) <UTF8 string>
182 Gets or sets the name of the OAEP digest algorithm used when OAEP
183 padding is in use.
184 "digest" (OSSL_ASYM_CIPHER_PARAM_DIGEST) <UTF8 string>
186 Gets or sets the name of the digest algorithm used by the algorithm
187 (where applicable).
188 "digest-props" (OSSL_ASYM_CIPHER_PARAM_OAEP_DIGEST_PROPS) <UTF8 string>
190 Gets or sets the properties to use when fetching the OAEP digest
191 algorithm.
192 "digest-props" (OSSL_ASYM_CIPHER_PARAM_DIGEST_PROPS) <UTF8 string>
194 Gets or sets the properties to use when fetching the cipher digest
195 algorithm.
196 "mgf1-digest" (OSSL_ASYM_CIPHER_PARAM_MGF1_DIGEST) <UTF8 string>
198 Gets or sets the name of the MGF1 digest algorithm used when OAEP
199 or PSS padding is in use.
200 "mgf1-digest-props" (OSSL_ASYM_CIPHER_PARAM_MGF1_DIGEST_PROPS) <UTF8
202 string>
203 Gets or sets the properties to use when fetching the MGF1 digest
204 algorithm.
205 "oaep-label" (OSSL_ASYM_CIPHER_PARAM_OAEP_LABEL) <octet string ptr>
207 Gets the OAEP label used when OAEP padding is in use.
208 "oaep-label" (OSSL_ASYM_CIPHER_PARAM_OAEP_LABEL) <octet string>
210 Sets the OAEP label used when OAEP padding is in use.
211 "tls-client-version" (OSSL_ASYM_CIPHER_PARAM_TLS_CLIENT_VERSION)
213 <unsigned integer>
214 The TLS protocol version first requested by the client.
215 "tls-negotiated-version" (OSSL_ASYM_CIPHER_PARAM_TLS_CLIENT_VERSION)
217 <unsigned integer>
218 The negotiated TLS protocol version.
219 "implicit-rejection" (OSSL_PKEY_PARAM_IMPLICIT_REJECTION) <unsigned
221 integer>
222 Gets of sets the use of the implicit rejection mechanism for RSA
223 PKCS#1 v1.5 decryption. When set (non zero value), the decryption
224 API will return a deterministically random value if the PKCS#1 v1.5
225 padding check fails. This makes explotation of the Bleichenbacher
226 significantly harder, even if the code using the RSA decryption API
227 is not implemented in side-channel free manner. Set by default.
228 OSSL_FUNC_asym_cipher_gettable_ctx_params() and
230 OSSL_FUNC_asym_cipher_settable_ctx_params() get a constant
231 OSSL_PARAM(3) array that describes the gettable and settable
232 parameters, i.e. parameters that can be used with
233 OSSL_FUNC_asym_cipherget_ctx_params() and
234 OSSL_FUNC_asym_cipher_set_ctx_params() respectively.
235
237 OSSL_FUNC_asym_cipher_newctx() and OSSL_FUNC_asym_cipher_dupctx()
238 should return the newly created provider side asymmetric cipher
239 context, or NULL on failure.
240 All other functions should return 1 for success or 0 on error.
242
244 provider(7)
245
247 The provider ASYM_CIPHER interface was introduced in OpenSSL 3.0.
248
250 Copyright 2019-2023 The OpenSSL Project Authors. All Rights Reserved.
251 Licensed under the Apache License 2.0 (the "License"). You may not use
253 this file except in compliance with the License. You can obtain a copy
254 in the file LICENSE in the source distribution or at
255 <https://www.openssl.org/source/license.html>.
2563.0.9 2023-07-27 PROVIDER-ASYM_CIPHER(7ossl)