Debian Codegraph @

upstream/debian-unstable/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.6.2 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, EVP_SKEY_import, EVP_SKEY_import_raw_key,
65 EVP_SKEY_import_SKEYMGMT, EVP_SKEY_up_ref, EVP_SKEY_export,
66 EVP_SKEY_get0_raw_key, EVP_SKEY_get0_key_id, EVP_SKEY_get0_skeymgmt_name,
67 EVP_SKEY_get0_provider_name, EVP_SKEY_free, EVP_SKEY_is_a, EVP_SKEY_to_provider
68 \&\- opaque symmetric key allocation and handling functions
69 .SH SYNOPSIS
70 .IX Header "SYNOPSIS"
71 .Vb 1
72 \& #include <openssl/evp.h>
73 \&
74 \& typedef evp_skey_st EVP_SKEY;
75 \&
76 \& EVP_SKEY *EVP_SKEY_generate(OSSL_LIB_CTX *libctx, const char *skeymgmtname,
77 \& const char *propquery, const OSSL_PARAM *params);
78 \& EVP_SKEY *EVP_SKEY_import(OSSL_LIB_CTX *libctx, const char *skeymgmtname,
79 \& const char *propquery,
80 \& int selection, const OSSL_PARAM *params);
81 \& EVP_SKEY *EVP_SKEY_import_raw_key(OSSL_LIB_CTX *libctx, const char *skeymgmtname,
82 \& unsigned char *key, size_t len,
83 \& const char *propquery);
84 \& EVP_SKEY *EVP_SKEY_import_SKEYMGMT(OSSL_LIB_CTX *libctx, EVP_SKEYMGMT *skeymgmt,
85 \& int selection, const OSSL_PARAM *params);
86 \& int EVP_SKEY_export(const EVP_SKEY *skey, int selection,
87 \& OSSL_CALLBACK *export_cb, void *export_cbarg);
88 \& int EVP_SKEY_get0_raw_key(const EVP_SKEY *skey, const unsigned char **key,
89 \& size_t *len);
90 \& const char *EVP_SKEY_get0_key_id(const EVP_SKEY *skey);
91 \&
92 \& const char *EVP_SKEY_get0_skeymgmt_name(const EVP_SKEY *skey);
93 \& const char *EVP_SKEY_get0_provider_name(const EVP_SKEY *skey);
94 \&
95 \& int EVP_SKEY_up_ref(EVP_SKEY *key);
96 \& void EVP_SKEY_free(EVP_SKEY *key);
97 \& int EVP_SKEY_is_a(const EVP_SKEY *skey, const char *name);
98 \& EVP_SKEY *EVP_SKEY_to_provider(EVP_SKEY *skey, OSSL_LIB_CTX *libctx,
99 \& OSSL_PROVIDER *prov, const char *propquery);
100 .Ve
101 .SH DESCRIPTION
102 .IX Header "DESCRIPTION"
103 \&\fBEVP_SKEY\fR is a generic structure to hold symmetric keys as opaque objects.
104 The keys themselves are often referred to as the "internal key", and are handled by
105 providers using \fBEVP_SKEYMGMT\fR\|(3).
106 .PP
107 Conceptually, an \fBEVP_SKEY\fR internal key may hold a symmetric key, and along
108 with those, key parameters if the key type requires them.
109 .PP
110 The \fBEVP_SKEY_generate()\fR functions creates a new \fBEVP_SKEY\fR object and
111 initializes it according to the \fBparams\fR argument.
112 .PP
113 The \fBEVP_SKEY_import()\fR function allocates an empty \fBEVP_SKEY\fR structure
114 which is used by OpenSSL to store symmetric keys, assigns the
115 \&\fBEVP_SKEYMGMT\fR object associated with the key, and initializes the object from
116 the \fBparams\fR argument.
117 .PP
118 The \fBEVP_SKEY_import_raw_key()\fR function is a helper that creates an \fBEVP_SKEY\fR
119 object containing the raw byte representation of the symmetric keys from the
120 buffer \fIkey\fR having length \fIlen\fR. The \fIskeymgmtname\fR defines the name of the
121 target \fBEVP_SKEYMGMT\fR for the newly created key.
122 .PP
123 The \fBEVP_SKEY_import_SKEYMGMT()\fR function is a helper that creates an \fBEVP_SKEY\fR
124 object containing the representation of the symmetric keys specific to the
125 particular \fBEVP_SKEYMGMT\fR.
126 .PP
127 The \fBEVP_SKEY_export()\fR function extracts values from a key \fIskey\fR using the
128 \&\fIselection\fR. \fIselection\fR is described below. It uses a callback \fIexport_cb\fR
129 that gets passed the value of \fIexport_cbarg\fR. See \fBopenssl\-core.h\fR\|(7) for
130 more information about the callback. Note that the \fBOSSL_PARAM\fR\|(3) array that
131 is passed to the callback is not persistent after the callback returns.
132 .PP
133 The \fBEVP_SKEY_get0_raw_key()\fR returns a pointer to a raw key bytes to the passed
134 address and sets the key len. The returned address is managed by the internal
135 key management and shouldn't be freed explicitly. The operation can fail when
136 the underlying key management doesn't support export of the secret key.
137 .PP
138 The \fBEVP_SKEY_get0_key_id()\fR returns a NUL-terminated string providing some
139 human-readable identifier of the key if provided by the underlying key
140 management. The pointer becomes invalid after freeing the EVP_SKEY object.
141 .PP
142 The \fBEVP_SKEY_get0_skeymgmt_name()\fR and \fBEVP_SKEY_get0_provider_name()\fR return the
143 names of the associated EVP_SKEYMGMT object and its provider correspondingly.
144 .PP
145 \&\fBEVP_SKEY_up_ref()\fR increments the reference count of \fIkey\fR.
146 .PP
147 \&\fBEVP_SKEY_free()\fR decrements the reference count of \fIkey\fR and, if the reference
148 count is zero, frees it. If \fIkey\fR is NULL, nothing is done.
149 .PP
150 \&\fBEVP_SKEY_is_a()\fR checks if the key type of \fIskey\fR is \fIname\fR.
151 .PP
152 \&\fBEVP_SKEY_to_provider()\fR simplifies the task of importing a \fIskey\fR into a
153 different provider identified by \fIprov\fR. If \fIprov\fR is NULL, the default
154 provider for the key type identified via \fIskey\fR is used.
155 .SS Selections
156 .IX Subsection "Selections"
157 The following constants can be used for \fIselection\fR:
158 .IP \fBOSSL_SKEYMGMT_SELECT_SECRET_KEY\fR 4
159 .IX Item "OSSL_SKEYMGMT_SELECT_SECRET_KEY"
160 Only the raw key representation will be selected.
161 .IP \fBOSSL_SKEYMGMT_SELECT_PARAMETERS\fR 4
162 .IX Item "OSSL_SKEYMGMT_SELECT_PARAMETERS"
163 Only the key parameters will be selected. This includes optional key
164 parameters.
165 .IP \fBOSSL_SKEYMGMT_SELECT_ALL\fR 4
166 .IX Item "OSSL_SKEYMGMT_SELECT_ALL"
167 All parameters will be selected.
168 .SH NOTES
169 .IX Header "NOTES"
170 The \fBEVP_SKEY\fR structure is used by various OpenSSL functions which require a
171 general symmetric key without reference to any particular algorithm.
172 .PP
173 The \fBEVP_SKEY_to_provider()\fR function will fail and return NULL if the origin
174 key \fIskey\fR cannot be exported from its provider.
175 .SH "RETURN VALUES"
176 .IX Header "RETURN VALUES"
177 \&\fBEVP_SKEY_generate()\fR, \fBEVP_SKEY_import()\fR, \fBEVP_SKEY_import_raw_key()\fR, and
178 \&\fBEVP_SKEY_import_SKEYMGMT()\fR return either the newly allocated \fBEVP_SKEY\fR
179 structure or NULL if an error occurred.
180 .PP
181 \&\fBEVP_SKEY_get0_key_id()\fR returns either a valid pointer or NULL.
182 .PP
183 \&\fBEVP_SKEY_up_ref()\fR returns 1 for success and 0 on failure.
184 .PP
185 \&\fBEVP_SKEY_export()\fR and \fBEVP_SKEY_get0_raw_key()\fR return 1 for success and 0 on failure.
186 .PP
187 \&\fBEVP_SKEY_get0_skeymgmt_name()\fR and \fBEVP_SKEY_get0_provider_name()\fR return the
188 names of the associated EVP_SKEYMGMT object and its provider correspondingly.
189 .PP
190 \&\fBEVP_SKEY_is_a()\fR returns 1 if \fIskey\fR has the key type \fIname\fR,
191 otherwise 0.
192 .PP
193 \&\fBEVP_SKEY_to_provider()\fR returns a new \fBEVP_SKEY\fR suitable for operations with
194 the \fIprov\fR provider or NULL in case of failure.
195 .SH "SEE ALSO"
196 .IX Header "SEE ALSO"
197 \&\fBEVP_SKEYMGMT\fR\|(3), \fBprovider\fR\|(7), \fBOSSL_PARAM\fR\|(3)
198 .SH HISTORY
199 .IX Header "HISTORY"
200 The \fBEVP_SKEY\fR API and functions \fBEVP_SKEY_export()\fR,
201 \&\fBEVP_SKEY_free()\fR, \fBEVP_SKEY_get0_raw_key()\fR, \fBEVP_SKEY_import()\fR,
202 \&\fBEVP_SKEY_import_raw_key()\fR, \fBEVP_SKEY_up_ref()\fR, \fBEVP_SKEY_generate()\fR,
203 \&\fBEVP_SKEY_get0_key_id()\fR, \fBEVP_SKEY_get0_provider_name()\fR,
204 \&\fBEVP_SKEY_get0_skeymgmt_name()\fR, \fBEVP_SKEY_is_a()\fR, \fBEVP_SKEY_to_provider()\fR
205 were introduced in OpenSSL 3.5.
206 .PP
207 The \fBEVP_SKEY_import_SKEYMGMT()\fR function was introduced in OpenSSL 4.0.
208 .SH COPYRIGHT
209 .IX Header "COPYRIGHT"
210 Copyright 2025\-2026 The OpenSSL Project Authors. All Rights Reserved.
211 .PP
212 Licensed under the Apache License 2.0 (the "License"). You may not use
213 this file except in compliance with the License. You can obtain a copy
214 in the file LICENSE in the source distribution or at
215 <https://www.openssl.org/source/license.html>.