Debian Codegraph @

upstream/debian-trixie/man3/EVP_SKEY.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "EVP_SKEY 3SSL"
58 .TH EVP_SKEY 3SSL 2026-04-07 3.5.6 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 EVP_SKEY, EVP_SKEY_generate,
65 EVP_SKEY_import, EVP_SKEY_import_raw_key, EVP_SKEY_up_ref,
66 EVP_SKEY_export, EVP_SKEY_get0_raw_key, EVP_SKEY_get0_key_id,
67 EVP_SKEY_get0_skeymgmt_name, EVP_SKEY_get0_provider_name,
68 EVP_SKEY_free, EVP_SKEY_is_a, EVP_SKEY_to_provider
69 \&\- opaque symmetric key allocation and handling functions
70 .SH SYNOPSIS
71 .IX Header "SYNOPSIS"
72 .Vb 1
73 \& #include <openssl/evp.h>
74 \&
75 \& typedef evp_skey_st EVP_SKEY;
76 \&
77 \& EVP_SKEY *EVP_SKEY_generate(OSSL_LIB_CTX *libctx, const char *skeymgmtname,
78 \& const char *propquery, const OSSL_PARAM *params);
79 \& EVP_SKEY *EVP_SKEY_import(OSSL_LIB_CTX *libctx, const char *skeymgmtname,
80 \& const char *propquery,
81 \& int selection, const OSSL_PARAM *params);
82 \& EVP_SKEY *EVP_SKEY_import_raw_key(OSSL_LIB_CTX *libctx, const char *skeymgmtname,
83 \& unsigned char *key, size_t len,
84 \& const char *propquery);
85 \& int EVP_SKEY_export(const EVP_SKEY *skey, int selection,
86 \& OSSL_CALLBACK *export_cb, void *export_cbarg);
87 \& int EVP_SKEY_get0_raw_key(const EVP_SKEY *skey, const unsigned char **key,
88 \& size_t *len);
89 \& const char *EVP_SKEY_get0_key_id(const EVP_SKEY *skey);
90 \&
91 \& const char *EVP_SKEY_get0_skeymgmt_name(const EVP_SKEY *skey);
92 \& const char *EVP_SKEY_get0_provider_name(const EVP_SKEY *skey);
93 \&
94 \& int EVP_SKEY_up_ref(EVP_SKEY *key);
95 \& void EVP_SKEY_free(EVP_SKEY *key);
96 \& int EVP_SKEY_is_a(const EVP_SKEY *skey, const char *name);
97 \& EVP_SKEY *EVP_SKEY_to_provider(EVP_SKEY *skey, OSSL_LIB_CTX *libctx,
98 \& OSSL_PROVIDER *prov, const char *propquery);
99 .Ve
100 .SH DESCRIPTION
101 .IX Header "DESCRIPTION"
102 \&\fBEVP_SKEY\fR is a generic structure to hold symmetric keys as opaque objects.
103 The keys themselves are often referred to as the "internal key", and are handled by
104 providers using \fBEVP_SKEYMGMT\fR\|(3).
105 .PP
106 Conceptually, an \fBEVP_SKEY\fR internal key may hold a symmetric key, and along
107 with those, key parameters if the key type requires them.
108 .PP
109 The \fBEVP_SKEY_generate()\fR functions creates a new \fBEVP_SKEY\fR object and
110 initializes it according to the \fBparams\fR argument.
111 .PP
112 The \fBEVP_SKEY_import()\fR function allocates an empty \fBEVP_SKEY\fR structure
113 which is used by OpenSSL to store symmetric keys, assigns the
114 \&\fBEVP_SKEYMGMT\fR object associated with the key, and initializes the object from
115 the \fBparams\fR argument.
116 .PP
117 The \fBEVP_SKEY_import_raw_key()\fR function is a helper that creates an \fBEVP_SKEY\fR
118 object containing the raw byte representation of the symmetric keys from the
119 buffer \fIkey\fR having length \fIlen\fR. The \fIskeymgmtname\fR defines the name of the
120 target \fBEVP_SKEYMGMT\fR for the newly created key.
121 .PP
122 The \fBEVP_SKEY_export()\fR function extracts values from a key \fIskey\fR using the
123 \&\fIselection\fR. \fIselection\fR is described below. It uses a callback \fIexport_cb\fR
124 that gets passed the value of \fIexport_cbarg\fR. See \fBopenssl\-core.h\fR\|(7) for
125 more information about the callback. Note that the \fBOSSL_PARAM\fR\|(3) array that
126 is passed to the callback is not persistent after the callback returns.
127 .PP
128 The \fBEVP_SKEY_get0_raw_key()\fR returns a pointer to a raw key bytes to the passed
129 address and sets the key len. The returned address is managed by the internal
130 key management and shouldn't be freed explicitly. The operation can fail when
131 the underlying key management doesn't support export of the secret key.
132 .PP
133 The \fBEVP_SKEY_get0_key_id()\fR returns a NUL-terminated string providing some
134 human-readable identifier of the key if provided by the underlying key
135 management. The pointer becomes invalid after freeing the EVP_SKEY object.
136 .PP
137 The \fBEVP_SKEY_get0_skeymgmt_name()\fR and \fBEVP_SKEY_get0_provider_name()\fR return the
138 names of the associated EVP_SKEYMGMT object and its provider correspondingly.
139 .PP
140 \&\fBEVP_SKEY_up_ref()\fR increments the reference count of \fIkey\fR.
141 .PP
142 \&\fBEVP_SKEY_free()\fR decrements the reference count of \fIkey\fR and, if the reference
143 count is zero, frees it. If \fIkey\fR is NULL, nothing is done.
144 .PP
145 \&\fBEVP_SKEY_is_a()\fR checks if the key type of \fIskey\fR is \fIname\fR.
146 .PP
147 \&\fBEVP_SKEY_to_provider()\fR simplifies the task of importing a \fIskey\fR into a
148 different provider identified by \fIprov\fR. If \fIprov\fR is NULL, the default
149 provider for the key type identified via \fIskey\fR is used.
150 .SS Selections
151 .IX Subsection "Selections"
152 The following constants can be used for \fIselection\fR:
153 .IP \fBOSSL_SKEYMGMT_SELECT_SECRET_KEY\fR 4
154 .IX Item "OSSL_SKEYMGMT_SELECT_SECRET_KEY"
155 Only the raw key representation will be selected.
156 .IP \fBOSSL_SKEYMGMT_SELECT_PARAMETERS\fR 4
157 .IX Item "OSSL_SKEYMGMT_SELECT_PARAMETERS"
158 Only the key parameters will be selected. This includes optional key
159 parameters.
160 .IP \fBOSSL_SKEYMGMT_SELECT_ALL\fR 4
161 .IX Item "OSSL_SKEYMGMT_SELECT_ALL"
162 All parameters will be selected.
163 .SH NOTES
164 .IX Header "NOTES"
165 The \fBEVP_SKEY\fR structure is used by various OpenSSL functions which require a
166 general symmetric key without reference to any particular algorithm.
167 .PP
168 The \fBEVP_SKEY_to_provider()\fR function will fail and return NULL if the origin
169 key \fIskey\fR cannot be exported from its provider.
170 .SH "RETURN VALUES"
171 .IX Header "RETURN VALUES"
172 \&\fBEVP_SKEY_generate()\fR, \fBEVP_SKEY_import()\fR and \fBEVP_SKEY_import_raw_key()\fR return
173 either the newly allocated \fBEVP_SKEY\fR structure or NULL if an error occurred.
174 .PP
175 \&\fBEVP_SKEY_get0_key_id()\fR returns either a valid pointer or NULL.
176 .PP
177 \&\fBEVP_SKEY_up_ref()\fR returns 1 for success and 0 on failure.
178 .PP
179 \&\fBEVP_SKEY_export()\fR and \fBEVP_SKEY_get0_raw_key()\fR return 1 for success and 0 on failure.
180 .PP
181 \&\fBEVP_SKEY_get0_skeymgmt_name()\fR and \fBEVP_SKEY_get0_provider_name()\fR return the
182 names of the associated EVP_SKEYMGMT object and its provider correspondingly.
183 .PP
184 \&\fBEVP_SKEY_is_a()\fR returns 1 if \fIskey\fR has the key type \fIname\fR,
185 otherwise 0.
186 .PP
187 \&\fBEVP_SKEY_to_provider()\fR returns a new \fBEVP_SKEY\fR suitable for operations with
188 the \fIprov\fR provider or NULL in case of failure.
189 .SH "SEE ALSO"
190 .IX Header "SEE ALSO"
191 \&\fBEVP_SKEYMGMT\fR\|(3), \fBprovider\fR\|(7), \fBOSSL_PARAM\fR\|(3)
192 .SH HISTORY
193 .IX Header "HISTORY"
194 The \fBEVP_SKEY\fR API and functions \fBEVP_SKEY_export()\fR,
195 \&\fBEVP_SKEY_free()\fR, \fBEVP_SKEY_get0_raw_key()\fR, \fBEVP_SKEY_import()\fR,
196 \&\fBEVP_SKEY_import_raw_key()\fR, \fBEVP_SKEY_up_ref()\fR, \fBEVP_SKEY_generate()\fR,
197 \&\fBEVP_SKEY_get0_key_id()\fR, \fBEVP_SKEY_get0_provider_name()\fR,
198 \&\fBEVP_SKEY_get0_skeymgmt_name()\fR, \fBEVP_SKEY_is_a()\fR, \fBEVP_SKEY_to_provider()\fR
199 were introduced in OpenSSL 3.5.
200 .SH COPYRIGHT
201 .IX Header "COPYRIGHT"
202 Copyright 2025\-2026 The OpenSSL Project Authors. All Rights Reserved.
203 .PP
204 Licensed under the Apache License 2.0 (the "License"). You may not use
205 this file except in compliance with the License. You can obtain a copy
206 in the file LICENSE in the source distribution or at
207 <https://www.openssl.org/source/license.html>.