diff options
Diffstat (limited to 'secure/lib/libcrypto/man/man3/EVP_SKEY.3')
| -rw-r--r-- | secure/lib/libcrypto/man/man3/EVP_SKEY.3 | 205 |
1 files changed, 205 insertions, 0 deletions
diff --git a/secure/lib/libcrypto/man/man3/EVP_SKEY.3 b/secure/lib/libcrypto/man/man3/EVP_SKEY.3 new file mode 100644 index 000000000000..f77ab2f0b994 --- /dev/null +++ b/secure/lib/libcrypto/man/man3/EVP_SKEY.3 @@ -0,0 +1,205 @@ +.\" -*- 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 3ossl" +.TH EVP_SKEY 3ossl 2025-07-01 3.5.1 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 <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); +.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 +<https://www.openssl.org/source/license.html>. |