diff options
author | lloyd <lloyd@randombit.net> | 2008-10-13 19:44:42 +0000 |
---|---|---|
committer | lloyd <lloyd@randombit.net> | 2008-10-13 19:44:42 +0000 |
commit | 86a53729e998f3ba7554625df0851a72650767d4 (patch) | |
tree | e6c7359aa3f3cc759120965d54a7c2a7ab45892c /src | |
parent | f4197e97cd5ff49089740e68a625bd2429c30cd7 (diff) |
Doxygen comments for pkcs8.h from InSiTo
Diffstat (limited to 'src')
-rw-r--r-- | src/pubkey/pubkey/pkcs8.h | 158 |
1 files changed, 127 insertions, 31 deletions
diff --git a/src/pubkey/pubkey/pkcs8.h b/src/pubkey/pubkey/pkcs8.h index 383b1604a..0598e7c68 100644 --- a/src/pubkey/pubkey/pkcs8.h +++ b/src/pubkey/pubkey/pkcs8.h @@ -12,13 +12,24 @@ namespace Botan { -/************************************************* -* PKCS #8 Private Key Encoder * -*************************************************/ +/** +* PKCS #8 Private Key Encoder. +*/ class BOTAN_DLL PKCS8_Encoder { public: + /** + * Get the algorithm identifier associated with the scheme + * this encoders key is part of. + * @return the algorithm identifier + */ virtual AlgorithmIdentifier alg_id() const = 0; + + /** + * Get the DER encoded key. + * @return the DER encoded key + */ + // XXX: Why not SecureVector? virtual MemoryVector<byte> key_bits() const = 0; virtual ~PKCS8_Encoder() {} }; @@ -29,14 +40,24 @@ class BOTAN_DLL PKCS8_Encoder class BOTAN_DLL PKCS8_Decoder { public: + /** + * Set the algorithm identifier associated with the scheme + * this decoders key is part of. + * @param alg_id the algorithm identifier + */ virtual void alg_id(const AlgorithmIdentifier&) = 0; + + /** + * Set the DER encoded key. + * @param key the DER encoded key + */ virtual void key_bits(const MemoryRegion<byte>&) = 0; virtual ~PKCS8_Decoder() {} }; -/************************************************* -* PKCS #8 General Exception * -*************************************************/ +/** +* PKCS #8 General Exception +*/ struct BOTAN_DLL PKCS8_Exception : public Decoding_Error { PKCS8_Exception(const std::string& error) : @@ -45,37 +66,112 @@ struct BOTAN_DLL PKCS8_Exception : public Decoding_Error namespace PKCS8 { -/************************************************* -* PKCS #8 Private Key Encoding/Decoding * -*************************************************/ -BOTAN_DLL void encode(const Private_Key&, Pipe&, X509_Encoding = PEM); -BOTAN_DLL std::string PEM_encode(const Private_Key&); - -BOTAN_DLL void encrypt_key(const Private_Key&, - Pipe&, - RandomNumberGenerator&, - const std::string&, - const std::string& = "", - X509_Encoding = PEM); +/** +* Encode a private key into a pipe. +* @param key the private key to encode +* @param pipe the pipe to feed the encoded key into +* @param enc the encoding type to use +*/ +BOTAN_DLL void encode(const Private_Key& key, Pipe& pipe, + X509_Encoding enc = PEM); + +/** +* Encode and encrypt a private key into a pipe. +* @param key the private key to encode +* @param pipe the pipe to feed the encoded key into +* @param pass the password to use for encryption +* @param rng the rng to use +* @param pbe_algo the name of the desired password-based encryption algorithm. +* Provide an empty string to use the default PBE defined in the configuration +* under base/default_pbe. +* @param enc the encoding type to use +*/ +BOTAN_DLL void encrypt_key(const Private_Key& key, + Pipe& pipe, + RandomNumberGenerator& rng, + const std::string& pass, + const std::string& pbe_algo = "", + X509_Encoding enc = PEM); + + +/** +* Get a string containing a PEM encoded private key. +* @param key the key to encode +* @return the encoded key +*/ +BOTAN_DLL std::string PEM_encode(const Private_Key& key); + +/** +* Get a string containing a PEM encoded private key, encrypting it with a +* password. +* @param key the key to encode +* @param rng the rng to use +* @param pass the password to use for encryption +* @param pbe_algo the name of the desired password-based encryption algorithm. +* Provide an empty string to use the default PBE defined in the configuration +* under base/default_pbe. +*/ +BOTAN_DLL std::string PEM_encode(const Private_Key& key, + RandomNumberGenerator& rng, + const std::string& pass, + const std::string& pbe_algo = ""); BOTAN_DLL std::string PEM_encode(const Private_Key&, - RandomNumberGenerator&, const std::string&, const std::string& = ""); -BOTAN_DLL Private_Key* load_key(DataSource&, RandomNumberGenerator&, - const User_Interface&); -BOTAN_DLL Private_Key* load_key(DataSource&, RandomNumberGenerator&, - const std::string& = ""); - -BOTAN_DLL Private_Key* load_key(const std::string&, - RandomNumberGenerator&, - const User_Interface&); -BOTAN_DLL Private_Key* load_key(const std::string&, - RandomNumberGenerator&, - const std::string& = ""); -BOTAN_DLL Private_Key* copy_key(const Private_Key&, +/** +* Load a key from a data source. +* @param source the data source providing the encoded key +* @param rng the rng to use +* @param ui the user interface to be used for passphrase dialog +* @return the loaded private key object +*/ +BOTAN_DLL Private_Key* load_key(DataSource& source, + RandomNumberGenerator& rng, + const User_Interface& ui); + +/** Load a key from a data source. +* @param source the data source providing the encoded key +* @param rng the rng to use +* @param pass the passphrase to decrypt the key. Provide an empty +* string if the key is not encoded. +* @return the loaded private key object +*/ +BOTAN_DLL Private_Key* load_key(DataSource& source, + RandomNumberGenerator& rng, + const std::string& pass = ""); + +/** +* Load a key from a file. +* @param filename the path to the file containing the encoded key +* @param rng the rng to use +* @param ui the user interface to be used for passphrase dialog +* @return the loaded private key object +*/ +BOTAN_DLL Private_Key* load_key(const std::string& filename, + RandomNumberGenerator& rng, + const User_Interface& ui); + +/** Load a key from a file. +* @param filename the path to the file containing the encoded key +* @param rng the rng to use +* @param pass the passphrase to decrypt the key. Provide an empty +* string if the key is not encoded. +* @return the loaded private key object +*/ +BOTAN_DLL Private_Key* load_key(const std::string& filename, + RandomNumberGenerator& rng, + const std::string& pass = ""); + +/** +* Copy an existing encoded key object. +* @param key the key to copy +* @param rng the rng to use +* @return the new copy of the key +*/ +BOTAN_DLL Private_Key* copy_key(const Private_Key& key, RandomNumberGenerator& rng); } |