Botan  1.10.9
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,
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,
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,
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,
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,
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,
174 
175 }
176 
177 }
178 
179 #endif
SecureVector< byte > BER_encode(const Private_Key &key)
Definition: pkcs8.cpp:134
X509_Encoding
Definition: pubkey_enums.h:67
Definition: secmem.h:422
std::string PEM_encode(const Private_Key &key)
Definition: pkcs8.cpp:150
RandomNumberGenerator * rng
Definition: global_rng.cpp:165
void encode(const Private_Key &key, Pipe &pipe, X509_Encoding encoding=PEM)
Definition: pkcs8.h:85
Private_Key * copy_key(const Private_Key &key, RandomNumberGenerator &rng)
Definition: pkcs8.cpp:250
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
Private_Key * load_key(DataSource &source, RandomNumberGenerator &rng, const User_Interface &ui)
Definition: pkcs8.cpp:201
PKCS8_Exception(const std::string &error)
Definition: pkcs8.h:21