1PROVIDER-ASYM_CIPHER(7ossl)         OpenSSL        PROVIDER-ASYM_CIPHER(7ossl)
2
3
4

NAME

6       provider-asym_cipher - The asym_cipher library <-> provider functions
7

SYNOPSIS

9        #include <openssl/core_dispatch.h>
10        #include <openssl/core_names.h>
11
12        /*
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
18        /* 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
23        /* 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
30        /* 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
37        /* 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

DESCRIPTION

44       This documentation is primarily aimed at provider authors. See
45       provider(7) for further information.
46
47       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
52       All "functions" mentioned here are passed as function pointers between
53       libcrypto and the provider in OSSL_DISPATCH arrays via OSSL_ALGORITHM
54       arrays that are returned by the provider's provider_query_operation()
55       function (see "Provider Functions" in provider-base(7)).
56
57       All these "functions" have a corresponding function type definition
58       named OSSL_FUNC_{name}_fn, and a helper function to retrieve the
59       function pointer from an OSSL_DISPATCH element named OSSL_FUNC_{name}.
60       For example, the "function" OSSL_FUNC_asym_cipher_newctx() has these:
61
62        typedef void *(OSSL_FUNC_asym_cipher_newctx_fn)(void *provctx);
63        static ossl_inline OSSL_FUNC_asym_cipher_newctx_fn
64            OSSL_FUNC_asym_cipher_newctx(const OSSL_DISPATCH *opf);
65
66       OSSL_DISPATCH arrays are indexed by numbers that are provided as macros
67       in openssl-core_dispatch.h(7), as follows:
68
69        OSSL_FUNC_asym_cipher_newctx               OSSL_FUNC_ASYM_CIPHER_NEWCTX
70        OSSL_FUNC_asym_cipher_freectx              OSSL_FUNC_ASYM_CIPHER_FREECTX
71        OSSL_FUNC_asym_cipher_dupctx               OSSL_FUNC_ASYM_CIPHER_DUPCTX
72
73        OSSL_FUNC_asym_cipher_encrypt_init         OSSL_FUNC_ASYM_CIPHER_ENCRYPT_INIT
74        OSSL_FUNC_asym_cipher_encrypt              OSSL_FUNC_ASYM_CIPHER_ENCRYPT
75
76        OSSL_FUNC_asym_cipher_decrypt_init         OSSL_FUNC_ASYM_CIPHER_DECRYPT_INIT
77        OSSL_FUNC_asym_cipher_decrypt              OSSL_FUNC_ASYM_CIPHER_DECRYPT
78
79        OSSL_FUNC_asym_cipher_get_ctx_params       OSSL_FUNC_ASYM_CIPHER_GET_CTX_PARAMS
80        OSSL_FUNC_asym_cipher_gettable_ctx_params  OSSL_FUNC_ASYM_CIPHER_GETTABLE_CTX_PARAMS
81        OSSL_FUNC_asym_cipher_set_ctx_params       OSSL_FUNC_ASYM_CIPHER_SET_CTX_PARAMS
82        OSSL_FUNC_asym_cipher_settable_ctx_params  OSSL_FUNC_ASYM_CIPHER_SETTABLE_CTX_PARAMS
83
84       An asymmetric cipher algorithm implementation may not implement all of
85       these functions.  In order to be a consistent set of functions a
86       provider must implement OSSL_FUNC_asym_cipher_newctx and
87       OSSL_FUNC_asym_cipher_freectx.  It must also implement both of
88       OSSL_FUNC_asym_cipher_encrypt_init and OSSL_FUNC_asym_cipher_encrypt,
89       or both of OSSL_FUNC_asym_cipher_decrypt_init and
90       OSSL_FUNC_asym_cipher_decrypt.  OSSL_FUNC_asym_cipher_get_ctx_params is
91       optional but if it is present then so must
92       OSSL_FUNC_asym_cipher_gettable_ctx_params.  Similarly,
93       OSSL_FUNC_asym_cipher_set_ctx_params is optional but if it is present
94       then so must OSSL_FUNC_asym_cipher_settable_ctx_params.
95
96       An asymmetric cipher algorithm must also implement some mechanism for
97       generating, loading or importing keys via the key management
98       (OSSL_OP_KEYMGMT) operation.  See provider-keymgmt(7) for further
99       details.
100
101   Context Management Functions
102       OSSL_FUNC_asym_cipher_newctx() should create and return a pointer to a
103       provider side structure for holding context information during an
104       asymmetric cipher operation.  A pointer to this context will be passed
105       back in a number of the other asymmetric cipher operation function
106       calls.  The parameter provctx is the provider context generated during
107       provider initialisation (see provider(7)).
108
109       OSSL_FUNC_asym_cipher_freectx() is passed a pointer to the provider
110       side asymmetric cipher context in the ctx parameter.  This function
111       should free any resources associated with that context.
112
113       OSSL_FUNC_asym_cipher_dupctx() should duplicate the provider side
114       asymmetric cipher context in the ctx parameter and return the duplicate
115       copy.
116
117   Encryption Functions
118       OSSL_FUNC_asym_cipher_encrypt_init() initialises a context for an
119       asymmetric encryption given a provider side asymmetric cipher context
120       in the ctx parameter, and a pointer to a provider key object in the
121       provkey parameter.  The params, if not NULL, should be set on the
122       context in a manner similar to using
123       OSSL_FUNC_asym_cipher_set_ctx_params().  The key object should have
124       been previously generated, loaded or imported into the provider using
125       the key management (OSSL_OP_KEYMGMT) operation (see
126       provider-keymgmt(7)>.  OSSL_FUNC_asym_cipher_encrypt() performs the
127       actual encryption itself.  A previously initialised asymmetric cipher
128       context is passed in the ctx parameter.  The data to be encrypted is
129       pointed to by the in parameter which is inlen bytes long.  Unless out
130       is NULL, the encrypted data should be written to the location pointed
131       to by the out parameter and it should not exceed outsize bytes in
132       length.  The length of the encrypted data should be written to *outlen.
133       If out is NULL then the maximum length of the encrypted data should be
134       written to *outlen.
135
136   Decryption Functions
137       OSSL_FUNC_asym_cipher_decrypt_init() initialises a context for an
138       asymmetric decryption given a provider side asymmetric cipher context
139       in the ctx parameter, and a pointer to a provider key object in the
140       provkey parameter.  The params, if not NULL, should be set on the
141       context in a manner similar to using
142       OSSL_FUNC_asym_cipher_set_ctx_params().  The key object should have
143       been previously generated, loaded or imported into the provider using
144       the key management (OSSL_OP_KEYMGMT) operation (see
145       provider-keymgmt(7)>.
146
147       OSSL_FUNC_asym_cipher_decrypt() performs the actual decryption itself.
148       A previously initialised asymmetric cipher context is passed in the ctx
149       parameter.  The data to be decrypted is pointed to by the in parameter
150       which is inlen bytes long.  Unless out is NULL, the decrypted data
151       should be written to the location pointed to by the out parameter and
152       it should not exceed outsize bytes in length.  The length of the
153       decrypted data should be written to *outlen.  If out is NULL then the
154       maximum length of the decrypted data should be written to *outlen.
155
156   Asymmetric Cipher Parameters
157       See OSSL_PARAM(3) for further details on the parameters structure used
158       by the OSSL_FUNC_asym_cipher_get_ctx_params() and
159       OSSL_FUNC_asym_cipher_set_ctx_params() functions.
160
161       OSSL_FUNC_asym_cipher_get_ctx_params() gets asymmetric cipher
162       parameters associated with the given provider side asymmetric cipher
163       context ctx and stores them in params.  Passing NULL for params should
164       return true.
165
166       OSSL_FUNC_asym_cipher_set_ctx_params() sets the asymmetric cipher
167       parameters associated with the given provider side asymmetric cipher
168       context ctx to params.  Any parameter settings are additional to any
169       that were previously set.  Passing NULL for params should return true.
170
171       Parameters currently recognised by built-in asymmetric cipher
172       algorithms are as follows.  Not all parameters are relevant to, or are
173       understood by all asymmetric cipher algorithms:
174
175       "pad-mode" (OSSL_ASYM_CIPHER_PARAM_PAD_MODE) <integer>
176           The type of padding to be used. The interpretation of this value
177           will depend on the algorithm in use. The default provider
178           understands these RSA padding modes: 1 (RSA_PKCS1_PADDING), 3
179           (RSA_NO_PADDING), 4 (RSA_PKCS1_OAEP_PADDING), 5 (RSA_X931_PADDING),
180           6 (RSA_PKCS1_PSS_PADDING) and 7 (RSA_PKCS1_WITH_TLS_PADDING). See
181           EVP_PKEY_CTX_set_rsa_padding(3) for further details.
182
183       "digest" (OSSL_ASYM_CIPHER_PARAM_OAEP_DIGEST) <UTF8 string>
184           Gets or sets the name of the OAEP digest algorithm used when OAEP
185           padding is in use.
186
187       "digest" (OSSL_ASYM_CIPHER_PARAM_DIGEST) <UTF8 string>
188           Gets or sets the name of the digest algorithm used by the algorithm
189           (where applicable).
190
191       "digest-props" (OSSL_ASYM_CIPHER_PARAM_OAEP_DIGEST_PROPS) <UTF8 string>
192           Gets or sets the properties to use when fetching the OAEP digest
193           algorithm.
194
195       "digest-props" (OSSL_ASYM_CIPHER_PARAM_DIGEST_PROPS) <UTF8 string>
196           Gets or sets the properties to use when fetching the cipher digest
197           algorithm.
198
199       "mgf1-digest" (OSSL_ASYM_CIPHER_PARAM_MGF1_DIGEST) <UTF8 string>
200           Gets or sets the name of the MGF1 digest algorithm used when OAEP
201           or PSS padding is in use.
202
203       "mgf1-digest-props" (OSSL_ASYM_CIPHER_PARAM_MGF1_DIGEST_PROPS) <UTF8
204       string>
205           Gets or sets the properties to use when fetching the MGF1 digest
206           algorithm.
207
208       "oaep-label" (OSSL_ASYM_CIPHER_PARAM_OAEP_LABEL) <octet string>
209           Gets or sets the OAEP label used when OAEP padding is in use.
210
211       "tls-client-version" (OSSL_ASYM_CIPHER_PARAM_TLS_CLIENT_VERSION)
212       <unsigned integer>
213           The TLS protocol version first requested by the client. See
214           RSA_PKCS1_WITH_TLS_PADDING on the page
215           EVP_PKEY_CTX_set_rsa_padding(3).
216
217       "tls-negotiated-version" (OSSL_ASYM_CIPHER_PARAM_TLS_CLIENT_VERSION)
218       <unsigned integer>
219           The negotiated TLS protocol version. See RSA_PKCS1_WITH_TLS_PADDING
220           on the page EVP_PKEY_CTX_set_rsa_padding(3).
221
222       OSSL_FUNC_asym_cipher_gettable_ctx_params() and
223       OSSL_FUNC_asym_cipher_settable_ctx_params() get a constant OSSL_PARAM
224       array that describes the gettable and settable parameters, i.e.
225       parameters that can be used with OSSL_FUNC_asym_cipherget_ctx_params()
226       and OSSL_FUNC_asym_cipher_set_ctx_params() respectively.  See
227       OSSL_PARAM(3) for the use of OSSL_PARAM as parameter descriptor.
228

RETURN VALUES

230       OSSL_FUNC_asym_cipher_newctx() and OSSL_FUNC_asym_cipher_dupctx()
231       should return the newly created provider side asymmetric cipher
232       context, or NULL on failure.
233
234       All other functions should return 1 for success or 0 on error.
235

SEE ALSO

237       provider(7)
238

HISTORY

240       The provider ASYM_CIPHER interface was introduced in OpenSSL 3.0.
241
243       Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved.
244
245       Licensed under the Apache License 2.0 (the "License").  You may not use
246       this file except in compliance with the License.  You can obtain a copy
247       in the file LICENSE in the source distribution or at
248       <https://www.openssl.org/source/license.html>.
249
250
251
2523.0.5                             2022-11-01       PROVIDER-ASYM_CIPHER(7ossl)
Impressum