Botan  1.11.15
src/lib/pubkey/pkcs8.h
Go to the documentation of this file.
00001 /*
00002 * PKCS #8
00003 * (C) 1999-2007 Jack Lloyd
00004 *
00005 * Botan is released under the Simplified BSD License (see license.txt)
00006 */
00007 
00008 #ifndef BOTAN_PKCS8_H__
00009 #define BOTAN_PKCS8_H__
00010 
00011 #include <botan/x509_key.h>
00012 #include <functional>
00013 #include <chrono>
00014 
00015 namespace Botan {
00016 
00017 /**
00018 * PKCS #8 General Exception
00019 */
00020 struct BOTAN_DLL PKCS8_Exception : public Decoding_Error
00021    {
00022    PKCS8_Exception(const std::string& error) :
00023       Decoding_Error("PKCS #8: " + error) {}
00024    };
00025 
00026 /**
00027 * This namespace contains functions for handling PKCS #8 private keys
00028 */
00029 namespace PKCS8 {
00030 
00031 /**
00032 * BER encode a private key
00033 * @param key the private key to encode
00034 * @return BER encoded key
00035 */
00036 BOTAN_DLL secure_vector<byte> BER_encode(const Private_Key& key);
00037 
00038 /**
00039 * Get a string containing a PEM encoded private key.
00040 * @param key the key to encode
00041 * @return encoded key
00042 */
00043 BOTAN_DLL std::string PEM_encode(const Private_Key& key);
00044 
00045 /**
00046 * Encrypt a key using PKCS #8 encryption
00047 * @param key the key to encode
00048 * @param rng the rng to use
00049 * @param pass the password to use for encryption
00050 * @param msec number of milliseconds to run the password derivation
00051 * @param pbe_algo the name of the desired password-based encryption
00052          algorithm; if empty ("") a reasonable (portable/secure)
00053          default will be chosen.
00054 * @return encrypted key in binary BER form
00055 */
00056 BOTAN_DLL std::vector<byte>
00057 BER_encode(const Private_Key& key,
00058            RandomNumberGenerator& rng,
00059            const std::string& pass,
00060            std::chrono::milliseconds msec = std::chrono::milliseconds(300),
00061            const std::string& pbe_algo = "");
00062 
00063 /**
00064 * Get a string containing a PEM encoded private key, encrypting it with a
00065 * password.
00066 * @param key the key to encode
00067 * @param rng the rng to use
00068 * @param pass the password to use for encryption
00069 * @param msec number of milliseconds to run the password derivation
00070 * @param pbe_algo the name of the desired password-based encryption
00071          algorithm; if empty ("") a reasonable (portable/secure)
00072          default will be chosen.
00073 * @return encrypted key in PEM form
00074 */
00075 BOTAN_DLL std::string
00076 PEM_encode(const Private_Key& key,
00077            RandomNumberGenerator& rng,
00078            const std::string& pass,
00079            std::chrono::milliseconds msec = std::chrono::milliseconds(300),
00080            const std::string& pbe_algo = "");
00081 
00082 /**
00083 * Load a key from a data source.
00084 * @param source the data source providing the encoded key
00085 * @param rng the rng to use
00086 * @param get_passphrase a function that returns passphrases
00087 * @return loaded private key object
00088 */
00089 BOTAN_DLL Private_Key* load_key(
00090   DataSource& source,
00091   RandomNumberGenerator& rng,
00092   std::function<std::string ()> get_passphrase);
00093 
00094 /** Load a key from a data source.
00095 * @param source the data source providing the encoded key
00096 * @param rng the rng to use
00097 * @param pass the passphrase to decrypt the key. Provide an empty
00098 * string if the key is not encrypted
00099 * @return loaded private key object
00100 */
00101 BOTAN_DLL Private_Key* load_key(DataSource& source,
00102                                 RandomNumberGenerator& rng,
00103                                 const std::string& pass = "");
00104 
00105 /**
00106 * Load a key from a file.
00107 * @param filename the path to the file containing the encoded key
00108 * @param rng the rng to use
00109 * @param get_passphrase a function that returns passphrases
00110 * @return loaded private key object
00111 */
00112 BOTAN_DLL Private_Key* load_key(
00113   const std::string& filename,
00114   RandomNumberGenerator& rng,
00115   std::function<std::string ()> get_passphrase);
00116 
00117 /** Load a key from a file.
00118 * @param filename the path to the file containing the encoded key
00119 * @param rng the rng to use
00120 * @param pass the passphrase to decrypt the key. Provide an empty
00121 * string if the key is not encrypted
00122 * @return loaded private key object
00123 */
00124 BOTAN_DLL Private_Key* load_key(const std::string& filename,
00125                                 RandomNumberGenerator& rng,
00126                                 const std::string& pass = "");
00127 
00128 /**
00129 * Copy an existing encoded key object.
00130 * @param key the key to copy
00131 * @param rng the rng to use
00132 * @return new copy of the key
00133 */
00134 BOTAN_DLL Private_Key* copy_key(const Private_Key& key,
00135                                 RandomNumberGenerator& rng);
00136 
00137 }
00138 
00139 }
00140 
00141 #endif