Arduino/libraries/AES-master/AES.h

   1 #ifndef __AES_H__
   2 #define __AES_H__
   3
   4 #include "AES_config.h"
   5 /*
   6  ---------------------------------------------------------------------------
   7  Copyright (c) 1998-2008, Brian Gladman, Worcester, UK. All rights reserved.
   8
   9  LICENSE TERMS
  10
  11  The redistribution and use of this software (with or without changes)
  12  is allowed without the payment of fees or royalties provided that:
  13
  14   1. source code distributions include the above copyright notice, this
  15      list of conditions and the following disclaimer;
  16
  17   2. binary distributions include the above copyright notice, this list
  18      of conditions and the following disclaimer in their documentation;
  19
  20   3. the name of the copyright holder is not used to endorse products
  21      built using this software without specific written permission.
  22
  23  DISCLAIMER
  24
  25  This software is provided 'as is' with no explicit or implied warranties
  26  in respect of its properties, including, but not limited to, correctness
  27  and/or fitness for purpose.
  28  ---------------------------------------------------------------------------
  29  Issue 09/09/2006
  30
  31  This is an AES implementation that uses only 8-bit byte operations on the
  32  cipher state.
  33  */
  34
  35  /* code was modified by george spanos <spaniakos@gmail.com>
  36  * 16/12/14
  37  */
  38
  39 class AES
  40 {
  41  public:
  42
  43 /*  The following calls are for a precomputed key schedule
  44
  45     NOTE: If the length_type used for the key length is an
  46     unsigned 8-bit character, a key length of 256 bits must
  47     be entered as a length in bytes (valid inputs are hence
  48     128, 192, 16, 24 and 32).
  49 */
  50         /** \fn AES()
  51         * \brief AES constructor
  52         *
  53         * This function initialized an instance of AES.
  54         */
  55         AES();
  56
  57         /** Set the cipher key for the pre-keyed version.
  58          *  @param key[] pointer to the key string.
  59          *  @param keylen Integer that indicates the length of the key.
  60          *  @note NOTE: If the length_type used for the key length is an unsigned 8-bit character,
  61          *  a key length of 256 bits must be entered as a length in bytes
  62          *  (valid inputs are hence 128, 192, 16, 24 and 32).
  63          *
  64          */
  65         byte set_key (byte key[], int keylen) ;
  66
  67         /** clean up subkeys after use.
  68          *
  69          */
  70         void clean () ;  // delete key schedule after use
  71
  72         /** copying and xoring utilities.
  73          *  @param *AESt byte pointer of the AEStination array.
  74          *  @param *src byte pointer of the source array.
  75          *  @param n byte, indicating the sizeof the bytes to be copied.
  76          *  @note this is an alternative for memcpy(void *s1,const void *s2, site_t n),
  77          *  i have not updated the function in the implementation yet, but it is considered a future plan.
  78          *
  79          */
  80         void copy_n_bytes (byte * AESt, byte * src, byte n) ;
  81
  82         /** Encrypt a single block of 16 bytes .
  83          *  @param plain[N_BLOCK] Array of the plaintext.
  84          *  @param cipher[N_BLOCK] Array of the ciphertext.
  85          *  @note The N_BLOCK is defined in AES_config.h as,
  86          *  @code #define N_ROW                   4
  87          *                #define N_COL                   4
  88          *                #define N_BLOCK   (N_ROW * N_COL)
  89          *      @endcode
  90          *  Changed to that will change the Block_size.
  91          *  @Return 0 if SUCCESS or -1 if FAILURE
  92          *
  93          */
  94         byte encrypt (byte plain [N_BLOCK], byte cipher [N_BLOCK]) ;
  95
  96         /** CBC encrypt a number of blocks (input and return an IV).
  97          *
  98          *  @param *plain Pointer, points to the plaintex.
  99          *  @param *cipher Pointer, points to the ciphertext that will be created.
 100          *  @param n_block integer, indicated the number of blocks to be ciphered.
 101          *  @param iv[N_BLOCK] byte Array that holds the IV (initialization vector).
 102          *  @Return 0 if SUCCESS or -1 if FAILURE
 103          *
 104          */
 105         byte cbc_encrypt (byte * plain, byte * cipher, int n_block, byte iv [N_BLOCK]) ;
 106
 107         /** CBC encrypt a number of blocks (input and return an IV).
 108          *
 109          *  @param *plain Pointer, points to the plaintex.
 110          *  @param *cipher Pointer, points to the ciphertext that will be created.
 111          *  @param n_block integer, indicated the number of blocks to be ciphered.
 112          *  @Return 0 if SUCCESS or -1 if FAILURE
 113          *
 114          */
 115         byte cbc_encrypt (byte * plain, byte * cipher, int n_block) ;
 116
 117
 118         /**  Decrypt a single block of 16 bytes
 119          *  @param cipher[N_BLOCK] Array of the ciphertext.
 120          *  @param plain[N_BLOCK] Array of the plaintext.
 121          *  @note The N_BLOCK is defined in AES_config.h as,
 122          *  @code #define N_ROW                   4
 123          *                #define N_COL                   4
 124          *                #define N_BLOCK   (N_ROW * N_COL)
 125          *      @endcode
 126          *  Changed to that will change the Block_size.
 127          *  @Return 0 if SUCCESS or -1 if FAILURE
 128          *
 129          */
 130         byte decrypt (byte cipher [N_BLOCK], byte plain [N_BLOCK]) ;
 131
 132         /** CBC decrypt a number of blocks (input and return an IV)
 133          *
 134          *  @param *cipher Pointer, points to the ciphertext that will be created.
 135          *  @param *plain Pointer, points to the plaintex.
 136          *  @param n_block integer, indicated the number of blocks to be ciphered.
 137          *  @param iv[N_BLOCK] byte Array that holds the IV (initialization vector).
 138          *  @Return 0 if SUCCESS or -1 if FAILURE
 139          *
 140          */
 141         byte cbc_decrypt (byte * cipher, byte * plain, int n_block, byte iv [N_BLOCK]) ;
 142
 143         /** CBC decrypt a number of blocks (input and return an IV)
 144          *
 145          *  @param *cipher Pointer, points to the ciphertext that will be created.
 146          *  @param *plain Pointer, points to the plaintex.
 147          *  @param n_block integer, indicated the number of blocks to be ciphered.
 148          *  @Return 0 if SUCCESS or -1 if FAILURE
 149          *
 150          */
 151         byte cbc_decrypt (byte * cipher, byte * plain, int n_block) ;
 152
 153         /** Sets IV (initialization vector) and IVC (IV counter).
 154          *  This function changes the ivc and iv variables needed for AES.
 155          *
 156          *  @param IVCl int or hex value of iv , ex. 0x0000000000000001
 157          *  @note example:
 158          *  @code unsigned long long int my_iv = 01234567; @endcode
 159         */
 160         void set_IV(unsigned long long int IVCl);
 161
 162         /** increase the iv (initialization vector) and IVC (IV counter) by 1
 163          *
 164          *  This function increased the VI by one step in order to have a different IV each time
 165          *
 166         */
 167         void iv_inc();
 168
 169         /** Getter method for size
 170          *
 171          * This function return the size
 172          * @return an integer, that is the size of the of the padded plaintext,
 173          * thus, the size of the ciphertext.
 174          */
 175         int get_size();
 176
 177         /** Setter method for size
 178          *
 179          * This function sets the size of the plaintext+pad
 180          *
 181          */
 182         void set_size(int sizel);
 183
 184         /** Getter method for IV
 185         *
 186         * This function return the IV
 187         * @param out byte pointer that gets the IV.
 188         * @return none, the IV is writed to the out pointer.
 189         */
 190         void get_IV(byte *out);
 191
 192         /** Calculates the size of the plaintext and the padding.
 193          *
 194          * Calculates the size of theplaintext with the padding
 195          * and the size of the padding needed. Moreover it stores them in their class variables.
 196          *
 197          * @param p_size the size of the byte array ex sizeof(plaintext)
 198         */
 199         void calc_size_n_pad(int p_size);
 200
 201         /** Pads the plaintext
 202          *
 203          * This function pads the plaintext and returns an char array with the
 204          * plaintext and the padding in order for the plaintext to be compatible with
 205          * 16bit size blocks required by AES
 206          *
 207          * @param in the string of the plaintext in a byte array
 208          * @param out The string of the out array.
 209          * @return no return, The padded plaintext is stored in the out pointer.
 210          */
 211         void padPlaintext(void* in,byte* out);
 212
 213         /** Check the if the padding is correct.
 214          *
 215          * This functions checks the padding of the plaintext.
 216          *
 217          * @param in the string of the plaintext in a byte array
 218          * @param size the size of the string
 219          * @return true if correct / false if not
 220          */
 221         bool CheckPad(byte* in,int size);
 222
 223         /** Prints the array given.
 224          *
 225          * This function prints the given array and pad,
 226          * It is mainlly used for debugging purpuses or to output the string.
 227          *
 228          * @param output[] the string of the text in a byte array
 229          * @param p_pad optional, used to print with out the padding characters
 230         */
 231         void printArray(byte output[],bool p_pad = true);
 232
 233         /** Prints the array given.
 234          *
 235          * This function prints the given array in Hexadecimal.
 236          *
 237          * @param output[] the string of the text in a byte array
 238          * @param sizel the size of the array.
 239         */
 240         void printArray(byte output[],int sizel);
 241
 242         /** User friendly implementation of AES-CBC encryption.
 243          *
 244          * @param *plain pointer to the plaintext
 245          * @param size_p size of the plaintext
 246          * @param *cipher pointer to the ciphertext
 247          * @param *key pointer to the key that will be used.
 248          * @param bits bits of the encryption/decrpytion
 249          * @param ivl[N_BLOCK] the initialization vector IV that will be used for encryption.
 250          * @note The key will be stored in class variable.
 251          */
 252         void do_aes_encrypt(byte *plain,int size_p,byte *cipher,byte *key, int bits, byte ivl [N_BLOCK]);
 253
 254         /** User friendly implementation of AES-CBC encryption.
 255          *
 256          * @param *plain pointer to the plaintext
 257          * @param size_p size of the plaintext
 258          * @param *cipher pointer to the ciphertext
 259          * @param *key pointer to the key that will be used.
 260          * @param bits bits of the encryption/decrpytion
 261          * @note The key will be stored in class variable.
 262          */
 263         void do_aes_encrypt(byte *plain,int size_p,byte *cipher,byte *key, int bits);
 264
 265         /** User friendly implementation of AES-CBC decryption.
 266          *
 267          * @param *cipher pointer to the ciphertext
 268          * @param size_c size of the ciphertext
 269          * @param *plain pointer to the plaintext
 270          * @param *key pointer to the key that will be used.
 271          * @param bits bits of the encryption/decrpytion
 272          * @param ivl[N_BLOCK] the initialization vector IV that will be used for decryption.
 273          * @note The key will be stored in class variable.
 274          */
 275         void do_aes_decrypt(byte *cipher,int size_c,byte *plain,byte *key, int bits, byte ivl [N_BLOCK]);
 276
 277         /** User friendly implementation of AES-CBC decryption.
 278          *
 279          * @param *cipher pointer to the ciphertext
 280          * @param size_c size of the ciphertext
 281          * @param *plain pointer to the plaintext
 282          * @param *key pointer to the key that will be used.
 283          * @param bits bits of the encryption/decrpytion
 284          * @note The key will be stored in class variable.
 285          */
 286         void do_aes_decrypt(byte *cipher,int size_c,byte *plain,byte *key, int bits);
 287
 288         #if defined(AES_LINUX)
 289                 /**
 290                  * used in linux in order to retrieve the time in milliseconds.
 291                  *
 292                  * @return returns the milliseconds in a double format.
 293                  */
 294                 double millis();
 295         #endif
 296  private:
 297   int round ;/**< holds the number of rounds to be used. */
 298   byte key_sched [KEY_SCHEDULE_BYTES] ;/**< holds the pre-computed key for the encryption/decrpytion. */
 299   unsigned long long int IVC;/**< holds the initialization vector counter in numerical format. */
 300   byte iv[16];/**< holds the initialization vector that will be used in the cipher. */
 301   int pad;/**< holds the size of the padding. */
 302   int size;/**< hold the size of the plaintext to be ciphered */
 303   #if defined(AES_LINUX)
 304         timeval tv;/**< holds the time value on linux */
 305         byte arr_pad[15];/**< holds the hexadecimal padding values on linux */
 306   #else
 307         byte arr_pad[15] = { 0x01,0x02,0x03,0x04,0x05,0x06,0x07,0x08,0x09,0x0a,0x0b,0x0c,0x0d,0x0e,0x0f };/**< holds the hexadecimal padding values */
 308   #endif
 309 } ;
 310
 311
 312 #endif
 313
 314 /**
 315  * @example aes.ino
 316  * <b>For Arduino</b><br>
 317  * <b>Updated: spaniakos 2015 </b><br>
 318  *
 319  * This is an example of how to use AES in CBC mode easily.
 320  * The text and keys can be either in HEX or String format.<br />
 321  */
 322
 323  /**
 324  * @example aes.cpp
 325  * <b>For Rasberry pi</b><br>
 326  * <b>Updated: spaniakos 2015 </b><br>
 327  *
 328  * This is an example of how to use AES in CBC mode easily.
 329  * The text and keys can be either in HEX or String format.<br />
 330  */
 331
 332  /**
 333  * @example test_vectors.ino
 334  * <b>For Arduino</b><br>
 335  * <b>Updated: spaniakos 2015 </b><br>
 336  *
 337  * This is an example of monte carlo test vectors, in order to justify the effectiveness of the algorithm.<br />
 338  * plus is a classical approach to the AES encryption library with out the easy to use add-on modifications.
 339  */
 340
 341  /**
 342  * @example test_vectors.cpp
 343  * <b>For Rasberry pi</b><br>
 344  * <b>Updated: spaniakos 2015 </b><br>
 345  *
 346  * This is an example of monte carlo test vectors, in order to justify the effectiveness of the algorithm.<br />
 347  * plus is a classical approach to the AES encryption library with out the easy to use add-on modifications.
 348  */
 349
 350 /**
 351  * @mainpage AES library for Arduino and Raspberry pi.
 352  *
 353  * @section Goals design Goals
 354  *
 355  * This library is AESigned to be...
 356  * @li Fast and efficient.
 357  * @li Able to effectively encrypt and decrypt any size of string.
 358  * @li Able to encrypt and decrypt using AES
 359  * @li Able to encrypt and decrypt using AES-CBC
 360  * @li Easy for the user to use in his programs.
 361  *
 362  * @section Acknowledgements Acknowledgements
 363  * This is an AES library for the Arduino, based on tzikis's AES library, which you can find <a href= "https://github.com/tzikis/arduino">here:</a>.<br />
 364  * Tzikis library was based on scottmac`s library, which you can find <a href="https://github.com/scottmac/arduino">here:</a><br />
 365  *
 366  * @section Installation Installation
 367  * <h3>Arduino</h3>
 368  * Create a folder named _AES_ in the _libraries_ folder inside your Arduino sketch folder. If the
 369  * libraries folder doesn't exist, create it. Then copy everything inside. (re)launch the Arduino IDE.<br />
 370  * You're done. Time for a mojito
 371  *
 372  * <h3>Raspberry  pi</h3>
 373  * <b>install</b><br /><br />
 374  *
 375  * sudo make install<br />
 376  * cd examples_Rpi<br />
 377  * make<br /><br />
 378  *
 379  * <b>What to do after changes to the library</b><br /><br />
 380  * sudo make clean<br />
 381  * sudo make install<br />
 382  * cd examples_Rpi<br />
 383  * make clean<br />
 384  * make<br /><br />
 385  * <b>What to do after changes to a sketch</b><br /><br />
 386  * cd examples_Rpi<br />
 387  * make <sketch><br /><br />
 388  * or <br />
 389  * make clean<br />
 390  * make<br /><br /><br />
 391  * <b>How to start a sketch</b><br /><br />
 392  * cd examples_Rpi<br />
 393  * sudo ./<sketch><br /><br />
 394  *
 395  * @section News News
 396  *
 397  * If issues are discovered with the documentation, please report them <a href="https://github.com/spaniakos/spaniakos.github.io/issues"> here</a>
 398  * @section Useful Useful References
 399  *
 400  * Please refer to:
 401  *
 402  * @li <a href="http://spaniakos.github.io/AES/classAES.html"><b>AES</b> Class Documentation</a>
 403  * @li <a href="https://github.com/spaniakos/AES/archive/master.zip"><b>Download</b></a>
 404  * @li <a href="https://github.com/spaniakos/AES/"><b>Source Code</b></a>
 405  * @li <a href="http://spaniakos.github.io/">All spaniakos Documentation Main Page</a>
 406  *
 407  * @section Board_Support Board Support
 408  *
 409  * Most standard Arduino based boards are supported:
 410  * - Arduino
 411  * - Intel Galileo support
 412  * - Raspberry Pi Support
 413  *
 414  * - The library has not been tested to other boards, but it should suppport ATMega 328 based boards,Mega Boards,Arduino Due,ATTiny board
 415  */