.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "EVP_SKEY 3ssl" .TH EVP_SKEY 3ssl 2025-04-10 3.5.0 OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH 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 .SH SYNOPSIS .IX Header "SYNOPSIS" .Vb 1 \& #include \& \& 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); .Ve .SH DESCRIPTION .IX Header "DESCRIPTION" \&\fBEVP_SKEY\fR 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 \fBEVP_SKEYMGMT\fR\|(3). .PP Conceptually, an \fBEVP_SKEY\fR internal key may hold a symmetric key, and along with those, key parameters if the key type requires them. .PP The \fBEVP_SKEY_generate()\fR functions creates a new \fBEVP_SKEY\fR object and initializes it according to the \fBparams\fR argument. .PP The \fBEVP_SKEY_import()\fR function allocates an empty \fBEVP_SKEY\fR structure which is used by OpenSSL to store symmetric keys, assigns the \&\fBEVP_SKEYMGMT\fR object associated with the key, and initializes the object from the \fBparams\fR argument. .PP The \fBEVP_SKEY_import_raw_key()\fR function is a helper that creates an \fBEVP_SKEY\fR object containing the raw byte representation of the symmetric keys. .PP The \fBEVP_SKEY_export()\fR function extracts values from a key \fIskey\fR using the \&\fIselection\fR. \fIselection\fR is described below. It uses a callback \fIexport_cb\fR that gets passed the value of \fIexport_cbarg\fR. See \fBopenssl\-core.h\fR\|(7) for more information about the callback. Note that the \fBOSSL_PARAM\fR\|(3) array that is passed to the callback is not persistent after the callback returns. .PP The \fBEVP_SKEY_get0_raw_key()\fR 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. .PP The \fBEVP_SKEY_get0_key_id()\fR 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. .PP The \fBEVP_SKEY_get0_skeymgmt_name()\fR and \fBEVP_SKEY_get0_provider_name()\fR return the names of the associated EVP_SKEYMGMT object and its provider correspondingly. .PP \&\fBEVP_SKEY_up_ref()\fR increments the reference count of \fIkey\fR. .PP \&\fBEVP_SKEY_free()\fR decrements the reference count of \fIkey\fR and, if the reference count is zero, frees it. If \fIkey\fR is NULL, nothing is done. .PP \&\fBEVP_SKEY_is_a()\fR checks if the key type of \fIskey\fR is \fIname\fR. .PP \&\fBEVP_SKEY_to_provider()\fR simplifies the task of importing a \fIskey\fR into a different provider identified by \fIprov\fR. If \fIprov\fR is NULL, the default provider for the key type identified via \fIskey\fR is used. .SS Selections .IX Subsection "Selections" The following constants can be used for \fIselection\fR: .IP \fBOSSL_SKEYMGMT_SELECT_SECRET_KEY\fR 4 .IX Item "OSSL_SKEYMGMT_SELECT_SECRET_KEY" Only the raw key representation will be selected. .IP \fBOSSL_SKEYMGMT_SELECT_PARAMETERS\fR 4 .IX Item "OSSL_SKEYMGMT_SELECT_PARAMETERS" Only the key parameters will be selected. This includes optional key parameters. .IP \fBOSSL_SKEYMGMT_SELECT_ALL\fR 4 .IX Item "OSSL_SKEYMGMT_SELECT_ALL" All parameters will be selected. .SH NOTES .IX Header "NOTES" The \fBEVP_SKEY\fR structure is used by various OpenSSL functions which require a general symmetric key without reference to any particular algorithm. .PP The \fBEVP_SKEY_to_provider()\fR function will fail and return NULL if the origin key \fIskey\fR cannot be exported from its provider. .SH "RETURN VALUES" .IX Header "RETURN VALUES" \&\fBEVP_SKEY_generate()\fR, \fBEVP_SKEY_import()\fR and \fBEVP_SKEY_import_raw_key()\fR return either the newly allocated \fBEVP_SKEY\fR structure or NULL if an error occurred. .PP \&\fBEVP_SKEY_get0_key_id()\fR returns either a valid pointer or NULL. .PP \&\fBEVP_SKEY_up_ref()\fR returns 1 for success and 0 on failure. .PP \&\fBEVP_SKEY_export()\fR and \fBEVP_SKEY_get0_raw_key()\fR return 1 for success and 0 on failure. .PP \&\fBEVP_SKEY_get0_skeymgmt_name()\fR and \fBEVP_SKEY_get0_provider_name()\fR return the names of the associated EVP_SKEYMGMT object and its provider correspondigly. .PP \&\fBEVP_SKEY_is_a()\fR returns 1 if \fIskey\fR has the key type \fIname\fR, otherwise 0. .PP \&\fBEVP_SKEY_to_provider()\fR returns a new \fBEVP_SKEY\fR suitable for operations with the \fIprov\fR provider or NULL in case of failure. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fBEVP_SKEYMGMT\fR\|(3), \fBprovider\fR\|(7), \fBOSSL_PARAM\fR\|(3) .SH HISTORY .IX Header "HISTORY" The \fBEVP_SKEY\fR API and functions \fBEVP_SKEY_export()\fR, \&\fBEVP_SKEY_free()\fR, \fBEVP_SKEY_get0_raw_key()\fR, \fBEVP_SKEY_import()\fR, \&\fBEVP_SKEY_import_raw_key()\fR, \fBEVP_SKEY_up_ref()\fR, \fBEVP_SKEY_generate()\fR, \&\fBEVP_SKEY_get0_key_id()\fR, \fBEVP_SKEY_get0_provider_name()\fR, \&\fBEVP_SKEY_get0_skeymgmt_name()\fR, \fBEVP_SKEY_is_a()\fR, \fBEVP_SKEY_to_provider()\fR were introduced in OpenSSL 3.5. .SH COPYRIGHT .IX Header "COPYRIGHT" Copyright 2025 The OpenSSL Project Authors. All Rights Reserved. .PP 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 .