Botan
1.11.15
|
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