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