aboutsummaryrefslogtreecommitdiffstats
path: root/src/pubkey
diff options
context:
space:
mode:
authorlloyd <lloyd@randombit.net>2008-10-13 19:01:31 +0000
committerlloyd <lloyd@randombit.net>2008-10-13 19:01:31 +0000
commit0472f4f7ea182633d8ec758d14a66e2cb1db7044 (patch)
tree577bd7ca1e6a82ca3ae34f41307cbc508e3c96f9 /src/pubkey
parent2b9da25f8e1d0d5df5f4e2fb05beba519bb6949f (diff)
InSiTo Doxygen comments for pubkey.h
Diffstat (limited to 'src/pubkey')
-rw-r--r--src/pubkey/pubkey/pubkey.h297
1 files changed, 233 insertions, 64 deletions
diff --git a/src/pubkey/pubkey/pubkey.h b/src/pubkey/pubkey/pubkey.h
index 52f14c5b3..4a75e7be8 100644
--- a/src/pubkey/pubkey/pubkey.h
+++ b/src/pubkey/pubkey/pubkey.h
@@ -14,57 +14,138 @@ namespace Botan {
enum Signature_Format { IEEE_1363, DER_SEQUENCE };
-/*************************************************
-* Public Key Encryptor *
-*************************************************/
+/**
+* Public Key Encryptor
+*/
class BOTAN_DLL PK_Encryptor
{
public:
- SecureVector<byte> encrypt(const byte[], u32bit,
- RandomNumberGenerator&) const;
- SecureVector<byte> encrypt(const MemoryRegion<byte>&,
- RandomNumberGenerator&) const;
+ /**
+ * Encrypt a message.
+ * @param in the message as a byte array
+ * @param length the length of the above byte array
+ * @param rng the random number source to use
+ * @return the encrypted message
+ */
+ SecureVector<byte> encrypt(const byte in[], u32bit length,
+ RandomNumberGenerator& rng) const;
+
+ /**
+ * Encrypt a message.
+ * @param in the message
+ * @param rng the random number source to use
+ * @return the encrypted message
+ */
+ SecureVector<byte> encrypt(const MemoryRegion<byte>& in,
+ RandomNumberGenerator& rng) const;
+
+ /**
+ * Return the maximum allowed message size in bytes.
+ * @return the maximum message size in bytes
+ */
virtual u32bit maximum_input_size() const = 0;
+
virtual ~PK_Encryptor() {}
private:
virtual SecureVector<byte> enc(const byte[], u32bit,
RandomNumberGenerator&) const = 0;
};
-/*************************************************
-* Public Key Decryptor *
-*************************************************/
+/**
+* Public Key Decryptor
+*/
class BOTAN_DLL PK_Decryptor
{
public:
- SecureVector<byte> decrypt(const byte[], u32bit) const;
- SecureVector<byte> decrypt(const MemoryRegion<byte>&) const;
+ /**
+ * Decrypt a ciphertext.
+ * @param in the ciphertext as a byte array
+ * @param length the length of the above byte array
+ * @return the decrypted message
+ */
+ SecureVector<byte> decrypt(const byte in[], u32bit length) const;
+
+ /**
+ * Decrypt a ciphertext.
+ * @param in the ciphertext
+ * @return the decrypted message
+ */
+ SecureVector<byte> decrypt(const MemoryRegion<byte>& in) const;
+
virtual ~PK_Decryptor() {}
private:
virtual SecureVector<byte> dec(const byte[], u32bit) const = 0;
};
-/*************************************************
-* Public Key Signer *
-*************************************************/
+/**
+* Public Key Signer. Use the sign_message() functions for small
+* messages. Use multiple calls update() to process large messages and
+* generate the signature by finally calling signature().
+*/
class BOTAN_DLL PK_Signer
{
public:
- SecureVector<byte> sign_message(const byte[], u32bit,
- RandomNumberGenerator&);
- SecureVector<byte> sign_message(const MemoryRegion<byte>&,
- RandomNumberGenerator&);
+ /**
+ * Sign a message.
+ * @param in the message to sign as a byte array
+ * @param length the length of the above byte array
+ * @param rng the rng to use
+ * @return the signature
+ */
+ SecureVector<byte> sign_message(const byte in[], u32bit length,
+ RandomNumberGenerator& rng);
+
+ /**
+ * Sign a message.
+ * @param in the message to sign
+ * @param rng the rng to use
+ * @return the signature
+ */
+ SecureVector<byte> sign_message(const MemoryRegion<byte>& in,
+ RandomNumberGenerator& rng);
+
+ /**
+ * Add a message part (single byte).
+ * @param the byte to add
+ */
+ void update(byte in);
+
+ /**
+ * Add a message part.
+ * @param in the message part to add as a byte array
+ * @param length the length of the above byte array
+ */
+ void update(const byte in[], u32bit length);
+
+ /**
+ * Add a message part.
+ * @param in the message part to add
+ */
+ void update(const MemoryRegion<byte>& in);
+
+ /**
+ * Get the signature of the so far processed message (provided by the
+ * calls to update()).
+ * @param rng the rng to use
+ * @return the signature of the total message
+ */
+ SecureVector<byte> signature(RandomNumberGenerator& rng);
+
+ /**
+ * Set the output format of the signature.
+ * @param format the signature format to use
+ */
+ void set_output_format(Signature_Format format);
+
+ /**
+ * Construct a PK Signer.
+ * @param key the key to use inside this signer
+ * @param emsa_name the name of the emsa to use.
+ * An example would be "EMSA1(SHA-224)".
+ */
+ PK_Signer(const PK_Signing_Key& key, const std::string& emsa_name);
- void update(byte);
- void update(const byte[], u32bit);
- void update(const MemoryRegion<byte>&);
-
- SecureVector<byte> signature(RandomNumberGenerator&);
-
- void set_output_format(Signature_Format);
-
- PK_Signer(const PK_Signing_Key&, const std::string&);
~PK_Signer() { delete emsa; }
private:
PK_Signer(const PK_Signer&);
@@ -75,26 +156,85 @@ class BOTAN_DLL PK_Signer
EMSA* emsa;
};
-/*************************************************
-* Public Key Verifier *
-*************************************************/
+/**
+* Public Key Verifier. Use the verify_message() functions for small
+* messages. Use multiple calls update() to process large messages and
+* verify the signature by finally calling check_signature().
+*/
class BOTAN_DLL PK_Verifier
{
public:
- bool verify_message(const byte[], u32bit, const byte[], u32bit);
- bool verify_message(const MemoryRegion<byte>&,
- const MemoryRegion<byte>&);
-
- void update(byte);
- void update(const byte[], u32bit);
- void update(const MemoryRegion<byte>&);
-
- bool check_signature(const byte[], u32bit);
- bool check_signature(const MemoryRegion<byte>&);
+ /**
+ * Verify a signature.
+ * @param msg the message that the signature belongs to, as a byte array
+ * @param msg_length the length of the above byte array msg
+ * @param sig the signature as a byte array
+ * @param sig_length the length of the above byte array sig
+ * @return true if the signature is valid
+ */
+ bool verify_message(const byte msg[], u32bit msg_length,
+ const byte sig[], u32bit sig_length);
+ /**
+ * Verify a signature.
+ * @param msg the message that the signature belongs to
+ * @param sig the signature
+ * @return true if the signature is valid
+ */
+ bool verify_message(const MemoryRegion<byte>& msg,
+ const MemoryRegion<byte>& sig);
+
+ /**
+ * Add a message part (single byte) of the message corresponding to the
+ * signature to be verified.
+ * @param msg_part the byte to add
+ */
+ void update(byte msg_part);
+
+ /**
+ * Add a message part of the message corresponding to the
+ * signature to be verified.
+ * @param msg_part the new message part as a byte array
+ * @param length the length of the above byte array
+ */
+ void update(const byte msg_part[], u32bit length);
+
+ /**
+ * Add a message part of the message corresponding to the
+ * signature to be verified.
+ * @param msg_part the new message part
+ */
+ void update(const MemoryRegion<byte>& msg_part);
+
+ /**
+ * Check the signature of the buffered message, i.e. the one build
+ * by successive calls to update.
+ * @param sig the signature to be verified as a byte array
+ * @param length the length of the above byte array
+ * @return true if the signature is valid, false otherwise
+ */
+ bool check_signature(const byte sig[], u32bit length);
+
+ /**
+ * Check the signature of the buffered message, i.e. the one build
+ * by successive calls to update.
+ * @param sig the signature to be verified
+ * @return true if the signature is valid, false otherwise
+ */
+ bool check_signature(const MemoryRegion<byte>& sig);
+
+ /**
+ * Set the format of the signatures fed to this verifier.
+ * @param format the signature format to use
+ */
+ void set_input_format(Signature_Format format);
+
+ /**
+ * Construct a PK Verifier.
+ * @param emsa_name the name of the emsa to use.
+ * An example would be "EMSA1(SHA-224)".
+ */
+ PK_Verifier(const std::string& emsa_name);
- void set_input_format(Signature_Format);
-
- PK_Verifier(const std::string&);
virtual ~PK_Verifier();
protected:
virtual bool validate_signature(const MemoryRegion<byte>&,
@@ -118,9 +258,14 @@ class BOTAN_DLL PK_Key_Agreement
SymmetricKey derive_key(u32bit, const byte[], u32bit,
const std::string& = "") const;
SymmetricKey derive_key(u32bit, const byte[], u32bit,
- const byte[], u32bit) const;
-
- PK_Key_Agreement(const PK_Key_Agreement_Key&, const std::string&);
+ const byte[], u32bit) const;
+
+ /**
+ * Construct a PK Key Agreement.
+ * @param key the key to use
+ * @param kdf_name the name of the key derivation function to use
+ */
+ PK_Key_Agreement(const PK_Key_Agreement_Key& key, const std::string& kdf_name);
private:
PK_Key_Agreement(const PK_Key_Agreement_Key&);
PK_Key_Agreement& operator=(const PK_Key_Agreement&);
@@ -129,17 +274,22 @@ class BOTAN_DLL PK_Key_Agreement
const std::string kdf_name;
};
-/*************************************************
-* Encryption with an MR algorithm and an EME *
-*************************************************/
+/**
+* Encryption with an MR algorithm and an EME.
+*/
class BOTAN_DLL PK_Encryptor_MR_with_EME : public PK_Encryptor
{
public:
u32bit maximum_input_size() const;
- PK_Encryptor_MR_with_EME(const PK_Encrypting_Key&, const std::string&);
- ~PK_Encryptor_MR_with_EME() { delete encoder; }
+ /**
+ * Construct an instance.
+ * @param key the key to use inside the decryptor
+ * @param eme the name of the eme to use
+ */
+ PK_Encryptor_MR_with_EME(const PK_Encrypting_Key& key, const std::string& eme);
+ ~PK_Encryptor_MR_with_EME() { delete encoder; }
private:
PK_Encryptor_MR_with_EME(const PK_Encryptor_MR_with_EME&);
PK_Encryptor_MR_with_EME& operator=(const PK_Encryptor_MR_with_EME&);
@@ -151,13 +301,19 @@ class BOTAN_DLL PK_Encryptor_MR_with_EME : public PK_Encryptor
const EME* encoder;
};
-/*************************************************
-* Decryption with an MR algorithm and an EME *
-*************************************************/
+/**
+* Decryption with an MR algorithm and an EME.
+*/
class BOTAN_DLL PK_Decryptor_MR_with_EME : public PK_Decryptor
{
public:
- PK_Decryptor_MR_with_EME(const PK_Decrypting_Key&, const std::string&);
+ /**
+ * Construct an instance.
+ * @param key the key to use inside the encryptor
+ * @param eme the name of the EME to use
+ */
+ PK_Decryptor_MR_with_EME(const PK_Decrypting_Key& key, const std::string& eme);
+
~PK_Decryptor_MR_with_EME() { delete encoder; }
private:
PK_Decryptor_MR_with_EME(const PK_Decryptor_MR_with_EME&);
@@ -169,13 +325,20 @@ class BOTAN_DLL PK_Decryptor_MR_with_EME : public PK_Decryptor
const EME* encoder;
};
-/*************************************************
-* Public Key Verifier with Message Recovery *
-*************************************************/
+/**
+* Public Key Verifier with Message Recovery.
+*/
class BOTAN_DLL PK_Verifier_with_MR : public PK_Verifier
{
public:
- PK_Verifier_with_MR(const PK_Verifying_with_MR_Key&, const std::string&);
+ /**
+ * Construct an instance.
+ * @param key the key to use inside the verifier
+ * @param emsa_name the name of the EMSA to use
+ */
+ PK_Verifier_with_MR(const PK_Verifying_with_MR_Key& key,
+ const std::string& emsa_name);
+
private:
PK_Verifier_with_MR(const PK_Verifying_with_MR_Key&);
PK_Verifier_with_MR& operator=(const PK_Verifier_with_MR&);
@@ -187,13 +350,19 @@ class BOTAN_DLL PK_Verifier_with_MR : public PK_Verifier
const PK_Verifying_with_MR_Key& key;
};
-/*************************************************
-* Public Key Verifier without Message Recovery *
-*************************************************/
+/**
+* Public Key Verifier without Message Recovery
+*/
class BOTAN_DLL PK_Verifier_wo_MR : public PK_Verifier
{
public:
- PK_Verifier_wo_MR(const PK_Verifying_wo_MR_Key&, const std::string&);
+ /**
+ * Construct an instance.
+ * @param key the key to use inside the verifier
+ * @param emsa_name the name of the EMSA to use
+ */
+ PK_Verifier_wo_MR(const PK_Verifying_wo_MR_Key& key, const std::string& emsa_name);
+
private:
PK_Verifier_wo_MR(const PK_Verifying_wo_MR_Key&);
PK_Verifier_wo_MR& operator=(const PK_Verifier_wo_MR&);