]>
Commit | Line | Data |
---|---|---|
80f4fd18 SL |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | provider-kem - The kem library E<lt>-E<gt> provider functions | |
6 | ||
7 | =head1 SYNOPSIS | |
8 | ||
9 | =for openssl multiple includes | |
10 | ||
11 | #include <openssl/core_dispatch.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 *OSSL_FUNC_kem_newctx(void *provctx); | |
22 | void OSSL_FUNC_kem_freectx(void *ctx); | |
23 | void *OSSL_FUNC_kem_dupctx(void *ctx); | |
24 | ||
25 | /* Encapsulation */ | |
26 | int OSSL_FUNC_kem_encapsulate_init(void *ctx, void *provkey, const char *name); | |
27 | int OSSL_FUNC_kem_encapsulate(void *ctx, unsigned char *out, size_t *outlen, | |
28 | unsigned char *secret, size_t *secretlen); | |
29 | ||
30 | /* Decapsulation */ | |
31 | int OSSL_FUNC_kem_decapsulate_init(void *ctx, void *provkey, const char *name); | |
32 | int OSSL_FUNC_kem_decapsulate(void *ctx, unsigned char *out, size_t *outlen, | |
33 | const unsigned char *in, size_t inlen); | |
34 | ||
35 | /* KEM parameters */ | |
36 | int OSSL_FUNC_kem_get_ctx_params(void *ctx, OSSL_PARAM params[]); | |
fb67126e | 37 | const OSSL_PARAM *OSSL_FUNC_kem_gettable_ctx_params(void *ctx, void *provctx); |
80f4fd18 | 38 | int OSSL_FUNC_kem_set_ctx_params(void *ctx, const OSSL_PARAM params[]); |
fb67126e | 39 | const OSSL_PARAM *OSSL_FUNC_kem_settable_ctx_params(void *ctx, void *provctx); |
80f4fd18 SL |
40 | |
41 | =head1 DESCRIPTION | |
42 | ||
43 | This documentation is primarily aimed at provider authors. See L<provider(7)> | |
44 | for further information. | |
45 | ||
46 | The asymmetric kem (OSSL_OP_KEM) operation enables providers to | |
47 | implement asymmetric kem algorithms and make them available to applications | |
48 | via the API functions L<EVP_PKEY_encapsulate(3)>, | |
49 | L<EVP_PKEY_decapsulate(3)> and other related functions. | |
50 | ||
51 | All "functions" mentioned here are passed as function pointers between | |
52 | F<libcrypto> and the provider in B<OSSL_DISPATCH> arrays via | |
53 | B<OSSL_ALGORITHM> arrays that are returned by the provider's | |
54 | provider_query_operation() function | |
55 | (see L<provider-base(7)/Provider Functions>). | |
56 | ||
57 | All these "functions" have a corresponding function type definition | |
58 | named B<OSSL_{name}_fn>, and a helper function to retrieve the | |
59 | function pointer from an B<OSSL_DISPATCH> element named | |
60 | B<OSSL_FUNC_{name}>. | |
61 | For example, the "function" OSSL_FUNC_kem_newctx() has these: | |
62 | ||
63 | typedef void *(OSSL_FUNC_kem_newctx_fn)(void *provctx); | |
64 | static ossl_inline OSSL_FUNC_kem_newctx_fn | |
65 | OSSL_FUNC_kem_newctx(const OSSL_DISPATCH *opf); | |
66 | ||
67 | B<OSSL_DISPATCH> arrays are indexed by numbers that are provided as | |
68 | macros in L<openssl-core_dispatch.h(7)>, as follows: | |
69 | ||
70 | OSSL_FUNC_kem_newctx OSSL_FUNC_KEM_NEWCTX | |
71 | OSSL_FUNC_kem_freectx OSSL_FUNC_KEM_FREECTX | |
72 | OSSL_FUNC_kem_dupctx OSSL_FUNC_KEM_DUPCTX | |
73 | ||
74 | OSSL_FUNC_kem_encapsulate_init OSSL_FUNC_KEM_ENCAPSULATE_INIT | |
75 | OSSL_FUNC_kem_encapsulate OSSL_FUNC_KEM_ENCAPSULATE | |
76 | ||
77 | OSSL_FUNC_kem_decapsulate_init OSSL_FUNC_KEM_DECAPSULATE_INIT | |
78 | OSSL_FUNC_kem_decapsulate OSSL_FUNC_KEM_DECAPSULATE | |
79 | ||
80 | OSSL_FUNC_kem_get_ctx_params OSSL_FUNC_KEM_GET_CTX_PARAMS | |
81 | OSSL_FUNC_kem_gettable_ctx_params OSSL_FUNC_KEM_GETTABLE_CTX_PARAMS | |
82 | OSSL_FUNC_kem_set_ctx_params OSSL_FUNC_KEM_SET_CTX_PARAMS | |
83 | OSSL_FUNC_kem_settable_ctx_params OSSL_FUNC_KEM_SETTABLE_CTX_PARAMS | |
84 | ||
85 | An asymmetric kem algorithm implementation may not implement all of these | |
86 | functions. | |
87 | In order to be a consistent set of functions a provider must implement | |
88 | OSSL_FUNC_kem_newctx and OSSL_FUNC_kem_freectx. | |
89 | It must also implement both of OSSL_FUNC_kem_encapsulate_init and | |
90 | OSSL_FUNC_kem_encapsulate, or both of OSSL_FUNC_kem_decapsulate_init and | |
91 | OSSL_FUNC_kem_decapsulate. | |
92 | OSSL_FUNC_kem_get_ctx_params is optional but if it is present then so must | |
93 | OSSL_FUNC_kem_gettable_ctx_params. | |
94 | Similarly, OSSL_FUNC_kem_set_ctx_params is optional but if it is present then | |
95 | so must OSSL_FUNC_kem_settable_ctx_params. | |
96 | ||
97 | An asymmetric kem algorithm must also implement some mechanism for generating, | |
98 | loading or importing keys via the key management (OSSL_OP_KEYMGMT) operation. | |
99 | See L<provider-keymgmt(7)> for further details. | |
100 | ||
101 | =head2 Context Management Functions | |
102 | ||
103 | OSSL_FUNC_kem_newctx() should create and return a pointer to a provider side | |
104 | structure for holding context information during an asymmetric kem operation. | |
105 | A pointer to this context will be passed back in a number of the other | |
106 | asymmetric kem operation function calls. | |
107 | The parameter I<provctx> is the provider context generated during provider | |
108 | initialisation (see L<provider(7)>). | |
109 | ||
110 | OSSL_FUNC_kem_freectx() is passed a pointer to the provider side asymmetric | |
111 | kem context in the I<ctx> parameter. | |
112 | This function should free any resources associated with that context. | |
113 | ||
114 | OSSL_FUNC_kem_dupctx() should duplicate the provider side asymmetric kem | |
115 | context in the I<ctx> parameter and return the duplicate copy. | |
116 | ||
117 | =head2 Asymmetric Key Encapsulation Functions | |
118 | ||
119 | OSSL_FUNC_kem_encapsulate_init() initialises a context for an asymmetric | |
120 | encapsulation given a provider side asymmetric kem context in the I<ctx> | |
121 | parameter, a pointer to a provider key object in the I<provkey> parameter and | |
122 | the I<name> of the algorithm. | |
123 | The key object should have been previously generated, loaded or imported into | |
124 | the provider using the key management (OSSL_OP_KEYMGMT) operation (see | |
125 | provider-keymgmt(7)>. | |
126 | ||
127 | OSSL_FUNC_kem_encapsulate() performs the actual encapsulation itself. | |
128 | A previously initialised asymmetric kem context is passed in the I<ctx> | |
129 | parameter. | |
130 | Unless I<out> is NULL, the data to be encapsulated is internally generated, | |
3e6a0d57 | 131 | and returned into the buffer pointed to by the I<secret> parameter and the |
80f4fd18 SL |
132 | encapsulated data should also be written to the location pointed to by the |
133 | I<out> parameter. The length of the encapsulated data should be written to | |
134 | I<*outlen> and the length of the generated secret should be written to | |
135 | I<*secretlen>. | |
136 | ||
137 | If I<out> is NULL then the maximum length of the encapsulated data should be | |
138 | written to I<*outlen>, and the maximum length of the generated secret should be | |
139 | written to I<*secretlen>. | |
140 | ||
141 | =head2 Decapsulation Functions | |
142 | ||
143 | OSSL_FUNC_kem_decapsulate_init() initialises a context for an asymmetric | |
144 | decapsulation given a provider side asymmetric kem context in the I<ctx> | |
145 | parameter, a pointer to a provider key object in the I<provkey> parameter, and | |
146 | a I<name> of the algorithm. | |
147 | The key object should have been previously generated, loaded or imported into | |
148 | the provider using the key management (OSSL_OP_KEYMGMT) operation (see | |
149 | provider-keymgmt(7)>. | |
150 | ||
151 | OSSL_FUNC_kem_decapsulate() performs the actual decapsulation itself. | |
152 | A previously initialised asymmetric kem context is passed in the I<ctx> | |
153 | parameter. | |
154 | The data to be decapsulated is pointed to by the I<in> parameter which is I<inlen> | |
155 | bytes long. | |
156 | Unless I<out> is NULL, the decapsulated data should be written to the location | |
157 | pointed to by the I<out> parameter. | |
158 | The length of the decapsulated data should be written to I<*outlen>. | |
159 | If I<out> is NULL then the maximum length of the decapsulated data should be | |
160 | written to I<*outlen>. | |
161 | ||
162 | =head2 Asymmetric Key Encapsulation Parameters | |
163 | ||
164 | See L<OSSL_PARAM(3)> for further details on the parameters structure used by | |
165 | the OSSL_FUNC_kem_get_ctx_params() and OSSL_FUNC_kem_set_ctx_params() | |
166 | functions. | |
167 | ||
168 | OSSL_FUNC_kem_get_ctx_params() gets asymmetric kem parameters associated | |
169 | with the given provider side asymmetric kem context I<ctx> and stores them in | |
170 | I<params>. | |
171 | OSSL_FUNC_kem_set_ctx_params() sets the asymmetric kem parameters associated | |
172 | with the given provider side asymmetric kem context I<ctx> to I<params>. | |
173 | Any parameter settings are additional to any that were previously set. | |
174 | ||
175 | No parameters are currently recognised by built-in asymmetric kem algorithms. | |
176 | ||
177 | OSSL_FUNC_kem_gettable_ctx_params() and OSSL_FUNC_kem_settable_ctx_params() | |
178 | get a constant B<OSSL_PARAM> array that describes the gettable and settable | |
179 | parameters, i.e. parameters that can be used with OSSL_FUNC_kem_get_ctx_params() | |
180 | and OSSL_FUNC_kem_set_ctx_params() respectively. | |
181 | See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as parameter descriptor. | |
182 | ||
183 | =head1 RETURN VALUES | |
184 | ||
185 | OSSL_FUNC_kem_newctx() and OSSL_FUNC_kem_dupctx() should return the newly | |
186 | created provider side asymmetric kem context, or NULL on failure. | |
187 | ||
188 | All other functions should return 1 for success or 0 on error. | |
189 | ||
190 | =head1 SEE ALSO | |
191 | ||
192 | L<provider(7)> | |
193 | ||
194 | =head1 HISTORY | |
195 | ||
196 | The provider KEM interface was introduced in OpenSSL 3.0. | |
197 | ||
198 | =head1 COPYRIGHT | |
199 | ||
8020d79b | 200 | Copyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved. |
80f4fd18 SL |
201 | |
202 | Licensed under the Apache License 2.0 (the "License"). You may not use | |
203 | this file except in compliance with the License. You can obtain a copy | |
204 | in the file LICENSE in the source distribution or at | |
205 | L<https://www.openssl.org/source/license.html>. | |
206 | ||
207 | =cut |