Botan  1.11.15
src/lib/base/transform.h
Go to the documentation of this file.
00001 /*
00002 * Transforms of data
00003 * (C) 2013 Jack Lloyd
00004 *
00005 * Botan is released under the Simplified BSD License (see license.txt)
00006 */
00007 
00008 #ifndef BOTAN_TRANSFORM_H__
00009 #define BOTAN_TRANSFORM_H__
00010 
00011 #include <botan/secmem.h>
00012 #include <botan/key_spec.h>
00013 #include <botan/exceptn.h>
00014 #include <botan/symkey.h>
00015 #include <botan/scan_name.h>
00016 #include <string>
00017 #include <vector>
00018 
00019 namespace Botan {
00020 
00021 /**
00022 * Interface for general transformations on data
00023 */
00024 class BOTAN_DLL Transform
00025    {
00026    public:
00027       typedef SCAN_Name Spec;
00028 
00029       /**
00030       * Begin processing a message.
00031       * @param nonce the per message nonce
00032       */
00033       template<typename Alloc>
00034       secure_vector<byte> start(const std::vector<byte, Alloc>& nonce)
00035          {
00036          return start(&nonce[0], nonce.size());
00037          }
00038 
00039       /**
00040       * Begin processing a message.
00041       * @param nonce the per message nonce
00042       */
00043       template<typename Alloc>
00044       BOTAN_DEPRECATED("Use Transform::start")
00045       secure_vector<byte> start_vec(const std::vector<byte, Alloc>& nonce)
00046          {
00047          return start(&nonce[0], nonce.size());
00048          }
00049 
00050       /**
00051       * Begin processing a message.
00052       * @param nonce the per message nonce
00053       * @param nonce_len length of nonce
00054       */
00055       secure_vector<byte> start(const byte nonce[], size_t nonce_len)
00056          {
00057          return start_raw(nonce, nonce_len);
00058          }
00059 
00060       /**
00061       * Begin processing a message.
00062       */
00063       secure_vector<byte> start()
00064          {
00065          return start_raw(nullptr, 0);
00066          }
00067 
00068       virtual secure_vector<byte> start_raw(const byte nonce[], size_t nonce_len) = 0;
00069 
00070       /**
00071       * Process some data. Input must be in size update_granularity() byte blocks.
00072       * @param blocks in/out paramter which will possibly be resized
00073       * @param offset an offset into blocks to begin processing
00074       */
00075       virtual void update(secure_vector<byte>& blocks, size_t offset = 0) = 0;
00076 
00077       /**
00078       * Complete processing of a message.
00079       *
00080       * @param final_block in/out parameter which must be at least
00081       *        minimum_final_size() bytes, and will be set to any final output
00082       * @param offset an offset into final_block to begin processing
00083       */
00084       virtual void finish(secure_vector<byte>& final_block, size_t offset = 0) = 0;
00085 
00086       /**
00087       * Returns the size of the output if this transform is used to process a
00088       * message with input_length bytes. Will throw if unable to give a precise
00089       * answer.
00090       */
00091       virtual size_t output_length(size_t input_length) const = 0;
00092 
00093       /**
00094       * @return size of required blocks to update
00095       */
00096       virtual size_t update_granularity() const = 0;
00097 
00098       /**
00099       * @return required minimium size to finalize() - may be any
00100       *         length larger than this.
00101       */
00102       virtual size_t minimum_final_size() const = 0;
00103 
00104       /**
00105       * Return the default size for a nonce
00106       */
00107       virtual size_t default_nonce_length() const = 0;
00108 
00109       /**
00110       * Return true iff nonce_len is a valid length for the nonce
00111       */
00112       virtual bool valid_nonce_length(size_t nonce_len) const = 0;
00113 
00114       /**
00115       * Return some short name describing the provider of this tranformation.
00116       * Useful in cases where multiple implementations are available (eg,
00117       * different implementations of AES). Default "core" is used for the
00118       * 'standard' implementation included in the library.
00119       */
00120       virtual std::string provider() const { return "core"; }
00121 
00122       virtual std::string name() const = 0;
00123 
00124       virtual void clear() = 0;
00125 
00126       virtual ~Transform() {}
00127    };
00128 
00129 class BOTAN_DLL Keyed_Transform : public Transform
00130    {
00131    public:
00132       /**
00133       * @return object describing limits on key size
00134       */
00135       virtual Key_Length_Specification key_spec() const = 0;
00136 
00137       /**
00138       * Check whether a given key length is valid for this algorithm.
00139       * @param length the key length to be checked.
00140       * @return true if the key length is valid.
00141       */
00142       bool valid_keylength(size_t length) const
00143          {
00144          return key_spec().valid_keylength(length);
00145          }
00146 
00147       template<typename Alloc>
00148       void set_key(const std::vector<byte, Alloc>& key)
00149          {
00150          set_key(&key[0], key.size());
00151          }
00152 
00153       void set_key(const SymmetricKey& key)
00154          {
00155          set_key(key.begin(), key.length());
00156          }
00157 
00158       /**
00159       * Set the symmetric key of this transform
00160       * @param key contains the key material
00161       * @param length in bytes of key param
00162       */
00163       void set_key(const byte key[], size_t length)
00164          {
00165          if(!valid_keylength(length))
00166             throw Invalid_Key_Length(name(), length);
00167          key_schedule(key, length);
00168          }
00169 
00170    private:
00171       virtual void key_schedule(const byte key[], size_t length) = 0;
00172    };
00173 
00174 typedef Transform Transformation;
00175 
00176 BOTAN_DLL Transform* get_transform(const std::string& specstr,
00177                                    const std::string& provider = "",
00178                                    const std::string& dirstr = "");
00179 
00180 }
00181 
00182 #endif