]>
Commit | Line | Data |
---|---|---|
b1b3e14f DSH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
137b274a MC |
5 | d2i_PrivateKey_ex, d2i_PrivateKey, d2i_PublicKey, d2i_KeyParams, |
6 | d2i_AutoPrivateKey_ex, d2i_AutoPrivateKey, i2d_PrivateKey, i2d_PublicKey, | |
7 | i2d_KeyParams, i2d_KeyParams_bio, d2i_PrivateKey_ex_bio, d2i_PrivateKey_bio, | |
8 | d2i_PrivateKey_ex_fp, d2i_PrivateKey_fp, d2i_KeyParams_bio, i2d_PrivateKey_bio, | |
9 | i2d_PrivateKey_fp | |
4692340e | 10 | - decode and encode functions for reading and saving EVP_PKEY structures |
b1b3e14f DSH |
11 | |
12 | =head1 SYNOPSIS | |
13 | ||
14 | #include <openssl/evp.h> | |
15 | ||
137b274a MC |
16 | EVP_PKEY *d2i_PrivateKey_ex(int type, EVP_PKEY **a, const unsigned char **pp, |
17 | long length, OPENSSL_CTX *libctx, | |
18 | const char *propq); | |
b1b3e14f DSH |
19 | EVP_PKEY *d2i_PrivateKey(int type, EVP_PKEY **a, const unsigned char **pp, |
20 | long length); | |
24b0be11 RS |
21 | EVP_PKEY *d2i_PublicKey(int type, EVP_PKEY **a, const unsigned char **pp, |
22 | long length); | |
6aa2e59e SL |
23 | EVP_PKEY *d2i_KeyParams(int type, EVP_PKEY **a, const unsigned char **pp, |
24 | long length); | |
137b274a MC |
25 | EVP_PKEY *d2i_AutoPrivateKey_ex(EVP_PKEY **a, const unsigned char **pp, |
26 | long length, OPENSSL_CTX *libctx, | |
27 | const char *propq); | |
b1b3e14f DSH |
28 | EVP_PKEY *d2i_AutoPrivateKey(EVP_PKEY **a, const unsigned char **pp, |
29 | long length); | |
6aa2e59e | 30 | |
9fdcc21f DO |
31 | int i2d_PrivateKey(const EVP_PKEY *a, unsigned char **pp); |
32 | int i2d_PublicKey(const EVP_PKEY *a, unsigned char **pp); | |
6aa2e59e SL |
33 | int i2d_KeyParams(const EVP_PKEY *a, unsigned char **pp); |
34 | int i2d_KeyParams_bio(BIO *bp, const EVP_PKEY *pkey); | |
137b274a MC |
35 | EVP_PKEY *d2i_KeyParams_bio(int type, EVP_PKEY **a, BIO *in); |
36 | ||
b1b3e14f | 37 | |
137b274a MC |
38 | #include <openssl/x509.h> |
39 | ||
40 | EVP_PKEY *d2i_PrivateKey_ex_bio(BIO *bp, EVP_PKEY **a, OPENSSL_CTX *libctx, | |
41 | const char *propq); | |
4692340e | 42 | EVP_PKEY *d2i_PrivateKey_bio(BIO *bp, EVP_PKEY **a); |
137b274a MC |
43 | EVP_PKEY *d2i_PrivateKey_ex_fp(FILE *fp, EVP_PKEY **a, OPENSSL_CTX *libctx, |
44 | const char *propq); | |
4692340e | 45 | EVP_PKEY *d2i_PrivateKey_fp(FILE *fp, EVP_PKEY **a) |
137b274a MC |
46 | |
47 | int i2d_PrivateKey_bio(BIO *bp, const EVP_PKEY *pkey); | |
48 | int i2d_PrivateKey_fp(FILE *fp, const EVP_PKEY *pkey); | |
4692340e | 49 | |
b1b3e14f DSH |
50 | =head1 DESCRIPTION |
51 | ||
137b274a MC |
52 | d2i_PrivateKey_ex() decodes a private key using algorithm I<type>. It attempts |
53 | to use any key specific format or PKCS#8 unencrypted PrivateKeyInfo format. The | |
54 | I<type> parameter should be a public key algorithm constant such as | |
55 | B<EVP_PKEY_RSA>. An error occurs if the decoded key does not match I<type>. Some | |
56 | private key decoding implementations may use cryptographic algorithms (for | |
57 | example to automatically derive the public key if it is not explicitly | |
58 | included in the encoding). In this case the supplied library context I<libctx> | |
59 | and property query string I<propq> are used. | |
60 | d2i_PrivateKey() does the same as d2i_PrivateKey_ex() except that the default | |
61 | library context and property query string are used. | |
24b0be11 | 62 | d2i_PublicKey() does the same for public keys. |
b305452f | 63 | d2i_KeyParams() does the same for key parameters. |
b1b3e14f | 64 | |
137b274a MC |
65 | The d2i_PrivateKey_ex_bio() and d2i_PrivateKey_bio() functions are similar to |
66 | d2i_PrivateKey_ex() and d2i_PrivateKey() respectively except that they decode | |
67 | the data read from the given BIO. The d2i_PrivateKey_ex_fp() and | |
68 | d2i_PrivateKey_fp() functions are the same except that they read the data from | |
69 | the given FILE. | |
70 | ||
71 | d2i_AutoPrivateKey_ex() and d2i_AutoPrivateKey() are similar to | |
72 | d2i_PrivateKey_ex() and d2i_PrivateKey() respectively except that they attempt | |
73 | to automatically detect the private key format. | |
b1b3e14f | 74 | |
137b274a | 75 | i2d_PrivateKey() encodes I<a>. It uses a key specific format or, if none is |
b1b3e14f | 76 | defined for that key type, PKCS#8 unencrypted PrivateKeyInfo format. |
24b0be11 | 77 | i2d_PublicKey() does the same for public keys. |
b305452f | 78 | i2d_KeyParams() does the same for key parameters. |
4692340e | 79 | These functions are similar to the d2i_X509() functions; see L<d2i_X509(3)>. |
137b274a MC |
80 | i2d_PrivateKey_bio() and i2d_PrivateKey_fp() do the same thing except that they |
81 | encode to a B<BIO> or B<FILE> respectrively. Again, these work similarly to the | |
82 | functions described in L<d2i_X509(3)>. | |
b1b3e14f DSH |
83 | |
84 | =head1 NOTES | |
85 | ||
86 | All these functions use DER format and unencrypted keys. Applications wishing | |
87 | to encrypt or decrypt private keys should use other functions such as | |
dd07e68b | 88 | d2i_PKCS8PrivateKey() instead. |
b1b3e14f | 89 | |
137b274a | 90 | If the I<*a> is not NULL when calling d2i_PrivateKey() or d2i_AutoPrivateKey() |
b1b3e14f | 91 | (i.e. an existing structure is being reused) and the key format is PKCS#8 |
137b274a | 92 | then I<*a> will be freed and replaced on a successful call. |
b1b3e14f | 93 | |
137b274a | 94 | To decode a key with type B<EVP_PKEY_EC>, d2i_PublicKey() requires I<*a> to be |
1980ce45 TS |
95 | a non-NULL EVP_PKEY structure assigned an EC_KEY structure referencing the proper |
96 | EC_GROUP. | |
97 | ||
b1b3e14f DSH |
98 | =head1 RETURN VALUES |
99 | ||
137b274a MC |
100 | The d2i_PrivateKey_ex(), d2i_PrivateKey(), d2i_AutoPrivateKey_ex(), |
101 | d2i_AutoPrivateKey(), d2i_PrivateKey_ex_bio(), d2i_PrivateKey_bio(), | |
102 | d2i_PrivateKey_ex_fp(), d2i_PrivateKey_fp(), d2i_PublicKey(), d2i_KeyParams() | |
103 | and d2i_KeyParams_bio() functions return a valid B<EVP_KEY> structure or B<NULL> | |
104 | if an error occurs. The error code can be obtained by calling | |
105 | L<ERR_get_error(3)>. | |
b1b3e14f | 106 | |
137b274a MC |
107 | i2d_PrivateKey(), i2d_PrivateKey_bio(), i2d_PrivateKey_fp(), i2d_PublicKey(), |
108 | i2d_KeyParams() i2d_KeyParams_bio() return the number of bytes successfully | |
109 | encoded or a negative value if an error occurs. The error code can be obtained | |
110 | by calling L<ERR_get_error(3)>. | |
b1b3e14f DSH |
111 | |
112 | =head1 SEE ALSO | |
113 | ||
b97fdb57 | 114 | L<crypto(7)>, |
9e183d22 | 115 | L<d2i_PKCS8PrivateKey_bio(3)> |
b1b3e14f | 116 | |
137b274a MC |
117 | =head1 HISTORY |
118 | ||
119 | d2i_PrivateKey_ex(), d2i_PrivateKey_ex_bio(), d2i_PrivateKey_ex_fp(), and | |
120 | d2i_AutoPrivateKey_ex() were added in OpenSSL 3.0. | |
121 | ||
e2f92610 RS |
122 | =head1 COPYRIGHT |
123 | ||
33388b44 | 124 | Copyright 2017-2020 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 125 | |
4746f25a | 126 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
127 | this file except in compliance with the License. You can obtain a copy |
128 | in the file LICENSE in the source distribution or at | |
129 | L<https://www.openssl.org/source/license.html>. | |
130 | ||
131 | =cut |