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