Botan  1.11.15
src/lib/pubkey/pubkey.h
Go to the documentation of this file.
00001 /*
00002 * Public Key Interface
00003 * (C) 1999-2010 Jack Lloyd
00004 *
00005 * Botan is released under the Simplified BSD License (see license.txt)
00006 */
00007 
00008 #ifndef BOTAN_PUBKEY_H__
00009 #define BOTAN_PUBKEY_H__
00010 
00011 #include <botan/pk_keys.h>
00012 #include <botan/pk_ops.h>
00013 #include <botan/symkey.h>
00014 #include <botan/rng.h>
00015 #include <botan/eme.h>
00016 #include <botan/emsa.h>
00017 #include <botan/kdf.h>
00018 
00019 namespace Botan {
00020 
00021 /**
00022 * The two types of signature format supported by Botan.
00023 */
00024 enum Signature_Format { IEEE_1363, DER_SEQUENCE };
00025 
00026 /**
00027 * Enum marking if protection against fault attacks should be used
00028 */
00029 enum Fault_Protection {
00030    ENABLE_FAULT_PROTECTION,
00031    DISABLE_FAULT_PROTECTION
00032 };
00033 
00034 /**
00035 * Public Key Encryptor
00036 */
00037 class BOTAN_DLL PK_Encryptor
00038    {
00039    public:
00040 
00041       /**
00042       * Encrypt a message.
00043       * @param in the message as a byte array
00044       * @param length the length of the above byte array
00045       * @param rng the random number source to use
00046       * @return encrypted message
00047       */
00048       std::vector<byte> encrypt(const byte in[], size_t length,
00049                                  RandomNumberGenerator& rng) const
00050          {
00051          return enc(in, length, rng);
00052          }
00053 
00054       /**
00055       * Encrypt a message.
00056       * @param in the message
00057       * @param rng the random number source to use
00058       * @return encrypted message
00059       */
00060       template<typename Alloc>
00061       std::vector<byte> encrypt(const std::vector<byte, Alloc>& in,
00062                                 RandomNumberGenerator& rng) const
00063          {
00064          return enc(&in[0], in.size(), rng);
00065          }
00066 
00067       /**
00068       * Return the maximum allowed message size in bytes.
00069       * @return maximum message size in bytes
00070       */
00071       virtual size_t maximum_input_size() const = 0;
00072 
00073       PK_Encryptor() {}
00074       virtual ~PK_Encryptor() {}
00075 
00076       PK_Encryptor(const PK_Encryptor&) = delete;
00077 
00078       PK_Encryptor& operator=(const PK_Encryptor&) = delete;
00079 
00080    private:
00081       virtual std::vector<byte> enc(const byte[], size_t,
00082                                      RandomNumberGenerator&) const = 0;
00083    };
00084 
00085 /**
00086 * Public Key Decryptor
00087 */
00088 class BOTAN_DLL PK_Decryptor
00089    {
00090    public:
00091       /**
00092       * Decrypt a ciphertext.
00093       * @param in the ciphertext as a byte array
00094       * @param length the length of the above byte array
00095       * @return decrypted message
00096       */
00097       secure_vector<byte> decrypt(const byte in[], size_t length) const
00098          {
00099          return dec(in, length);
00100          }
00101 
00102       /**
00103       * Decrypt a ciphertext.
00104       * @param in the ciphertext
00105       * @return decrypted message
00106       */
00107       template<typename Alloc>
00108       secure_vector<byte> decrypt(const std::vector<byte, Alloc>& in) const
00109          {
00110          return dec(&in[0], in.size());
00111          }
00112 
00113       PK_Decryptor() {}
00114       virtual ~PK_Decryptor() {}
00115 
00116       PK_Decryptor(const PK_Decryptor&) = delete;
00117       PK_Decryptor& operator=(const PK_Decryptor&) = delete;
00118 
00119    private:
00120       virtual secure_vector<byte> dec(const byte[], size_t) const = 0;
00121    };
00122 
00123 /**
00124 * Public Key Signer. Use the sign_message() functions for small
00125 * messages. Use multiple calls update() to process large messages and
00126 * generate the signature by finally calling signature().
00127 */
00128 class BOTAN_DLL PK_Signer
00129    {
00130    public:
00131       /**
00132       * Sign a message.
00133       * @param in the message to sign as a byte array
00134       * @param length the length of the above byte array
00135       * @param rng the rng to use
00136       * @return signature
00137       */
00138       std::vector<byte> sign_message(const byte in[], size_t length,
00139                                       RandomNumberGenerator& rng);
00140 
00141       /**
00142       * Sign a message.
00143       * @param in the message to sign
00144       * @param rng the rng to use
00145       * @return signature
00146       */
00147       std::vector<byte> sign_message(const std::vector<byte>& in,
00148                                      RandomNumberGenerator& rng)
00149          { return sign_message(&in[0], in.size(), rng); }
00150 
00151       std::vector<byte> sign_message(const secure_vector<byte>& in,
00152                                      RandomNumberGenerator& rng)
00153          { return sign_message(&in[0], in.size(), rng); }
00154 
00155       /**
00156       * Add a message part (single byte).
00157       * @param in the byte to add
00158       */
00159       void update(byte in) { update(&in, 1); }
00160 
00161       /**
00162       * Add a message part.
00163       * @param in the message part to add as a byte array
00164       * @param length the length of the above byte array
00165       */
00166       void update(const byte in[], size_t length);
00167 
00168       /**
00169       * Add a message part.
00170       * @param in the message part to add
00171       */
00172       void update(const std::vector<byte>& in) { update(&in[0], in.size()); }
00173 
00174       /**
00175       * Get the signature of the so far processed message (provided by the
00176       * calls to update()).
00177       * @param rng the rng to use
00178       * @return signature of the total message
00179       */
00180       std::vector<byte> signature(RandomNumberGenerator& rng);
00181 
00182       /**
00183       * Set the output format of the signature.
00184       * @param format the signature format to use
00185       */
00186       void set_output_format(Signature_Format format) { m_sig_format = format; }
00187 
00188       /**
00189       * Construct a PK Signer.
00190       * @param key the key to use inside this signer
00191       * @param emsa the EMSA to use
00192       * An example would be "EMSA1(SHA-224)".
00193       * @param format the signature format to use
00194       * @param prot says if fault protection should be enabled
00195       */
00196       PK_Signer(const Private_Key& key,
00197                 const std::string& emsa,
00198                 Signature_Format format = IEEE_1363,
00199                 Fault_Protection prot = ENABLE_FAULT_PROTECTION);
00200    private:
00201       bool self_test_signature(const std::vector<byte>& msg,
00202                                const std::vector<byte>& sig) const;
00203 
00204       std::unique_ptr<PK_Ops::Signature> m_op;
00205       std::unique_ptr<PK_Ops::Verification> m_verify_op;
00206       std::unique_ptr<EMSA> m_emsa;
00207       Signature_Format m_sig_format;
00208    };
00209 
00210 /**
00211 * Public Key Verifier. Use the verify_message() functions for small
00212 * messages. Use multiple calls update() to process large messages and
00213 * verify the signature by finally calling check_signature().
00214 */
00215 class BOTAN_DLL PK_Verifier
00216    {
00217    public:
00218       /**
00219       * Verify a signature.
00220       * @param msg the message that the signature belongs to, as a byte array
00221       * @param msg_length the length of the above byte array msg
00222       * @param sig the signature as a byte array
00223       * @param sig_length the length of the above byte array sig
00224       * @return true if the signature is valid
00225       */
00226       bool verify_message(const byte msg[], size_t msg_length,
00227                           const byte sig[], size_t sig_length);
00228       /**
00229       * Verify a signature.
00230       * @param msg the message that the signature belongs to
00231       * @param sig the signature
00232       * @return true if the signature is valid
00233       */
00234       template<typename Alloc, typename Alloc2>
00235       bool verify_message(const std::vector<byte, Alloc>& msg,
00236                           const std::vector<byte, Alloc2>& sig)
00237          {
00238          return verify_message(&msg[0], msg.size(),
00239                                &sig[0], sig.size());
00240          }
00241 
00242       /**
00243       * Add a message part (single byte) of the message corresponding to the
00244       * signature to be verified.
00245       * @param in the byte to add
00246       */
00247       void update(byte in) { update(&in, 1); }
00248 
00249       /**
00250       * Add a message part of the message corresponding to the
00251       * signature to be verified.
00252       * @param msg_part the new message part as a byte array
00253       * @param length the length of the above byte array
00254       */
00255       void update(const byte msg_part[], size_t length);
00256 
00257       /**
00258       * Add a message part of the message corresponding to the
00259       * signature to be verified.
00260       * @param in the new message part
00261       */
00262       void update(const std::vector<byte>& in)
00263          { update(&in[0], in.size()); }
00264 
00265       /**
00266       * Check the signature of the buffered message, i.e. the one build
00267       * by successive calls to update.
00268       * @param sig the signature to be verified as a byte array
00269       * @param length the length of the above byte array
00270       * @return true if the signature is valid, false otherwise
00271       */
00272       bool check_signature(const byte sig[], size_t length);
00273 
00274       /**
00275       * Check the signature of the buffered message, i.e. the one build
00276       * by successive calls to update.
00277       * @param sig the signature to be verified
00278       * @return true if the signature is valid, false otherwise
00279       */
00280       template<typename Alloc>
00281       bool check_signature(const std::vector<byte, Alloc>& sig)
00282          {
00283          return check_signature(&sig[0], sig.size());
00284          }
00285 
00286       /**
00287       * Set the format of the signatures fed to this verifier.
00288       * @param format the signature format to use
00289       */
00290       void set_input_format(Signature_Format format);
00291 
00292       /**
00293       * Construct a PK Verifier.
00294       * @param pub_key the public key to verify against
00295       * @param emsa the EMSA to use (eg "EMSA3(SHA-1)")
00296       * @param format the signature format to use
00297       */
00298       PK_Verifier(const Public_Key& pub_key,
00299                   const std::string& emsa,
00300                   Signature_Format format = IEEE_1363);
00301    private:
00302       bool validate_signature(const secure_vector<byte>& msg,
00303                               const byte sig[], size_t sig_len);
00304 
00305       std::unique_ptr<PK_Ops::Verification> m_op;
00306       std::unique_ptr<EMSA> m_emsa;
00307       Signature_Format m_sig_format;
00308    };
00309 
00310 /**
00311 * Key used for key agreement
00312 */
00313 class BOTAN_DLL PK_Key_Agreement
00314    {
00315    public:
00316 
00317       /*
00318       * Perform Key Agreement Operation
00319       * @param key_len the desired key output size
00320       * @param in the other parties key
00321       * @param in_len the length of in in bytes
00322       * @param params extra derivation params
00323       * @param params_len the length of params in bytes
00324       */
00325       SymmetricKey derive_key(size_t key_len,
00326                               const byte in[],
00327                               size_t in_len,
00328                               const byte params[],
00329                               size_t params_len) const;
00330 
00331       /*
00332       * Perform Key Agreement Operation
00333       * @param key_len the desired key output size
00334       * @param in the other parties key
00335       * @param in_len the length of in in bytes
00336       * @param params extra derivation params
00337       * @param params_len the length of params in bytes
00338       */
00339       SymmetricKey derive_key(size_t key_len,
00340                               const std::vector<byte>& in,
00341                               const byte params[],
00342                               size_t params_len) const
00343          {
00344          return derive_key(key_len, &in[0], in.size(),
00345                            params, params_len);
00346          }
00347 
00348       /*
00349       * Perform Key Agreement Operation
00350       * @param key_len the desired key output size
00351       * @param in the other parties key
00352       * @param in_len the length of in in bytes
00353       * @param params extra derivation params
00354       */
00355       SymmetricKey derive_key(size_t key_len,
00356                               const byte in[], size_t in_len,
00357                               const std::string& params = "") const
00358          {
00359          return derive_key(key_len, in, in_len,
00360                            reinterpret_cast<const byte*>(params.data()),
00361                            params.length());
00362          }
00363 
00364       /*
00365       * Perform Key Agreement Operation
00366       * @param key_len the desired key output size
00367       * @param in the other parties key
00368       * @param params extra derivation params
00369       */
00370       SymmetricKey derive_key(size_t key_len,
00371                               const std::vector<byte>& in,
00372                               const std::string& params = "") const
00373          {
00374          return derive_key(key_len, &in[0], in.size(),
00375                            reinterpret_cast<const byte*>(params.data()),
00376                            params.length());
00377          }
00378 
00379       /**
00380       * Construct a PK Key Agreement.
00381       * @param key the key to use
00382       * @param kdf name of the KDF to use (or 'Raw' for no KDF)
00383       */
00384       PK_Key_Agreement(const Private_Key& key, const std::string& kdf);
00385    private:
00386       std::unique_ptr<PK_Ops::Key_Agreement> m_op;
00387       std::unique_ptr<KDF> m_kdf;
00388    };
00389 
00390 /**
00391 * Encryption with an MR algorithm and an EME.
00392 */
00393 class BOTAN_DLL PK_Encryptor_EME : public PK_Encryptor
00394    {
00395    public:
00396       size_t maximum_input_size() const;
00397 
00398       /**
00399       * Construct an instance.
00400       * @param key the key to use inside the decryptor
00401       * @param eme the EME to use
00402       */
00403       PK_Encryptor_EME(const Public_Key& key,
00404                        const std::string& eme);
00405    private:
00406       std::vector<byte> enc(const byte[], size_t,
00407                              RandomNumberGenerator& rng) const;
00408 
00409       std::unique_ptr<PK_Ops::Encryption> m_op;
00410       std::unique_ptr<EME> m_eme;
00411    };
00412 
00413 /**
00414 * Decryption with an MR algorithm and an EME.
00415 */
00416 class BOTAN_DLL PK_Decryptor_EME : public PK_Decryptor
00417    {
00418    public:
00419      /**
00420       * Construct an instance.
00421       * @param key the key to use inside the encryptor
00422       * @param eme the EME to use
00423       */
00424       PK_Decryptor_EME(const Private_Key& key,
00425                        const std::string& eme);
00426    private:
00427       secure_vector<byte> dec(const byte[], size_t) const;
00428 
00429       std::unique_ptr<PK_Ops::Decryption> m_op;
00430       std::unique_ptr<EME> m_eme;
00431    };
00432 
00433 }
00434 
00435 #endif