1*e7be843bSPierre Pronchery=pod 2*e7be843bSPierre Pronchery 3*e7be843bSPierre Pronchery=head1 NAME 4*e7be843bSPierre Pronchery 5*e7be843bSPierre ProncheryEVP_SKEY, EVP_SKEY_generate, 6*e7be843bSPierre ProncheryEVP_SKEY_import, EVP_SKEY_import_raw_key, EVP_SKEY_up_ref, 7*e7be843bSPierre ProncheryEVP_SKEY_export, EVP_SKEY_get0_raw_key, EVP_SKEY_get0_key_id, 8*e7be843bSPierre ProncheryEVP_SKEY_get0_skeymgmt_name, EVP_SKEY_get0_provider_name, 9*e7be843bSPierre ProncheryEVP_SKEY_free, EVP_SKEY_is_a, EVP_SKEY_to_provider 10*e7be843bSPierre Pronchery- opaque symmetric key allocation and handling functions 11*e7be843bSPierre Pronchery 12*e7be843bSPierre Pronchery=head1 SYNOPSIS 13*e7be843bSPierre Pronchery 14*e7be843bSPierre Pronchery #include <openssl/evp.h> 15*e7be843bSPierre Pronchery 16*e7be843bSPierre Pronchery typedef evp_skey_st EVP_SKEY; 17*e7be843bSPierre Pronchery 18*e7be843bSPierre Pronchery EVP_SKEY *EVP_SKEY_generate(OSSL_LIB_CTX *libctx, const char *skeymgmtname, 19*e7be843bSPierre Pronchery const char *propquery, const OSSL_PARAM *params); 20*e7be843bSPierre Pronchery EVP_SKEY *EVP_SKEY_import(OSSL_LIB_CTX *libctx, const char *skeymgmtname, 21*e7be843bSPierre Pronchery const char *propquery, 22*e7be843bSPierre Pronchery int selection, const OSSL_PARAM *params); 23*e7be843bSPierre Pronchery EVP_SKEY *EVP_SKEY_import_raw_key(OSSL_LIB_CTX *libctx, const char *skeymgmtname, 24*e7be843bSPierre Pronchery unsigned char *key, size_t *len, 25*e7be843bSPierre Pronchery const char *propquery); 26*e7be843bSPierre Pronchery int EVP_SKEY_export(const EVP_SKEY *skey, int selection, 27*e7be843bSPierre Pronchery OSSL_CALLBACK *export_cb, void *export_cbarg); 28*e7be843bSPierre Pronchery int EVP_SKEY_get0_raw_key(const EVP_SKEY *skey, const unsigned char **key, 29*e7be843bSPierre Pronchery size_t *len); 30*e7be843bSPierre Pronchery const char *EVP_SKEY_get0_key_id(const EVP_SKEY *skey); 31*e7be843bSPierre Pronchery 32*e7be843bSPierre Pronchery const char *EVP_SKEY_get0_skeymgmt_name(const EVP_SKEY *skey); 33*e7be843bSPierre Pronchery const char *EVP_SKEY_get0_provider_name(const EVP_SKEY *skey); 34*e7be843bSPierre Pronchery 35*e7be843bSPierre Pronchery int EVP_SKEY_up_ref(EVP_SKEY *key); 36*e7be843bSPierre Pronchery void EVP_SKEY_free(EVP_SKEY *key); 37*e7be843bSPierre Pronchery int EVP_SKEY_is_a(const EVP_SKEY *skey, const char *name); 38*e7be843bSPierre Pronchery EVP_SKEY *EVP_SKEY_to_provider(EVP_SKEY *skey, OSSL_LIB_CTX *libctx, 39*e7be843bSPierre Pronchery OSSL_PROVIDER *prov, const char *propquery); 40*e7be843bSPierre Pronchery 41*e7be843bSPierre Pronchery 42*e7be843bSPierre Pronchery=head1 DESCRIPTION 43*e7be843bSPierre Pronchery 44*e7be843bSPierre ProncheryB<EVP_SKEY> is a generic structure to hold symmetric keys as opaque objects. 45*e7be843bSPierre ProncheryThe keys themselves are often referred to as the "internal key", and are handled by 46*e7be843bSPierre Proncheryproviders using L<EVP_SKEYMGMT(3)>. 47*e7be843bSPierre Pronchery 48*e7be843bSPierre ProncheryConceptually, an B<EVP_SKEY> internal key may hold a symmetric key, and along 49*e7be843bSPierre Proncherywith those, key parameters if the key type requires them. 50*e7be843bSPierre Pronchery 51*e7be843bSPierre ProncheryThe EVP_SKEY_generate() functions creates a new B<EVP_SKEY> object and 52*e7be843bSPierre Proncheryinitializes it according to the B<params> argument. 53*e7be843bSPierre Pronchery 54*e7be843bSPierre ProncheryThe EVP_SKEY_import() function allocates an empty B<EVP_SKEY> structure 55*e7be843bSPierre Proncherywhich is used by OpenSSL to store symmetric keys, assigns the 56*e7be843bSPierre ProncheryB<EVP_SKEYMGMT> object associated with the key, and initializes the object from 57*e7be843bSPierre Proncherythe B<params> argument. 58*e7be843bSPierre Pronchery 59*e7be843bSPierre ProncheryThe EVP_SKEY_import_raw_key() function is a helper that creates an B<EVP_SKEY> object 60*e7be843bSPierre Proncherycontaining the raw byte representation of the symmetric keys. 61*e7be843bSPierre Pronchery 62*e7be843bSPierre ProncheryThe EVP_SKEY_export() function extracts values from a key I<skey> using the 63*e7be843bSPierre ProncheryI<selection>. I<selection> is described below. It uses a callback I<export_cb> 64*e7be843bSPierre Proncherythat gets passed the value of I<export_cbarg>. See L<openssl-core.h(7)> for 65*e7be843bSPierre Proncherymore information about the callback. Note that the L<OSSL_PARAM(3)> array that 66*e7be843bSPierre Proncheryis passed to the callback is not persistent after the callback returns. 67*e7be843bSPierre Pronchery 68*e7be843bSPierre ProncheryThe EVP_SKEY_get0_raw_key() returns a pointer to a raw key bytes to the passed 69*e7be843bSPierre Proncheryaddress and sets the key len. The returned address is managed by the internal 70*e7be843bSPierre Proncherykey management and shouldn't be freed explicitly. The operation can fail when 71*e7be843bSPierre Proncherythe underlying key management doesn't support export of the secret key. 72*e7be843bSPierre Pronchery 73*e7be843bSPierre ProncheryThe EVP_SKEY_get0_key_id() returns a NUL-terminated string providing some 74*e7be843bSPierre Proncheryhuman-readable identifier of the key if provided by the underlying key 75*e7be843bSPierre Proncherymanagement. The pointer becomes invalid after freeing the EVP_SKEY object. 76*e7be843bSPierre Pronchery 77*e7be843bSPierre ProncheryThe EVP_SKEY_get0_skeymgmt_name() and EVP_SKEY_get0_provider_name() return the 78*e7be843bSPierre Proncherynames of the associated EVP_SKEYMGMT object and its provider correspondingly. 79*e7be843bSPierre Pronchery 80*e7be843bSPierre ProncheryEVP_SKEY_up_ref() increments the reference count of I<key>. 81*e7be843bSPierre Pronchery 82*e7be843bSPierre ProncheryEVP_SKEY_free() decrements the reference count of I<key> and, if the reference 83*e7be843bSPierre Proncherycount is zero, frees it. If I<key> is NULL, nothing is done. 84*e7be843bSPierre Pronchery 85*e7be843bSPierre ProncheryEVP_SKEY_is_a() checks if the key type of I<skey> is I<name>. 86*e7be843bSPierre Pronchery 87*e7be843bSPierre ProncheryEVP_SKEY_to_provider() simplifies the task of importing a I<skey> into a 88*e7be843bSPierre Proncherydifferent provider identified by I<prov>. If I<prov> is NULL, the default 89*e7be843bSPierre Proncheryprovider for the key type identified via I<skey> is used. 90*e7be843bSPierre Pronchery 91*e7be843bSPierre Pronchery=head2 Selections 92*e7be843bSPierre Pronchery 93*e7be843bSPierre ProncheryThe following constants can be used for I<selection>: 94*e7be843bSPierre Pronchery 95*e7be843bSPierre Pronchery=over 4 96*e7be843bSPierre Pronchery 97*e7be843bSPierre Pronchery=item B<OSSL_SKEYMGMT_SELECT_SECRET_KEY> 98*e7be843bSPierre Pronchery 99*e7be843bSPierre ProncheryOnly the raw key representation will be selected. 100*e7be843bSPierre Pronchery 101*e7be843bSPierre Pronchery=item B<OSSL_SKEYMGMT_SELECT_PARAMETERS> 102*e7be843bSPierre Pronchery 103*e7be843bSPierre ProncheryOnly the key parameters will be selected. This includes optional key 104*e7be843bSPierre Proncheryparameters. 105*e7be843bSPierre Pronchery 106*e7be843bSPierre Pronchery=item B<OSSL_SKEYMGMT_SELECT_ALL> 107*e7be843bSPierre Pronchery 108*e7be843bSPierre ProncheryAll parameters will be selected. 109*e7be843bSPierre Pronchery 110*e7be843bSPierre Pronchery=back 111*e7be843bSPierre Pronchery 112*e7be843bSPierre Pronchery=head1 NOTES 113*e7be843bSPierre Pronchery 114*e7be843bSPierre ProncheryThe B<EVP_SKEY> structure is used by various OpenSSL functions which require a 115*e7be843bSPierre Proncherygeneral symmetric key without reference to any particular algorithm. 116*e7be843bSPierre Pronchery 117*e7be843bSPierre ProncheryThe EVP_SKEY_to_provider() function will fail and return NULL if the origin 118*e7be843bSPierre Proncherykey I<skey> cannot be exported from its provider. 119*e7be843bSPierre Pronchery 120*e7be843bSPierre Pronchery=head1 RETURN VALUES 121*e7be843bSPierre Pronchery 122*e7be843bSPierre ProncheryEVP_SKEY_generate(), EVP_SKEY_import() and EVP_SKEY_import_raw_key() return 123*e7be843bSPierre Proncheryeither the newly allocated B<EVP_SKEY> structure or NULL if an error occurred. 124*e7be843bSPierre Pronchery 125*e7be843bSPierre ProncheryEVP_SKEY_get0_key_id() returns either a valid pointer or NULL. 126*e7be843bSPierre Pronchery 127*e7be843bSPierre ProncheryEVP_SKEY_up_ref() returns 1 for success and 0 on failure. 128*e7be843bSPierre Pronchery 129*e7be843bSPierre ProncheryEVP_SKEY_export() and EVP_SKEY_get0_raw_key() return 1 for success and 0 on failure. 130*e7be843bSPierre Pronchery 131*e7be843bSPierre ProncheryEVP_SKEY_get0_skeymgmt_name() and EVP_SKEY_get0_provider_name() return the 132*e7be843bSPierre Proncherynames of the associated EVP_SKEYMGMT object and its provider correspondigly. 133*e7be843bSPierre Pronchery 134*e7be843bSPierre ProncheryEVP_SKEY_is_a() returns 1 if I<skey> has the key type I<name>, 135*e7be843bSPierre Proncheryotherwise 0. 136*e7be843bSPierre Pronchery 137*e7be843bSPierre ProncheryEVP_SKEY_to_provider() returns a new B<EVP_SKEY> suitable for operations with 138*e7be843bSPierre Proncherythe I<prov> provider or NULL in case of failure. 139*e7be843bSPierre Pronchery 140*e7be843bSPierre Pronchery=head1 SEE ALSO 141*e7be843bSPierre Pronchery 142*e7be843bSPierre ProncheryL<EVP_SKEYMGMT(3)>, L<provider(7)>, L<OSSL_PARAM(3)> 143*e7be843bSPierre Pronchery 144*e7be843bSPierre Pronchery=head1 HISTORY 145*e7be843bSPierre Pronchery 146*e7be843bSPierre ProncheryThe B<EVP_SKEY> API and functions EVP_SKEY_export(), 147*e7be843bSPierre ProncheryEVP_SKEY_free(), EVP_SKEY_get0_raw_key(), EVP_SKEY_import(), 148*e7be843bSPierre ProncheryEVP_SKEY_import_raw_key(), EVP_SKEY_up_ref(), EVP_SKEY_generate(), 149*e7be843bSPierre ProncheryEVP_SKEY_get0_key_id(), EVP_SKEY_get0_provider_name(), 150*e7be843bSPierre ProncheryEVP_SKEY_get0_skeymgmt_name(), EVP_SKEY_is_a(), EVP_SKEY_to_provider() 151*e7be843bSPierre Proncherywere introduced in OpenSSL 3.5. 152*e7be843bSPierre Pronchery 153*e7be843bSPierre Pronchery=head1 COPYRIGHT 154*e7be843bSPierre Pronchery 155*e7be843bSPierre ProncheryCopyright 2025 The OpenSSL Project Authors. All Rights Reserved. 156*e7be843bSPierre Pronchery 157*e7be843bSPierre ProncheryLicensed under the Apache License 2.0 (the "License"). You may not use 158*e7be843bSPierre Proncherythis file except in compliance with the License. You can obtain a copy 159*e7be843bSPierre Proncheryin the file LICENSE in the source distribution or at 160*e7be843bSPierre ProncheryL<https://www.openssl.org/source/license.html>. 161*e7be843bSPierre Pronchery 162*e7be843bSPierre Pronchery=cut 163