aboutsummaryrefslogtreecommitdiffstats
path: root/src
diff options
context:
space:
mode:
authorlloyd <lloyd@randombit.net>2008-10-13 19:44:42 +0000
committerlloyd <lloyd@randombit.net>2008-10-13 19:44:42 +0000
commit86a53729e998f3ba7554625df0851a72650767d4 (patch)
treee6c7359aa3f3cc759120965d54a7c2a7ab45892c /src
parentf4197e97cd5ff49089740e68a625bd2429c30cd7 (diff)
Doxygen comments for pkcs8.h from InSiTo
Diffstat (limited to 'src')
-rw-r--r--src/pubkey/pubkey/pkcs8.h158
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);
}