1=pod 2 3=head1 NAME 4 5provider-skeymgmt - The SKEYMGMT library E<lt>-E<gt> provider functions 6 7=head1 SYNOPSIS 8 9 #include <openssl/core_dispatch.h> 10 11 /* 12 * None of these are actual functions, but are displayed like this for 13 * the function signatures for functions that are offered as function 14 * pointers in OSSL_DISPATCH arrays. 15 */ 16 17 /* Key object destruction */ 18 void OSSL_FUNC_skeymgmt_free(void *keydata); 19 20 /* Key object import and export functions */ 21 void *OSSL_FUNC_skeymgmt_import(void *provctx, int selection, 22 const OSSL_PARAM params[]); 23 int OSSL_FUNC_skeymgmt_export(void *keydata, int selection, 24 OSSL_CALLBACK *param_cb, void *cbarg); 25 void *OSSL_FUNC_skeymgmt_generate(void *provctx, 26 const OSSL_PARAM params[]); 27 const OSSL_PARAM *OSSL_FUNC_skeymgmt_gen_settable_params(void *provctx); 28 const OSSL_PARAM *OSSL_FUNC_skeymgmt_imp_settable_params(void *provctx); 29 const char *OSSL_FUNC_skeymgmt_get_key_id(void *keydata); 30 31=head1 DESCRIPTION 32 33The SKEYMGMT operation doesn't have much public visibility in the OpenSSL 34libraries, rather it is an internal operation that is designed to work 35with operations that use opaque symmetric keys objects. 36 37The SKEYMGMT operation shares knowledge with the operations it works with, 38therefore the SKEYMGMT and the algorithms which use it must belong to the same 39provider. The OpenSSL libraries will ensure that they do. 40 41The primary responsibility of the SKEYMGMT operation is to hold the 42provider side key data for the OpenSSL library EVP_SKEY structure. 43 44All "functions" mentioned here are passed as function pointers between 45F<libcrypto> and the provider in L<OSSL_DISPATCH(3)> arrays via 46L<OSSL_ALGORITHM(3)> arrays that are returned by the provider's 47provider_query_operation() function 48(see L<provider-base(7)/Provider Functions>). 49 50All these "functions" have a corresponding function type definition 51named B<OSSL_FUNC_{name}_fn>, and a helper function to retrieve the 52function pointer from a L<OSSL_DISPATCH(3)> element named 53B<OSSL_FUNC_{name}>. 54 55L<OSSL_DISPATCH(3)> arrays are indexed by numbers that are provided as 56macros in L<openssl-core_dispatch.h(7)>, as follows: 57 58 OSSL_FUNC_skeymgmt_free OSSL_FUNC_SKEYMGMT_FREE 59 60 OSSL_FUNC_skeymgmt_import OSSL_FUNC_SKEYMGMT_IMPORT 61 OSSL_FUNC_skeymgmt_export OSSL_FUNC_SKEYMGMT_EXPORT 62 63 OSSL_FUNC_skeymgmt_generate OSSL_FUNC_SKEYMGMT_GENERATE 64 65 OSSL_FUNC_skeymgmt_get_key_id OSSL_FUNC_SKEYMGMT_GET_KEY_ID 66 OSSL_FUNC_skeymgmt_imp_settable_params OSSL_FUNC_SKEYMGMT_IMP_SETTABLE_PARAMS 67 OSSL_FUNC_skeymgmt_gen_settable_params OSSL_FUNC_SKEYMGMT_GEN_SETTABLE_PARAMS 68 69The SKEYMGMT management is inspired by KEYMGMT but is simpler. 70 71=head2 Key Objects 72 73A key object is a collection of data for an symmetric key, and is 74represented as I<keydata> in this manual. 75 76The exact contents of a key object are defined by the provider, and it 77is assumed that different operations in one and the same provider use 78the exact same structure to represent this collection of data, so that 79for example, a key object that has been created using the SKEYMGMT 80interface can be passed as is to other algorithms from the same provider 81operations, such as OSSL_FUNC_mac_init_opaque() (see 82L<provider-mac(7)>). 83 84With the export SKEYMGMT function, it's possible to select a specific 85subset of data to handle, governed by the bits in a I<selection> 86indicator. The bits are: 87 88=over 4 89 90=item B<OSSL_SKEYMGMT_SELECT_SECRET_KEY> 91 92Indicating that the secret key raw bytes in a key object should be 93included. 94 95=item B<OSSL_SKEYMGMT_SELECT_PARAMETERS> 96 97Indicating that the parameters in a key object should be 98included. 99 100=back 101 102Combined selector bits are also defined for easier use: 103 104=over 4 105 106=item B<OSSL_SKEYMGMT_SELECT_ALL> 107 108Indicating that everything in a key object should be included. 109 110=back 111 112The exact interpretation of those bits or how they combine is left to 113each function where you can specify a selector. 114 115=head2 Destructing Function 116 117OSSL_FUNC_skeymgmt_free() should free the passed I<keydata>. 118 119=head2 Key Object Import and Export Functions 120 121OSSL_FUNC_skeymgmt_import() should import data into I<keydata> with values 122taken from the L<OSSL_PARAM(3)> array I<params>. It allocates the I<keydata> 123object (there is no separate allocation function). 124 125OSSL_FUNC_skeymgmt_imp_settable_params() returns a list of parameters that can 126be provided to the OSSL_FUNC_skeymgmt_import() function. 127 128OSSL_FUNC_skeymgmt_export() should extract values indicated by I<selection> 129from I<keydata>, create an L<OSSL_PARAM(3)> array with them and call 130I<param_cb> with that array as well as the given I<cbarg>. 131The passed L<OSSL_PARAM(3)> array is transient and is freed upon the return from I<param_cb>. 132 133=head2 Key Object Generation Functions 134 135OSSL_FUNC_skeymgmt_generate() creates a new key according to the values 136taken from the L<OSSL_PARAM(3)> array I<params>. It allocates the I<keydata> 137object. 138 139OSSL_FUNC_skeymgmt_gen_settable_params() returns a list of parameters that can 140be provided to the OSSL_FUNC_skeymgmt_generate() function. 141 142=head2 Key Object Information functions 143 144OSSL_FUNC_skeymgmt_get_key_id() returns a NUL-terminated string identifying the 145particular key. The returned string will be freed by a call to EVP_SKEY_free() 146so callers need to copy it themselves if they want to preserve the value past 147the key lifetime. The purpose of this function is providing a printable string 148that can help users to access the specific key. The content of this string is 149provider-specific. 150 151=head2 Common Import and Export Parameters 152 153See L<OSSL_PARAM(3)> for further details on the parameters structure. 154 155Common information parameters currently recognised by built-in 156skeymgmt algorithms are as follows: 157 158=over 4 159 160=item "raw-bytes" (B<SKEY_PARAM_RAW_BYTES>) <octet string> 161 162The value represents symmetric key as a byte array. 163 164=item "key-length" (B<SKEY_PARAM_KEY_LENGTH>) <integer> 165 166The value is the byte length of the given key. 167 168=back 169 170=head1 RETURN VALUES 171 172OSSL_FUNC_skeymgmt_import() and OSSL_FUNC_skeymgmt_generate() return a pointer 173to an allocated object on success and NULL on error. 174 175OSSL_FUNC_skeymgmt_export() returns 1 for success or 0 on error. 176 177OSSL_FUNC_skeymgmt_get_key_id() returns a pointer to a 0-terminated string or NULL. 178 179OSSL_FUNC_skeymgmt_gen_settable_params() and OSSL_FUNC_skeymgmt_imp_settable_params() 180return references to an array of B<OSSL_PARAM> which can be NULL if there are 181no settable parameters. 182 183=head1 SEE ALSO 184 185L<provider(7)>, L<EVP_SKEY(3)>, L<EVP_KEYMGMT(3)> 186 187=head1 HISTORY 188 189The SKEYMGMT interface was introduced in OpenSSL 3.5. 190 191=head1 COPYRIGHT 192 193Copyright 2024-2025 The OpenSSL Project Authors. All Rights Reserved. 194 195Licensed under the Apache License 2.0 (the "License"). You may not use 196this file except in compliance with the License. You can obtain a copy 197in the file LICENSE in the source distribution or at 198L<https://www.openssl.org/source/license.html>. 199 200=cut 201