mirror of https://github.com/openssl/openssl.git
163 lines
6.1 KiB
Plaintext
163 lines
6.1 KiB
Plaintext
=pod
|
|
|
|
=head1 NAME
|
|
|
|
EVP_SKEY, EVP_SKEY_generate,
|
|
EVP_SKEY_import, EVP_SKEY_import_raw_key, EVP_SKEY_up_ref,
|
|
EVP_SKEY_export, EVP_SKEY_get0_raw_key, EVP_SKEY_get0_key_id,
|
|
EVP_SKEY_get0_skeymgmt_name, EVP_SKEY_get0_provider_name,
|
|
EVP_SKEY_free, EVP_SKEY_is_a, EVP_SKEY_to_provider
|
|
- opaque symmetric key allocation and handling functions
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
#include <openssl/evp.h>
|
|
|
|
typedef evp_skey_st EVP_SKEY;
|
|
|
|
EVP_SKEY *EVP_SKEY_generate(OSSL_LIB_CTX *libctx, const char *skeymgmtname,
|
|
const char *propquery, const OSSL_PARAM *params);
|
|
EVP_SKEY *EVP_SKEY_import(OSSL_LIB_CTX *libctx, const char *skeymgmtname,
|
|
const char *propquery,
|
|
int selection, const OSSL_PARAM *params);
|
|
EVP_SKEY *EVP_SKEY_import_raw_key(OSSL_LIB_CTX *libctx, const char *skeymgmtname,
|
|
unsigned char *key, size_t *len,
|
|
const char *propquery);
|
|
int EVP_SKEY_export(const EVP_SKEY *skey, int selection,
|
|
OSSL_CALLBACK *export_cb, void *export_cbarg);
|
|
int EVP_SKEY_get0_raw_key(const EVP_SKEY *skey, const unsigned char **key,
|
|
size_t *len);
|
|
const char *EVP_SKEY_get0_key_id(const EVP_SKEY *skey);
|
|
|
|
const char *EVP_SKEY_get0_skeymgmt_name(const EVP_SKEY *skey);
|
|
const char *EVP_SKEY_get0_provider_name(const EVP_SKEY *skey);
|
|
|
|
int EVP_SKEY_up_ref(EVP_SKEY *key);
|
|
void EVP_SKEY_free(EVP_SKEY *key);
|
|
int EVP_SKEY_is_a(const EVP_SKEY *skey, const char *name);
|
|
EVP_SKEY *EVP_SKEY_to_provider(EVP_SKEY *skey, OSSL_LIB_CTX *libctx,
|
|
OSSL_PROVIDER *prov, const char *propquery);
|
|
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
B<EVP_SKEY> is a generic structure to hold symmetric keys as opaque objects.
|
|
The keys themselves are often referred to as the "internal key", and are handled by
|
|
providers using L<EVP_SKEYMGMT(3)>.
|
|
|
|
Conceptually, an B<EVP_SKEY> internal key may hold a symmetric key, and along
|
|
with those, key parameters if the key type requires them.
|
|
|
|
The EVP_SKEY_generate() functions creates a new B<EVP_SKEY> object and
|
|
initializes it according to the B<params> argument.
|
|
|
|
The EVP_SKEY_import() function allocates an empty B<EVP_SKEY> structure
|
|
which is used by OpenSSL to store symmetric keys, assigns the
|
|
B<EVP_SKEYMGMT> object associated with the key, and initializes the object from
|
|
the B<params> argument.
|
|
|
|
The EVP_SKEY_import_raw_key() function is a helper that creates an B<EVP_SKEY> object
|
|
containing the raw byte representation of the symmetric keys.
|
|
|
|
The EVP_SKEY_export() function extracts values from a key I<skey> using the
|
|
I<selection>. I<selection> is described below. It uses a callback I<export_cb>
|
|
that gets passed the value of I<export_cbarg>. See L<openssl-core.h(7)> for
|
|
more information about the callback. Note that the L<OSSL_PARAM(3)> array that
|
|
is passed to the callback is not persistent after the callback returns.
|
|
|
|
The EVP_SKEY_get0_raw_key() returns a pointer to a raw key bytes to the passed
|
|
address and sets the key len. The returned address is managed by the internal
|
|
key management and shouldn't be freed explicitly. The operation can fail when
|
|
the underlying key management doesn't support export of the secret key.
|
|
|
|
The EVP_SKEY_get0_key_id() returns a NUL-terminated string providing some
|
|
human-readable identifier of the key if provided by the underlying key
|
|
management. The pointer becomes invalid after freeing the EVP_SKEY object.
|
|
|
|
The EVP_SKEY_get0_skeymgmt_name() and EVP_SKEY_get0_provider_name() return the
|
|
names of the associated EVP_SKEYMGMT object and its provider correspondingly.
|
|
|
|
EVP_SKEY_up_ref() increments the reference count of I<key>.
|
|
|
|
EVP_SKEY_free() decrements the reference count of I<key> and, if the reference
|
|
count is zero, frees it. If I<key> is NULL, nothing is done.
|
|
|
|
EVP_SKEY_is_a() checks if the key type of I<skey> is I<name>.
|
|
|
|
EVP_SKEY_to_provider() simplifies the task of importing a I<skey> into a
|
|
different provider identified by I<prov>. If I<prov> is NULL, the default
|
|
provider for the key type identified via I<skey> is used.
|
|
|
|
=head2 Selections
|
|
|
|
The following constants can be used for I<selection>:
|
|
|
|
=over 4
|
|
|
|
=item B<OSSL_SKEYMGMT_SELECT_SECRET_KEY>
|
|
|
|
Only the raw key representation will be selected.
|
|
|
|
=item B<OSSL_SKEYMGMT_SELECT_PARAMETERS>
|
|
|
|
Only the key parameters will be selected. This includes optional key
|
|
parameters.
|
|
|
|
=item B<OSSL_SKEYMGMT_SELECT_ALL>
|
|
|
|
All parameters will be selected.
|
|
|
|
=back
|
|
|
|
=head1 NOTES
|
|
|
|
The B<EVP_SKEY> structure is used by various OpenSSL functions which require a
|
|
general symmetric key without reference to any particular algorithm.
|
|
|
|
The EVP_SKEY_to_provider() function will fail and return NULL if the origin
|
|
key I<skey> cannot be exported from its provider.
|
|
|
|
=head1 RETURN VALUES
|
|
|
|
EVP_SKEY_generate(), EVP_SKEY_import() and EVP_SKEY_import_raw_key() return
|
|
either the newly allocated B<EVP_SKEY> structure or NULL if an error occurred.
|
|
|
|
EVP_SKEY_get0_key_id() returns either a valid pointer or NULL.
|
|
|
|
EVP_SKEY_up_ref() returns 1 for success and 0 on failure.
|
|
|
|
EVP_SKEY_export() and EVP_SKEY_get0_raw_key() return 1 for success and 0 on failure.
|
|
|
|
EVP_SKEY_get0_skeymgmt_name() and EVP_SKEY_get0_provider_name() return the
|
|
names of the associated EVP_SKEYMGMT object and its provider correspondigly.
|
|
|
|
EVP_SKEY_is_a() returns 1 if I<skey> has the key type I<name>,
|
|
otherwise 0.
|
|
|
|
EVP_SKEY_to_provider() returns a new B<EVP_SKEY> suitable for operations with
|
|
the I<prov> provider or NULL in case of failure.
|
|
|
|
=head1 SEE ALSO
|
|
|
|
L<EVP_SKEYMGMT(3)>, L<provider(7)>, L<OSSL_PARAM(3)>
|
|
|
|
=head1 HISTORY
|
|
|
|
The B<EVP_SKEY> API and functions EVP_SKEY_export(),
|
|
EVP_SKEY_free(), EVP_SKEY_get0_raw_key(), EVP_SKEY_import(),
|
|
EVP_SKEY_import_raw_key(), EVP_SKEY_up_ref(), EVP_SKEY_generate(),
|
|
EVP_SKEY_get0_key_id(), EVP_SKEY_get0_provider_name(),
|
|
EVP_SKEY_get0_skeymgmt_name(), EVP_SKEY_is_a(), EVP_SKEY_to_provider()
|
|
were introduced in OpenSSL 3.5.
|
|
|
|
=head1 COPYRIGHT
|
|
|
|
Copyright 2025 The OpenSSL Project Authors. All Rights Reserved.
|
|
|
|
Licensed under the Apache License 2.0 (the "License"). You may not use
|
|
this file except in compliance with the License. You can obtain a copy
|
|
in the file LICENSE in the source distribution or at
|
|
L<https://www.openssl.org/source/license.html>.
|
|
|
|
=cut
|