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