Debian Codegraph @

upstream/debian-unstable/man3/d2i_RSAPrivateKey.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 "D2I_RSAPRIVATEKEY 3SSL"
58 .TH D2I_RSAPRIVATEKEY 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 d2i_DSAPrivateKey,
65 d2i_DSAPrivateKey_bio,
66 d2i_DSAPrivateKey_fp,
67 d2i_DSAPublicKey,
68 d2i_DSA_PUBKEY,
69 d2i_DSA_PUBKEY_bio,
70 d2i_DSA_PUBKEY_fp,
71 d2i_DSAparams,
72 d2i_RSAPrivateKey,
73 d2i_RSAPrivateKey_bio,
74 d2i_RSAPrivateKey_fp,
75 d2i_RSAPublicKey,
76 d2i_RSAPublicKey_bio,
77 d2i_RSAPublicKey_fp,
78 d2i_RSA_PUBKEY,
79 d2i_RSA_PUBKEY_bio,
80 d2i_RSA_PUBKEY_fp,
81 d2i_DHparams,
82 d2i_DHparams_bio,
83 d2i_DHparams_fp,
84 d2i_ECParameters,
85 d2i_ECPrivateKey,
86 d2i_ECPrivateKey_bio,
87 d2i_ECPrivateKey_fp,
88 d2i_EC_PUBKEY,
89 d2i_EC_PUBKEY_bio,
90 d2i_EC_PUBKEY_fp,
91 i2d_RSAPrivateKey,
92 i2d_RSAPrivateKey_bio,
93 i2d_RSAPrivateKey_fp,
94 i2d_RSAPublicKey,
95 i2d_RSAPublicKey_bio,
96 i2d_RSAPublicKey_fp,
97 i2d_RSA_PUBKEY,
98 i2d_RSA_PUBKEY_bio,
99 i2d_RSA_PUBKEY_fp,
100 i2d_DHparams,
101 i2d_DHparams_bio,
102 i2d_DHparams_fp,
103 i2d_DSAPrivateKey,
104 i2d_DSAPrivateKey_bio,
105 i2d_DSAPrivateKey_fp,
106 i2d_DSAPublicKey,
107 i2d_DSA_PUBKEY,
108 i2d_DSA_PUBKEY_bio,
109 i2d_DSA_PUBKEY_fp,
110 i2d_DSAparams,
111 i2d_ECParameters,
112 i2d_ECPrivateKey,
113 i2d_ECPrivateKey_bio,
114 i2d_ECPrivateKey_fp,
115 i2d_EC_PUBKEY,
116 i2d_EC_PUBKEY_bio,
117 i2d_EC_PUBKEY_fp
118 \&\- DEPRECATED
119 .SH SYNOPSIS
120 .IX Header "SYNOPSIS"
121 The following functions have been deprecated since OpenSSL 3.0, and can be
122 hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value,
123 see \fBopenssl_user_macros\fR\|(7):
124 .PP
125 .Vb 12
126 \& TYPE *d2i_TYPEPrivateKey(TYPE **a, const unsigned char **ppin, long length);
127 \& TYPE *d2i_TYPEPrivateKey_bio(BIO *bp, TYPE **a);
128 \& TYPE *d2i_TYPEPrivateKey_fp(FILE *fp, TYPE **a);
129 \& TYPE *d2i_TYPEPublicKey(TYPE **a, const unsigned char **ppin, long length);
130 \& TYPE *d2i_TYPEPublicKey_bio(BIO *bp, TYPE **a);
131 \& TYPE *d2i_TYPEPublicKey_fp(FILE *fp, TYPE **a);
132 \& TYPE *d2i_TYPEparams(TYPE **a, const unsigned char **ppin, long length);
133 \& TYPE *d2i_TYPEparams_bio(BIO *bp, TYPE **a);
134 \& TYPE *d2i_TYPEparams_fp(FILE *fp, TYPE **a);
135 \& TYPE *d2i_TYPE_PUBKEY(TYPE **a, const unsigned char **ppin, long length);
136 \& TYPE *d2i_TYPE_PUBKEY_bio(BIO *bp, TYPE **a);
137 \& TYPE *d2i_TYPE_PUBKEY_fp(FILE *fp, TYPE **a);
138 \&
139 \& int i2d_TYPEPrivateKey(const TYPE *a, unsigned char **ppout);
140 \& int i2d_TYPEPrivateKey(TYPE *a, unsigned char **ppout);
141 \& int i2d_TYPEPrivateKey_fp(FILE *fp, const TYPE *a);
142 \& int i2d_TYPEPrivateKey_fp(FILE *fp, TYPE *a);
143 \& int i2d_TYPEPrivateKey_bio(BIO *bp, const TYPE *a);
144 \& int i2d_TYPEPrivateKey_bio(BIO *bp, TYPE *a);
145 \& int i2d_TYPEPublicKey(const TYPE *a, unsigned char **ppout);
146 \& int i2d_TYPEPublicKey(TYPE *a, unsigned char **ppout);
147 \& int i2d_TYPEPublicKey_fp(FILE *fp, const TYPE *a);
148 \& int i2d_TYPEPublicKey_fp(FILE *fp, TYPE *a);
149 \& int i2d_TYPEPublicKey_bio(BIO *bp, const TYPE *a);
150 \& int i2d_TYPEPublicKey_bio(BIO *bp, TYPE *a);
151 \& int i2d_TYPEparams(const TYPE *a, unsigned char **ppout);
152 \& int i2d_TYPEparams(TYPE *a, unsigned char **ppout);
153 \& int i2d_TYPEparams_fp(FILE *fp, const TYPE *a);
154 \& int i2d_TYPEparams_fp(FILE *fp, TYPE *a);
155 \& int i2d_TYPEparams_bio(BIO *bp, const TYPE *a);
156 \& int i2d_TYPEparams_bio(BIO *bp, TYPE *a);
157 \& int i2d_TYPE_PUBKEY(const TYPE *a, unsigned char **ppout);
158 \& int i2d_TYPE_PUBKEY(TYPE *a, unsigned char **ppout);
159 \& int i2d_TYPE_PUBKEY_fp(FILE *fp, const TYPE *a);
160 \& int i2d_TYPE_PUBKEY_fp(FILE *fp, TYPE *a);
161 \& int i2d_TYPE_PUBKEY_bio(BIO *bp, const TYPE *a);
162 \& int i2d_TYPE_PUBKEY_bio(BIO *bp, TYPE *a);
163 .Ve
164 .SH DESCRIPTION
165 .IX Header "DESCRIPTION"
166 All functions described here are deprecated. Please use \fBOSSL_DECODER\fR\|(3)
167 instead of the \fBd2i\fR functions and \fBOSSL_ENCODER\fR\|(3) instead of the \fBi2d\fR
168 functions. See "Migration" below.
169 .PP
170 In the description here, \fR\f(BITYPE\fR\fB\fR is used a placeholder for any of the
171 OpenSSL datatypes, such as \fBRSA\fR.
172 The function parameters \fIppin\fR and \fIppout\fR are generally either both named
173 \&\fIpp\fR in the headers, or \fIin\fR and \fIout\fR.
174 .PP
175 All the functions here behave the way that's described in \fBd2i_X509\fR\|(3).
176 .PP
177 Please note that not all functions in the synopsis are available for all key
178 types. For example, there are no \fBd2i_RSAparams()\fR or \fBi2d_RSAparams()\fR,
179 because the PKCS#1 \fBRSA\fR structure doesn't include any key parameters.
180 .PP
181 \&\fBd2i_\fR\f(BITYPE\fR\fBPrivateKey\fR() and derivates thereof decode DER encoded
182 \&\fR\f(BITYPE\fR\fB\fR private key data organized in a type specific structure.
183 .PP
184 \&\fBd2i_\fR\f(BITYPE\fR\fBPublicKey\fR() and derivates thereof decode DER encoded
185 \&\fR\f(BITYPE\fR\fB\fR public key data organized in a type specific structure.
186 .PP
187 \&\fBd2i_\fR\f(BITYPE\fR\fBparams\fR() and derivates thereof decode DER encoded \fR\f(BITYPE\fR\fB\fR
188 key parameters organized in a type specific structure.
189 .PP
190 \&\fBd2i_\fR\f(BITYPE\fR\fB_PUBKEY\fR() and derivates thereof decode DER encoded \fR\f(BITYPE\fR\fB\fR
191 public key data organized in a \fBSubjectPublicKeyInfo\fR structure.
192 .PP
193 \&\fBi2d_\fR\f(BITYPE\fR\fBPrivateKey\fR() and derivates thereof encode the private key
194 \&\fR\f(BITYPE\fR\fB\fR data into a type specific DER encoded structure.
195 .PP
196 \&\fBi2d_\fR\f(BITYPE\fR\fBPublicKey\fR() and derivates thereof encode the public key
197 \&\fR\f(BITYPE\fR\fB\fR data into a type specific DER encoded structure.
198 .PP
199 \&\fBi2d_\fR\f(BITYPE\fR\fBparams\fR() and derivates thereof encode the \fR\f(BITYPE\fR\fB\fR key
200 parameters data into a type specific DER encoded structure.
201 .PP
202 \&\fBi2d_\fR\f(BITYPE\fR\fB_PUBKEY\fR() and derivates thereof encode the public key
203 \&\fR\f(BITYPE\fR\fB\fR data into a DER encoded \fBSubjectPublicKeyInfo\fR structure.
204 .PP
205 For example, \fBd2i_RSAPrivateKey()\fR and \fBd2i_RSAPublicKey()\fR expects the
206 structure defined by PKCS#1.
207 Similarly, \fBi2d_RSAPrivateKey()\fR and \fBi2d_RSAPublicKey()\fR produce DER encoded
208 string organized according to PKCS#1.
209 .SS Migration
210 .IX Subsection "Migration"
211 Migration from the diverse \fR\f(BITYPE\fR\fB\fRs requires using corresponding new
212 OpenSSL types. For all \fB\fR\f(BITYPE\fR\fB\fRs described here, the corresponding new
213 type is \fBEVP_PKEY\fR. The rest of this section assumes that this has been
214 done, exactly how to do that is described elsewhere.
215 .PP
216 There are two migration paths:
217 .IP \(bu 4
218 Replace
219 \&\fBd2i_\fR\f(BITYPE\fR\fBPrivateKey()\fR with \fBd2i_PrivateKey\fR\|(3),
220 \&\fBd2i_\fR\f(BITYPE\fR\fBPublicKey()\fR with \fBd2i_PublicKey\fR\|(3),
221 \&\fBd2i_\fR\f(BITYPE\fR\fBparams()\fR with \fBd2i_KeyParams\fR\|(3),
222 \&\fBd2i_\fR\f(BITYPE\fR\fB_PUBKEY()\fR with \fBd2i_PUBKEY\fR\|(3),
223 \&\fBi2d_\fR\f(BITYPE\fR\fBPrivateKey()\fR with \fBi2d_PrivateKey\fR\|(3),
224 \&\fBi2d_\fR\f(BITYPE\fR\fBPublicKey()\fR with \fBi2d_PublicKey\fR\|(3),
225 \&\fBi2d_\fR\f(BITYPE\fR\fBparams()\fR with \fBi2d_KeyParams\fR\|(3),
226 \&\fBi2d_\fR\f(BITYPE\fR\fB_PUBKEY()\fR with \fBi2d_PUBKEY\fR\|(3).
227 A caveat is that \fBi2d_PrivateKey\fR\|(3) may output a DER encoded PKCS#8
228 outermost structure instead of the type specific structure, and that
229 \&\fBd2i_PrivateKey\fR\|(3) recognises and unpacks a PKCS#8 structures.
230 .IP \(bu 4
231 Use \fBOSSL_DECODER\fR\|(3) and \fBOSSL_ENCODER\fR\|(3). How to migrate is described
232 below. All those descriptions assume that the key to be encoded is in the
233 variable \fIpkey\fR.
234 .PP
235 \fIMigrating \fR\f(BIi2d\fR\fI functions to \fR\f(BIOSSL_ENCODER\fR
236 .IX Subsection "Migrating i2d functions to OSSL_ENCODER"
237 .PP
238 The exact \fBOSSL_ENCODER\fR\|(3) output is driven by arguments rather than by
239 function names. The sample code to get DER encoded output in a type
240 specific structure is uniform, the only things that vary are the selection
241 of what part of the \fBEVP_PKEY\fR should be output, and the structure. The
242 \&\fBi2d\fR functions names can therefore be translated into two variables,
243 \&\fIselection\fR and \fIstructure\fR as follows:
244 .IP "\fBi2d_\fR\f(BITYPE\fR\fBPrivateKey\fR() translates into:" 4
245 .IX Item "i2d_TYPEPrivateKey() translates into:"
246 .Vb 2
247 \& int selection = EVP_PKEY_KEYPAIR;
248 \& const char *structure = "type\-specific";
249 .Ve
250 .IP "\fBi2d_\fR\f(BITYPE\fR\fBPublicKey\fR() translates into:" 4
251 .IX Item "i2d_TYPEPublicKey() translates into:"
252 .Vb 2
253 \& int selection = EVP_PKEY_PUBLIC_KEY;
254 \& const char *structure = "type\-specific";
255 .Ve
256 .IP "\fBi2d_\fR\f(BITYPE\fR\fBparams\fR() translates into:" 4
257 .IX Item "i2d_TYPEparams() translates into:"
258 .Vb 2
259 \& int selection = EVP_PKEY_PARAMETERS;
260 \& const char *structure = "type\-specific";
261 .Ve
262 .IP "\fBi2d_\fR\f(BITYPE\fR\fB_PUBKEY\fR() translates into:" 4
263 .IX Item "i2d_TYPE_PUBKEY() translates into:"
264 .Vb 2
265 \& int selection = EVP_PKEY_PUBLIC_KEY;
266 \& const char *structure = "SubjectPublicKeyInfo";
267 .Ve
268 .PP
269 The following sample code does the rest of the work:
270 .PP
271 .Vb 10
272 \& unsigned char *p = buffer; /* |buffer| is supplied by the caller */
273 \& size_t len = buffer_size; /* assumed be the size of |buffer| */
274 \& OSSL_ENCODER_CTX *ctx =
275 \& OSSL_ENCODER_CTX_new_for_pkey(pkey, selection, "DER", structure,
276 \& NULL, NULL);
277 \& if (ctx == NULL) {
278 \& /* fatal error handling */
279 \& }
280 \& if (OSSL_ENCODER_CTX_get_num_encoders(ctx) == 0) {
281 \& OSSL_ENCODER_CTX_free(ctx);
282 \& /* non\-fatal error handling */
283 \& }
284 \& if (!OSSL_ENCODER_to_data(ctx, &p, &len)) {
285 \& OSSL_ENCODER_CTX_free(ctx);
286 \& /* error handling */
287 \& }
288 \& OSSL_ENCODER_CTX_free(ctx);
289 .Ve
290 .SH NOTES
291 .IX Header "NOTES"
292 The letters \fBi\fR and \fBd\fR in \fBi2d_\fR\f(BITYPE\fR() stand for
293 "internal" (that is, an internal C structure) and "DER" respectively.
294 So \fBi2d_\fR\f(BITYPE\fR\fB\fR() converts from internal to DER.
295 .PP
296 The functions can also understand \fBBER\fR forms.
297 .PP
298 The actual TYPE structure passed to \fBi2d_\fR\f(BITYPE\fR() must be a valid
299 populated \fB\fR\f(BITYPE\fR\fB\fR structure \-\- it \fBcannot\fR simply be fed with an
300 empty structure such as that returned by \fBTYPE_new()\fR.
301 .PP
302 The encoded data is in binary form and may contain embedded zeros.
303 Therefore, any FILE pointers or BIOs should be opened in binary mode.
304 Functions such as \fBstrlen()\fR will \fBnot\fR return the correct length
305 of the encoded structure.
306 .PP
307 The ways that \fI*ppin\fR and \fI*ppout\fR are incremented after the operation
308 can trap the unwary. See the \fBWARNINGS\fR section in \fBd2i_X509\fR\|(3) for some
309 common errors.
310 The reason for this-auto increment behaviour is to reflect a typical
311 usage of ASN1 functions: after one structure is encoded or decoded
312 another will be processed after it.
313 .PP
314 The following points about the data types might be useful:
315 .IP \fBDSA_PUBKEY\fR 4
316 .IX Item "DSA_PUBKEY"
317 Represents a DSA public key using a \fBSubjectPublicKeyInfo\fR structure.
318 .IP "\fBDSAPublicKey\fR, \fBDSAPrivateKey\fR" 4
319 .IX Item "DSAPublicKey, DSAPrivateKey"
320 Use a non-standard OpenSSL format and should be avoided; use \fBDSA_PUBKEY\fR,
321 \&\fBPEM_write_PrivateKey\fR\|(3), or similar instead.
322 .SH "RETURN VALUES"
323 .IX Header "RETURN VALUES"
324 \&\fBd2i_\fR\f(BITYPE\fR(), \fBd2i_\fR\f(BITYPE\fR\fB_bio\fR() and \fBd2i_\fR\f(BITYPE\fR\fB_fp\fR() return a valid
325 \&\fB\fR\f(BITYPE\fR\fB\fR structure or NULL if an error occurs. If the "reuse" capability has
326 been used with a valid structure being passed in via \fIa\fR, then the object is
327 freed in the event of error and \fI*a\fR is set to NULL.
328 .PP
329 \&\fBi2d_\fR\f(BITYPE\fR() returns the number of bytes successfully encoded or a negative
330 value if an error occurs.
331 .PP
332 \&\fBi2d_\fR\f(BITYPE\fR\fB_bio\fR() and \fBi2d_\fR\f(BITYPE\fR\fB_fp\fR() return 1 for success and 0 if an
333 error occurs.
334 .SH "SEE ALSO"
335 .IX Header "SEE ALSO"
336 \&\fBOSSL_ENCODER\fR\|(3), \fBOSSL_DECODER\fR\|(3),
337 \&\fBd2i_PrivateKey\fR\|(3), \fBd2i_PublicKey\fR\|(3), \fBd2i_KeyParams\fR\|(3),
338 \&\fBd2i_PUBKEY\fR\|(3),
339 \&\fBi2d_PrivateKey\fR\|(3), \fBi2d_PublicKey\fR\|(3), \fBi2d_KeyParams\fR\|(3),
340 \&\fBi2d_PUBKEY\fR\|(3)
341 .SH COPYRIGHT
342 .IX Header "COPYRIGHT"
343 Copyright 2020\-2025 The OpenSSL Project Authors. All Rights Reserved.
344 .PP
345 Licensed under the Apache License 2.0 (the "License"). You may not use
346 this file except in compliance with the License. You can obtain a copy
347 in the file LICENSE in the source distribution or at
348 <https://www.openssl.org/source/license.html>.