Botan 1.10.17

pkcs8.h
Go to the documentation of this file.
1 /*
2 * PKCS #8
3 * (C) 1999-2007 Jack Lloyd
4 *
5 * Distributed under the terms of the Botan license
6 */
7
8 #ifndef BOTAN_PKCS8_H__
9 #define BOTAN_PKCS8_H__
10
11 #include <botan/x509_key.h>
12 #include <botan/ui.h>
13
14 namespace Botan {
15
16 /**
17 * PKCS #8 General Exception
18 */
19 struct BOTAN_DLL PKCS8_Exception : public Decoding_Error
20 {
21 PKCS8_Exception(const std::string& error) :
22 Decoding_Error("PKCS #8: " + error) {}
23 };
24
25 /**
26 * This namespace contains functions for handling PKCS #8 private keys
27 */
28 namespace PKCS8 {
29
30 /**
31 * BER encode a private key
32 * @param key the private key to encode
33 * @return BER encoded key
34 */
35 BOTAN_DLL SecureVector<byte> BER_encode(const Private_Key& key);
36
37 /**
38 * Get a string containing a PEM encoded private key.
39 * @param key the key to encode
40 * @return encoded key
41 */
42 BOTAN_DLL std::string PEM_encode(const Private_Key& key);
43
44 /**
45 * Encrypt a key using PKCS #8 encryption
46 * @param key the key to encode
47 * @param rng the rng to use
48 * @param pass the password to use for encryption
49 * @param pbe_algo the name of the desired password-based encryption
50 algorithm; if empty ("") a reasonable (portable/secure)
51 default will be chosen.
52 * @return encrypted key in binary BER form
53 */
54 BOTAN_DLL SecureVector<byte> BER_encode(const Private_Key& key,
55 RandomNumberGenerator& rng,
56 const std::string& pass,
57 const std::string& pbe_algo = "");
58
59 /**
60 * Get a string containing a PEM encoded private key, encrypting it with a
61 * password.
62 * @param key the key to encode
63 * @param rng the rng to use
64 * @param pass the password to use for encryption
65 * @param pbe_algo the name of the desired password-based encryption
66 algorithm; if empty ("") a reasonable (portable/secure)
67 default will be chosen.
68 * @return encrypted key in PEM form
69 */
70 BOTAN_DLL std::string PEM_encode(const Private_Key& key,
71 RandomNumberGenerator& rng,
72 const std::string& pass,
73 const std::string& pbe_algo = "");
74
75
76 /**
77 * Encode a private key into a pipe.
78 * @deprecated Use PEM_encode or BER_encode instead
79 *
80 * @param key the private key to encode
81 * @param pipe the pipe to feed the encoded key into
82 * @param encoding the encoding type to use
83 */
84 BOTAN_DEPRECATED("Use PEM_encode or BER_encode")
85 inline void encode(const Private_Key& key,
86 Pipe& pipe,
87 X509_Encoding encoding = PEM)
88 {
89 if(encoding == PEM)
90 pipe.write(PKCS8::PEM_encode(key));
91 else
92 pipe.write(PKCS8::BER_encode(key));
93 }
94
95 /**
96 * Encode and encrypt a private key into a pipe.
97 * @deprecated Use PEM_encode or BER_encode instead
98 *
99 * @param key the private key to encode
100 * @param pipe the pipe to feed the encoded key into
101 * @param pass the password to use for encryption
102 * @param rng the rng to use
103 * @param pbe_algo the name of the desired password-based encryption
104 algorithm; if empty ("") a reasonable (portable/secure)
105 default will be chosen.
106 * @param encoding the encoding type to use
107 */
108 BOTAN_DEPRECATED("Use PEM_encode or BER_encode")
109 inline void encrypt_key(const Private_Key& key,
110 Pipe& pipe,
111 RandomNumberGenerator& rng,
112 const std::string& pass,
113 const std::string& pbe_algo = "",
114 X509_Encoding encoding = PEM)
115 {
116 if(encoding == PEM)
117 pipe.write(PKCS8::PEM_encode(key, rng, pass, pbe_algo));
118 else
119 pipe.write(PKCS8::BER_encode(key, rng, pass, pbe_algo));
120 }
121
122 /**
123 * Load a key from a data source.
124 * @param source the data source providing the encoded key
125 * @param rng the rng to use
126 * @param ui the user interface to be used for passphrase dialog
127 * @return loaded private key object
128 */
129 BOTAN_DLL Private_Key* load_key(DataSource& source,
130 RandomNumberGenerator& rng,
131 const User_Interface& ui);
132
133 /** Load a key from a data source.
134 * @param source the data source providing the encoded key
135 * @param rng the rng to use
136 * @param pass the passphrase to decrypt the key. Provide an empty
137 * string if the key is not encoded.
138 * @return loaded private key object
139 */
140 BOTAN_DLL Private_Key* load_key(DataSource& source,
141 RandomNumberGenerator& rng,
142 const std::string& pass = "");
143
144 /**
145 * Load a key from a file.
146 * @param filename the path to the file containing the encoded key
147 * @param rng the rng to use
148 * @param ui the user interface to be used for passphrase dialog
149 * @return loaded private key object
150 */
151 BOTAN_DLL Private_Key* load_key(const std::string& filename,
152 RandomNumberGenerator& rng,
153 const User_Interface& ui);
154
155 /** Load a key from a file.
156 * @param filename the path to the file containing the encoded key
157 * @param rng the rng to use
158 * @param pass the passphrase to decrypt the key. Provide an empty
159 * string if the key is not encoded.
160 * @return loaded private key object
161 */
162 BOTAN_DLL Private_Key* load_key(const std::string& filename,
163 RandomNumberGenerator& rng,
164 const std::string& pass = "");
165
166 /**
167 * Copy an existing encoded key object.
168 * @param key the key to copy
169 * @param rng the rng to use
170 * @return new copy of the key
171 */
172 BOTAN_DLL Private_Key* copy_key(const Private_Key& key,
173 RandomNumberGenerator& rng);
174
175 }
176
177 }
178
179 #endif
Botan::User_Interface
Definition: ui.h:20
Botan::PKCS8::BER_encode
SecureVector< byte > BER_encode(const Private_Key &key)
Definition: pkcs8.cpp:134
Botan::RandomNumberGenerator
Definition: rng.h:20
Botan::Private_Key
Definition: pk_keys.h:86
Botan::X509_Encoding
X509_Encoding
Definition: pubkey_enums.h:67
std
Definition: secmem.h:435
Botan::PKCS8::PEM_encode
std::string PEM_encode(const Private_Key &key)
Definition: pkcs8.cpp:150
Botan::DataSource
Definition: data_src.h:20
Botan::PKCS8::encode
void encode(const Private_Key &key, Pipe &pipe, X509_Encoding encoding=PEM)
Definition: pkcs8.h:85
Botan::Decoding_Error
Definition: exceptn.h:138
Botan::PKCS8::copy_key
Private_Key * copy_key(const Private_Key &key, RandomNumberGenerator &rng)
Definition: pkcs8.cpp:250
Botan
Definition: algo_base.h:14
Botan::PEM
Definition: pubkey_enums.h:67
Botan::PKCS8::encrypt_key
void encrypt_key(const Private_Key &key, Pipe &pipe, RandomNumberGenerator &rng, const std::string &pass, const std::string &pbe_algo="", X509_Encoding encoding=PEM)
Definition: pkcs8.h:109
Botan::PKCS8_Exception
Definition: pkcs8.h:19
Botan::Pipe
Definition: pipe.h:25
Botan::PKCS8::load_key
Private_Key * load_key(DataSource &source, RandomNumberGenerator &rng, const User_Interface &ui)
Definition: pkcs8.cpp:201
Botan::PKCS8_Exception::PKCS8_Exception
PKCS8_Exception(const std::string &error)
Definition: pkcs8.h:21