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