]>
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 | |
25 | /* Encryption */ | |
f187d4f9 P |
26 | int OSSL_FUNC_asym_cipher_encrypt_init(void *ctx, void *provkey, |
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 | |
32 | /* Decryption */ | |
f187d4f9 P |
33 | int OSSL_FUNC_asym_cipher_decrypt_init(void *ctx, void *provkey, |
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 | |
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 | |
318a9dfa RL |
57 | F<libcrypto> and the provider in L<OSSL_DISPATCH(3)> arrays via |
58 | L<OSSL_ALGORITHM(3)> arrays that are returned by the provider's | |
11d876df MC |
59 | provider_query_operation() function |
60 | (see L<provider-base(7)/Provider Functions>). | |
61 | ||
62 | All these "functions" have a corresponding function type definition | |
bd6e7fb7 | 63 | named B<OSSL_FUNC_{name}_fn>, and a helper function to retrieve the |
318a9dfa | 64 | function pointer from an L<OSSL_DISPATCH(3)> element named |
363b1e5d DMSP |
65 | B<OSSL_FUNC_{name}>. |
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 | 71 | |
318a9dfa | 72 | L<OSSL_DISPATCH(3)> 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 |
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 |
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 |
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 |
128 | using OSSL_FUNC_asym_cipher_set_ctx_params(). | |
11d876df | 129 | The key object should have been previously generated, loaded or imported into |
010333be | 130 | the provider using the key management (OSSL_OP_KEYMGMT) operation (see L<provider-keymgmt(7)>). |
363b1e5d | 131 | OSSL_FUNC_asym_cipher_encrypt() performs the actual encryption itself. |
11d876df MC |
132 | A previously initialised asymmetric cipher context is passed in the I<ctx> |
133 | parameter. | |
134 | The data to be encrypted is pointed to by the I<in> parameter which is I<inlen> | |
135 | bytes long. | |
136 | Unless I<out> is NULL, the encrypted data should be written to the location | |
137 | pointed to by the I<out> parameter and it should not exceed I<outsize> bytes in | |
138 | length. | |
139 | The length of the encrypted data should be written to I<*outlen>. | |
140 | If I<out> is NULL then the maximum length of the encrypted data should be | |
141 | written to I<*outlen>. | |
142 | ||
143 | =head2 Decryption Functions | |
144 | ||
363b1e5d | 145 | OSSL_FUNC_asym_cipher_decrypt_init() initialises a context for an asymmetric decryption |
11d876df MC |
146 | given a provider side asymmetric cipher context in the I<ctx> parameter, and a |
147 | pointer to a provider key object in the I<provkey> parameter. | |
f187d4f9 P |
148 | The I<params>, if not NULL, should be set on the context in a manner similar to |
149 | using OSSL_FUNC_asym_cipher_set_ctx_params(). | |
11d876df MC |
150 | The key object should have been previously generated, loaded or imported into |
151 | the provider using the key management (OSSL_OP_KEYMGMT) operation (see | |
010333be | 152 | L<provider-keymgmt(7)>). |
11d876df | 153 | |
363b1e5d | 154 | OSSL_FUNC_asym_cipher_decrypt() performs the actual decryption itself. |
11d876df MC |
155 | A previously initialised asymmetric cipher context is passed in the I<ctx> |
156 | parameter. | |
157 | The data to be decrypted is pointed to by the I<in> parameter which is I<inlen> | |
158 | bytes long. | |
159 | Unless I<out> is NULL, the decrypted data should be written to the location | |
160 | pointed to by the I<out> parameter and it should not exceed I<outsize> bytes in | |
161 | length. | |
162 | The length of the decrypted data should be written to I<*outlen>. | |
163 | If I<out> is NULL then the maximum length of the decrypted data should be | |
164 | written to I<*outlen>. | |
165 | ||
166 | =head2 Asymmetric Cipher Parameters | |
167 | ||
168 | See L<OSSL_PARAM(3)> for further details on the parameters structure used by | |
363b1e5d | 169 | the OSSL_FUNC_asym_cipher_get_ctx_params() and OSSL_FUNC_asym_cipher_set_ctx_params() |
11d876df MC |
170 | functions. |
171 | ||
363b1e5d | 172 | OSSL_FUNC_asym_cipher_get_ctx_params() gets asymmetric cipher parameters associated |
11d876df MC |
173 | with the given provider side asymmetric cipher context I<ctx> and stores them in |
174 | I<params>. | |
f59612fe P |
175 | Passing NULL for I<params> should return true. |
176 | ||
363b1e5d | 177 | OSSL_FUNC_asym_cipher_set_ctx_params() sets the asymmetric cipher parameters associated |
11d876df MC |
178 | with the given provider side asymmetric cipher context I<ctx> to I<params>. |
179 | Any parameter settings are additional to any that were previously set. | |
f59612fe | 180 | Passing NULL for I<params> should return true. |
11d876df MC |
181 | |
182 | Parameters currently recognised by built-in asymmetric cipher algorithms are as | |
183 | follows. | |
184 | Not all parameters are relevant to, or are understood by all asymmetric cipher | |
185 | algorithms: | |
186 | ||
187 | =over 4 | |
188 | ||
ad60cd52 | 189 | =item "pad-mode" (B<OSSL_ASYM_CIPHER_PARAM_PAD_MODE>) <UTF8 string> OR <integer> |
11d876df | 190 | |
350c9235 | 191 | The type of padding to be used. The interpretation of this value will depend |
ad60cd52 | 192 | on the algorithm in use. |
350c9235 | 193 | |
11d876df MC |
194 | =item "digest" (B<OSSL_ASYM_CIPHER_PARAM_OAEP_DIGEST>) <UTF8 string> |
195 | ||
196 | Gets or sets the name of the OAEP digest algorithm used when OAEP padding is in | |
197 | use. | |
198 | ||
a48309cb MC |
199 | =item "digest" (B<OSSL_ASYM_CIPHER_PARAM_DIGEST>) <UTF8 string> |
200 | ||
201 | Gets or sets the name of the digest algorithm used by the algorithm (where | |
202 | applicable). | |
203 | ||
11d876df MC |
204 | =item "digest-props" (B<OSSL_ASYM_CIPHER_PARAM_OAEP_DIGEST_PROPS>) <UTF8 string> |
205 | ||
206 | Gets or sets the properties to use when fetching the OAEP digest algorithm. | |
207 | ||
a48309cb MC |
208 | =item "digest-props" (B<OSSL_ASYM_CIPHER_PARAM_DIGEST_PROPS>) <UTF8 string> |
209 | ||
210 | Gets or sets the properties to use when fetching the cipher digest algorithm. | |
211 | ||
11d876df MC |
212 | =item "mgf1-digest" (B<OSSL_ASYM_CIPHER_PARAM_MGF1_DIGEST>) <UTF8 string> |
213 | ||
214 | Gets or sets the name of the MGF1 digest algorithm used when OAEP or PSS padding | |
215 | is in use. | |
216 | ||
217 | =item "mgf1-digest-props" (B<OSSL_ASYM_CIPHER_PARAM_MGF1_DIGEST_PROPS>) <UTF8 string> | |
218 | ||
219 | Gets or sets the properties to use when fetching the MGF1 digest algorithm. | |
220 | ||
ad60cd52 | 221 | =item "oaep-label" (B<OSSL_ASYM_CIPHER_PARAM_OAEP_LABEL>) <octet string ptr> |
222 | ||
223 | Gets the OAEP label used when OAEP padding is in use. | |
224 | ||
11d876df MC |
225 | =item "oaep-label" (B<OSSL_ASYM_CIPHER_PARAM_OAEP_LABEL>) <octet string> |
226 | ||
ad60cd52 | 227 | Sets the OAEP label used when OAEP padding is in use. |
11d876df | 228 | |
350c9235 MC |
229 | =item "tls-client-version" (B<OSSL_ASYM_CIPHER_PARAM_TLS_CLIENT_VERSION>) <unsigned integer> |
230 | ||
ad60cd52 | 231 | The TLS protocol version first requested by the client. |
350c9235 MC |
232 | |
233 | =item "tls-negotiated-version" (B<OSSL_ASYM_CIPHER_PARAM_TLS_CLIENT_VERSION>) <unsigned integer> | |
234 | ||
ad60cd52 | 235 | The negotiated TLS protocol version. |
350c9235 | 236 | |
5ab3ec1b HK |
237 | =item "implicit-rejection" (B<OSSL_PKEY_PARAM_IMPLICIT_REJECTION>) <unsigned integer> |
238 | ||
239 | Gets of sets the use of the implicit rejection mechanism for RSA PKCS#1 v1.5 | |
240 | decryption. When set (non zero value), the decryption API will return | |
241 | a deterministically random value if the PKCS#1 v1.5 padding check fails. | |
a53d4f83 | 242 | This makes exploitation of the Bleichenbacher significantly harder, even |
5ab3ec1b HK |
243 | if the code using the RSA decryption API is not implemented in side-channel |
244 | free manner. Set by default. | |
245 | ||
11d876df MC |
246 | =back |
247 | ||
363b1e5d | 248 | OSSL_FUNC_asym_cipher_gettable_ctx_params() and OSSL_FUNC_asym_cipher_settable_ctx_params() |
318a9dfa | 249 | get a constant L<OSSL_PARAM(3)> array that describes the gettable and settable |
363b1e5d DMSP |
250 | parameters, i.e. parameters that can be used with OSSL_FUNC_asym_cipherget_ctx_params() |
251 | and OSSL_FUNC_asym_cipher_set_ctx_params() respectively. | |
11d876df MC |
252 | |
253 | =head1 RETURN VALUES | |
254 | ||
363b1e5d | 255 | OSSL_FUNC_asym_cipher_newctx() and OSSL_FUNC_asym_cipher_dupctx() should return the newly |
11d876df MC |
256 | created provider side asymmetric cipher context, or NULL on failure. |
257 | ||
258 | All other functions should return 1 for success or 0 on error. | |
259 | ||
260 | =head1 SEE ALSO | |
261 | ||
262 | L<provider(7)> | |
263 | ||
264 | =head1 HISTORY | |
265 | ||
266 | The provider ASYM_CIPHER interface was introduced in OpenSSL 3.0. | |
267 | ||
268 | =head1 COPYRIGHT | |
269 | ||
da1c088f | 270 | Copyright 2019-2023 The OpenSSL Project Authors. All Rights Reserved. |
11d876df MC |
271 | |
272 | Licensed under the Apache License 2.0 (the "License"). You may not use | |
273 | this file except in compliance with the License. You can obtain a copy | |
274 | in the file LICENSE in the source distribution or at | |
275 | L<https://www.openssl.org/source/license.html>. | |
276 | ||
277 | =cut |