]>
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 | ||
11 | #include <openssl/core_numbers.h> | |
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 */ | |
21 | void *OP_asym_cipher_newctx(void *provctx); | |
22 | void OP_asym_cipher_freectx(void *ctx); | |
23 | void *OP_asym_cipher_dupctx(void *ctx); | |
24 | ||
25 | /* Encryption */ | |
26 | int OP_asym_cipher_encrypt_init(void *ctx, void *provkey); | |
27 | int OP_asym_cipher_encrypt(void *ctx, unsigned char *out, size_t *outlen, | |
28 | size_t outsize, const unsigned char *in, | |
29 | size_t inlen); | |
30 | ||
31 | /* Decryption */ | |
32 | int OP_asym_cipher_decrypt_init(void *ctx, void *provkey); | |
33 | int OP_asym_cipher_decrypt(void *ctx, unsigned char *out, size_t *outlen, | |
34 | size_t outsize, const unsigned char *in, | |
35 | size_t inlen); | |
36 | ||
37 | /* Asymmetric Cipher parameters */ | |
38 | int OP_asym_cipher_get_ctx_params(void *ctx, OSSL_PARAM params[]); | |
39 | const OSSL_PARAM *OP_asym_cipher_gettable_ctx_params(void); | |
40 | int OP_asym_cipher_set_ctx_params(void *ctx, const OSSL_PARAM params[]); | |
41 | const OSSL_PARAM *OP_asym_cipher_settable_ctx_params(void); | |
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 | |
63 | B<OSSL_get_{name}>. | |
64 | For example, the "function" OP_asym_cipher_newctx() has these: | |
65 | ||
66 | typedef void *(OSSL_OP_asym_cipher_newctx_fn)(void *provctx); | |
67 | static ossl_inline OSSL_OP_asym_cipher_newctx_fn | |
68 | OSSL_get_OP_asym_cipher_newctx(const OSSL_DISPATCH *opf); | |
69 | ||
70 | B<OSSL_DISPATCH> arrays are indexed by numbers that are provided as | |
71 | macros in L<openssl-core_numbers.h(7)>, as follows: | |
72 | ||
73 | OP_asym_cipher_newctx OSSL_FUNC_ASYM_CIPHER_NEWCTX | |
74 | OP_asym_cipher_freectx OSSL_FUNC_ASYM_CIPHER_FREECTX | |
75 | OP_asym_cipher_dupctx OSSL_FUNC_ASYM_CIPHER_DUPCTX | |
76 | ||
77 | OP_asym_cipher_encrypt_init OSSL_FUNC_ASYM_CIPHER_ENCRYPT_INIT | |
78 | OP_asym_cipher_encrypt OSSL_FUNC_ASYM_CIPHER_ENCRYPT | |
79 | ||
80 | OP_asym_cipher_decrypt_init OSSL_FUNC_ASYM_CIPHER_DECRYPT_INIT | |
81 | OP_asym_cipher_decrypt OSSL_FUNC_ASYM_CIPHER_DECRYPT | |
82 | ||
83 | OP_asym_cipher_get_ctx_params OSSL_FUNC_ASYM_CIPHER_GET_CTX_PARAMS | |
84 | OP_asym_cipher_gettable_ctx_params OSSL_FUNC_ASYM_CIPHER_GETTABLE_CTX_PARAMS | |
85 | OP_asym_cipher_set_ctx_params OSSL_FUNC_ASYM_CIPHER_SET_CTX_PARAMS | |
86 | OP_asym_cipher_settable_ctx_params OSSL_FUNC_ASYM_CIPHER_SETTABLE_CTX_PARAMS | |
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 | |
91 | OP_asym_cipher_newctx and OP_asym_cipher_freectx. | |
92 | It must also implement both of OP_asym_cipher_encrypt_init and | |
93 | OP_asym_cipher_encrypt, or both of OP_asym_cipher_decrypt_init and | |
94 | OP_asym_cipher_decrypt. | |
95 | OP_asym_cipher_get_ctx_params is optional but if it is present then so must | |
96 | OP_asym_cipher_gettable_ctx_params. | |
97 | Similarly, OP_asym_cipher_set_ctx_params is optional but if it is present then | |
98 | so must OP_asym_cipher_settable_ctx_params. | |
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 | ||
106 | OP_asym_cipher_newctx() should create and return a pointer to a provider side | |
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 MC |
112 | |
113 | OP_asym_cipher_freectx() is passed a pointer to the provider side asymmetric | |
114 | cipher context in the I<ctx> parameter. | |
115 | This function should free any resources associated with that context. | |
116 | ||
117 | OP_asym_cipher_dupctx() should duplicate the provider side asymmetric cipher | |
118 | context in the I<ctx> parameter and return the duplicate copy. | |
119 | ||
120 | =head2 Encryption Functions | |
121 | ||
122 | OP_asym_cipher_encrypt_init() initialises a context for an asymmetric encryption | |
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 | ||
129 | OP_asym_cipher_encrypt() performs the actual encryption itself. | |
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 | ||
143 | OP_asym_cipher_decrypt_init() initialises a context for an asymmetric decryption | |
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 | ||
150 | OP_asym_cipher_decrypt() performs the actual decryption itself. | |
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 | |
165 | the OP_asym_cipher_get_ctx_params() and OP_asym_cipher_set_ctx_params() | |
166 | functions. | |
167 | ||
168 | OP_asym_cipher_get_ctx_params() gets asymmetric cipher parameters associated | |
169 | with the given provider side asymmetric cipher context I<ctx> and stores them in | |
170 | I<params>. | |
171 | OP_asym_cipher_set_ctx_params() sets the asymmetric cipher parameters associated | |
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 |
228 | ||
229 | OP_asym_cipher_gettable_ctx_params() and OP_asym_cipher_settable_ctx_params() | |
230 | get a constant B<OSSL_PARAM> array that describes the gettable and settable | |
231 | parameters, i.e. parameters that can be used with OP_asym_cipherget_ctx_params() | |
232 | and OP_asym_cipher_set_ctx_params() respectively. | |
233 | See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as parameter descriptor. | |
234 | ||
235 | =head1 RETURN VALUES | |
236 | ||
237 | OP_asym_cipher_newctx() and OP_asym_cipher_dupctx() should return the newly | |
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 | ||
252 | Copyright 2019 The OpenSSL Project Authors. All Rights Reserved. | |
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 |