git.sur5r.net Git - freertos/blob - FreeRTOS/Demo/CORTEX_M4_SimpleLink_CC3220SF_CCS/ti/drivers/crypto/CryptoCC32XX.h

   1 /*
   2  * Copyright (c) 2015-2016, Texas Instruments Incorporated
   3  * All rights reserved.
   4  *
   5  * Redistribution and use in source and binary forms, with or without
   6  * modification, are permitted provided that the following conditions
   7  * are met:
   8  *
   9  * *  Redistributions of source code must retain the above copyright
  10  *    notice, this list of conditions and the following disclaimer.
  11  *
  12  * *  Redistributions in binary form must reproduce the above copyright
  13  *    notice, this list of conditions and the following disclaimer in the
  14  *    documentation and/or other materials provided with the distribution.
  15  *
  16  * *  Neither the name of Texas Instruments Incorporated nor the names of
  17  *    its contributors may be used to endorse or promote products derived
  18  *    from this software without specific prior written permission.
  19  *
  20  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  21  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
  22  * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  23  * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
  24  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  25  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  26  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
  27  * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
  28  * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
  29  * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
  30  * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  31  */
  32 /** ============================================================================
  33  *  @file       CryptoCC32XX.h
  34  *
  35  *  @brief      Crypto driver implementation for a CC32XX Crypto controller.
  36  *
  37  *  The Crypto header file should be included in an application as follows:
  38  *  @code
  39  *  #include <ti/drivers/crypto/CryptoCC32XX.h>
  40  *  @endcode
  41  *
  42  *  # Operation #
  43  *
  44  *  The CryptoCC32XX driver is used several security methods (AES, DES and HMAC Hash functions).
  45  *  This driver provides API for encrypt/decrypt (AES and DES)
  46  *  and sign/verify (HMAC hash)
  47  *
  48  *  The application initializes the CryptoCC32XX driver by calling CryptoCC32XX_init()
  49  *  and is then ready to open a Crypto by calling CryptoCC32XX_open().
  50  *
  51  *  The APIs in this driver serve as an interface to a typical TI-RTOS
  52  *  application. The specific peripheral implementations are responsible to
  53  *  create all the OSAL specific primitives to allow for thread-safe
  54  *  operation.
  55  *
  56  *  ## Opening the driver #
  57  *
  58  *  @code
  59  *  CryptoCC32XX_Handle      handle;
  60  *
  61  *  handle = CryptoCC32XX_open(CryptoCC32XX_configIndexValue,   CryptoCC32XX_AES |
  62                                                                 CryptoCC32XX_DES |
  63                                                                 CryptoCC32XX_HMAC);
  64  *  if (!handle) {
  65  *      System_printf("CryptoCC32XX did not open");
  66  *  }
  67  *  @endcode
  68  *
  69  *
  70  *  ## AES data encryption #
  71  *
  72  *  @code
  73  *  CryptoCC32XX_EncryptMethod  method = desiredMethod;
  74  *  CryptoCC32XX_Params         params;
  75  *  unsigned char               plainData[16] = "whatsoever123456";
  76  *  unsigned int                plainDataLen = sizeof(plainData);
  77  *  unsigned char               cipherData[16];
  78  *  unsigned int                cipherDataLen;
  79  *
  80  *  params.aes.keySize = desiredKeySize;
  81  *  params.aes.pKey = (CryptoCC32XX_KeyPtr)desiredKey; // desiredKey length should be as the desiredKeySize
  82  *  params.aes.pIV = (void *)pointerToInitVector;
  83  *  ret = CryptoCC32XX_encrypt(handle, method , plainData, plainDataLen, cipherData , &cipherDataLen , &params);
  84  *
  85  *  @endcode
  86  *
  87  *  ## Generate HMAC Hash signature #
  88  *
  89  *  @code
  90  *  CryptoCC32XX_HmacMethod hmacMethod = desiredHmacMethod;
  91  *  CryptoCC32XX_Params     params;
  92  *  unsigned char           dataBuff[] = "whatsoever";
  93  *  unsigned int            dataLength = sizeof(dataBuff);
  94  *  unsigned char           signatureBuff[32];
  95  *
  96  *  params.pKey = pointerToHMACkey;
  97  *  params.moreData = 0;
  98  *  ret = CryptoCC32XX_sign(handle, hmacMethod , &dataBuff, dataLength, &signatureBuff, &params);
  99  *
 100  *  @endcode
 101  *
 102  *  # Implementation #
 103  *
 104  *  The CryptoCC32XX driver interface module is joined (at link time) to a
 105  *  NULL-terminated array of CryptoCC32XX_Config data structures named *CryptoCC32XX_config*.
 106  *  *CryptoCC32XX_config* is implemented in the application with each entry being an
 107  *  instance of a CryptoCC32XX peripheral. Each entry in *CryptoCC32XX_config* contains a:
 108  *  - (void *) data object that is pointed to CryptoCC32XX_Object
 109  *
 110  *
 111  *  ============================================================================
 112  */
 113
 114 #ifndef ti_drivers_crypto_CryptoCC32XX__include
 115 #define ti_drivers_crypto_CryptoCC32XX__include
 116
 117 #ifdef __cplusplus
 118 extern "C" {
 119 #endif
 120
 121
 122 #include <stdint.h>
 123 #include <stddef.h>
 124 #include <stdbool.h>
 125 #include <ti/drivers/dpl/HwiP.h>
 126 #include <ti/drivers/dpl/SemaphoreP.h>
 127
 128
 129 #define CryptoCC32XX_CMD_RESERVED             32
 130
 131 #define CryptoCC32XX_STATUS_RESERVED          -32
 132
 133 /*!
 134  * @brief   Successful status code returned by Crypto Common functions.
 135  *
 136  */
 137 #define CryptoCC32XX_STATUS_SUCCESS           0
 138
 139 /*!
 140  * @brief   Generic error status code returned by Crypto Common functions.
 141  *
 142  */
 143 #define CryptoCC32XX_STATUS_ERROR             -1
 144
 145 /*!
 146  * @brief   An error status code returned by Crypto Common functions for undefined
 147  * command codes.
 148  *
 149  */
 150 #define CryptoCC32XX_STATUS_UNDEFINEDCMD      -2
 151
 152 /*!
 153  * @brief   An error status code returned by CryptoCC32XX_verify for define error in
 154  * verifying a given Hash value.
 155  *
 156  */
 157 #define CryptoCC32XX_STATUS_ERROR_VERIFY      -3
 158
 159 /*!
 160  * @brief   An error status code returned by Crypto Common functions for define
 161  * cryptographic type not supported.
 162  *
 163  */
 164 #define CryptoCC32XX_STATUS_ERROR_NOT_SUPPORTED -4
 165
 166
 167 #define CryptoCC32XX_MAX_TYPES                3
 168
 169
 170 /*!
 171  *  @brief  Cryptography types configuration
 172  *
 173  *  This enum defines bitwise Cryptography types.
 174  */
 175 typedef enum
 176 {
 177     CryptoCC32XX_AES = 0x01,     /*!< Advanced Encryption Standard */
 178     CryptoCC32XX_DES = 0x02,     /*!< Data Encryption Standard */
 179     CryptoCC32XX_HMAC = 0x04,    /*!< Cryptographic hash function */
 180 }CryptoCC32XX_Type;
 181
 182 /*!
 183  *  @brief  AES and DES Cryptography methods configuration
 184  *  Keep the Crypto method in the lower 8 bit and
 185  *  Crypto type in the upper 8 bits
 186  *
 187  *  This enum defines the AES and DES Cryptography modes.
 188  */
 189 typedef enum
 190 {
 191     CryptoCC32XX_AES_ECB = (CryptoCC32XX_AES << 8) | 1, /*!< AES Electronic CodeBook */
 192     CryptoCC32XX_AES_CBC,                         /*!< AES Cipher Block Chaining */
 193     CryptoCC32XX_AES_CTR,                         /*!< AES Counter */
 194     CryptoCC32XX_AES_ICM,                         /*!< AES Integer Counter Mode */
 195     CryptoCC32XX_AES_CFB,                         /*!< AES Cipher FeedBack */
 196     CryptoCC32XX_AES_GCM,                         /*!< AES Galois/Counter Mode */
 197     CryptoCC32XX_AES_CCM,                         /*!< AES Counter with CBC-MAC Mode */
 198
 199     CryptoCC32XX_DES_ECB = (CryptoCC32XX_DES << 8) | 1, /*!< DES Electronic CodeBook */
 200     CryptoCC32XX_DES_CBC,                         /*!< DES Cipher Block Chaining */
 201     CryptoCC32XX_DES_CFB,                         /*!< DES Cipher FeedBack */
 202
 203 }CryptoCC32XX_EncryptMethod;
 204
 205 /*!
 206  *  @brief  HMAC Cryptography methods configuration
 207  *  Keep the Crypto method in the lower 8 bit and
 208  *  Crypto type in the upper 8 bits
 209  *
 210  *  This enum defines the HMAC HASH algorithms modes.
 211  */
 212 typedef enum
 213 {
 214     CryptoCC32XX_HMAC_MD5 = (CryptoCC32XX_HMAC << 8) | 1,   /*!< MD5 used keyed-hash message authentication code */
 215     CryptoCC32XX_HMAC_SHA1,                           /*!< SHA1 used keyed-hash message authentication code */
 216     CryptoCC32XX_HMAC_SHA224,                         /*!< SHA224 used keyed-hash message authentication code */
 217     CryptoCC32XX_HMAC_SHA256                          /*!< SHA256 used keyed-hash message authentication code */
 218
 219 }CryptoCC32XX_HmacMethod;
 220
 221 /*!
 222  *  @brief  AES Cryptography key size type configuration
 223  *
 224  *  This enum defines the AES key size types
 225  */
 226 typedef enum
 227 {
 228     CryptoCC32XX_AES_KEY_SIZE_128BIT,
 229     CryptoCC32XX_AES_KEY_SIZE_192BIT,
 230     CryptoCC32XX_AES_KEY_SIZE_256BIT
 231
 232 }CryptoCC32XX_AesKeySize;
 233
 234 /*!
 235  *  @brief  DES Cryptography key size type configuration
 236  *
 237  *  This enum defines the DES key size types
 238  */
 239 typedef enum
 240 {
 241     CryptoCC32XX_DES_KEY_SIZE_SINGLE,
 242     CryptoCC32XX_DES_KEY_SIZE_TRIPLE
 243
 244 }CryptoCC32XX_DesKeySize;
 245
 246
 247 /*!
 248  *  @brief  AES Additional Authentication Data input parameters
 249  *
 250  *  This structure defines the AES Additional Authentication Data input parameters used for
 251  *  CryptoCC32XX_AES_GCM and CryptoCC32XX_AES_CCM
 252  */
 253 typedef struct
 254 {
 255     uint8_t                 *pKey2;     /*!< pointer to AES second key (CryptoCC32XX_AES_CCM) */
 256     CryptoCC32XX_AesKeySize       key2Size;   /*!< AES second Key size type (CryptoCC32XX_AES_CCM) */
 257     size_t                  len;        /*!< length of the additional authentication data in bytes */
 258 }CryptoCC32XX_AesAadInputParams;
 259
 260 /*!
 261  *  @brief  AES Additional Authentication Data Parameters
 262  *
 263  *  This union defines the AES additional authentication parameters used for
 264  *  CryptoCC32XX_AES_GCM and CryptoCC32XX_AES_CCM
 265  */
 266 typedef union
 267 {
 268     CryptoCC32XX_AesAadInputParams    input;   /*!<an input - additional authentication data */
 269     uint8_t                     tag[16]; /*!<an output - pointer to a 4-word array where the hash tag is written */
 270 }CryptoCC32XX_AesAadParams;
 271
 272 /*!
 273  *  @brief  AES Parameters
 274  *
 275  *  This structure defines the AES parameters used in CryptoCC32XX_encrypt and CryptoCC32XX_decrypt functions.
 276  */
 277 typedef struct
 278 {
 279     const uint8_t           *pKey;       /*!< pointer to AES key */
 280     CryptoCC32XX_AesKeySize       keySize;    /*!< AES Key size type */
 281     void                    *pIV;       /*!< Pointer to AES Initialization Vector */
 282     CryptoCC32XX_AesAadParams     aadParams;
 283 }CryptoCC32XX_AesParams;
 284
 285 /*!
 286  *  @brief  DES Parameters
 287  *
 288  *  This structure defines the DES parameters used in CryptoCC32XX_encrypt and CryptoCC32XX_decrypt functions.
 289  */
 290 typedef struct
 291 {
 292     const uint8_t           *pKey;       /*!< pointer to DES key */
 293     CryptoCC32XX_DesKeySize       keySize;    /*!< DES Key size type */
 294     void                    *pIV;       /*!< Pointer to DES Initialization Vector */
 295 }CryptoCC32XX_DesParams;
 296
 297 /*!
 298  *  @brief  Cryptography Parameters
 299  *
 300  *  This union defines the AES and DES Cryptographic types
 301  */
 302 typedef union
 303 {
 304     CryptoCC32XX_AesParams        aes;
 305     CryptoCC32XX_DesParams        des;
 306 }CryptoCC32XX_EncryptParams;
 307
 308 /*!
 309  *  @brief  HMAC Parameters
 310  *
 311  *  This structure defines the Hmac parameters used in CryptoCC32XX_sign and CryptoCC32XX_verify functions.
 312  */
 313
 314 typedef struct
 315 {
 316     uint8_t                 *pKey; /*!< pointer to hash key */
 317     uint8_t                 moreData;  /*!< True value will NOT reset the HMAC HW machine */
 318     void                    *pContext;
 319 }CryptoCC32XX_HmacParams;
 320
 321 /*!
 322  *  @brief      A handle that is returned from a CryptoCC32XX_open() call.
 323  */
 324 typedef struct CryptoCC32XX_Config    *CryptoCC32XX_Handle;
 325
 326
 327 /*!
 328  *  @brief  CryptoCC32XX Object
 329  *
 330  *  The application must not access any member variables of this structure!
 331  */
 332 typedef struct CryptoCC32XX_Object {
 333     /* Interrupt handles */
 334     HwiP_Handle     hwiHandle[CryptoCC32XX_MAX_TYPES];
 335     /* flag to indicate module is open */
 336     bool            isOpen;
 337     /* Semaphore handles */
 338     SemaphoreP_Handle   sem[CryptoCC32XX_MAX_TYPES];
 339 } CryptoCC32XX_Object;
 340
 341
 342 /*!
 343  *  @brief  Crypto Global configuration
 344  *
 345  *  The CryptoCC32XX_Config structure contains a set of pointers used to characterize
 346  *  the Crypto driver implementation.
 347  *
 348  *  This structure needs to be defined before calling CryptoCC32XX_init() and it must
 349  *  not be changed thereafter.
 350  *
 351  *  @sa     CryptoCC32XX_init()
 352  */
 353 typedef struct CryptoCC32XX_Config {
 354
 355     /*! Pointer to a driver specific data object */
 356     void               *object;
 357
 358 } CryptoCC32XX_Config;
 359
 360
 361 /*!
 362  *  @brief  Function to close a given Crypto peripheral specified by the Crypto
 363  *  handle.
 364  *
 365  *  @pre    CryptoCC32XX_open() had to be called first.
 366  *
 367  *  @param  handle  A CryptoCC32XX_Handle returned from CryptoCC32XX_open
 368  *
 369  *  @sa     CryptoCC32XX_open()
 370  */
 371 void CryptoCC32XX_close(CryptoCC32XX_Handle handle);
 372
 373 /*!
 374  *  @brief  Function to initializes the Crypto module
 375  *
 376  *  @pre    The CryptoCC32XX_Config structure must exist and be persistent before this
 377  *          function can be called. This function must also be called before
 378  *          any other Crypto driver APIs. This function call does not modify any
 379  *          peripheral registers.
 380  */
 381 void CryptoCC32XX_init(void);
 382
 383 /*!
 384  *  @brief  Opens a Crypto object with a given index and returns a CryptoCC32XX_Handle.
 385  *
 386  *  @pre    Crypto module has been initialized
 387  *
 388  *  @param  index         Logical peripheral number for the Crypto indexed into
 389  *                        the CryptoCC32XX_config table
 390  *
 391  *  @param  types         Define bitwise Crypto Types to support
 392  *
 393  *  @return A CryptoCC32XX_Handle on success or a NULL on an error or if it has been
 394  *          opened already.
 395  *
 396  *  @sa     CryptoCC32XX_init()
 397  *  @sa     CryptoCC32XX_close()
 398  */
 399 CryptoCC32XX_Handle CryptoCC32XX_open(uint32_t index, uint32_t types);
 400
 401 /*!
 402  *  @brief Function which encrypt given data by a given AES or DES method.
 403  *  relevant to CryptoCC32XX_AES and CryptoCC32XX_DES
 404  *
 405  *  @param  handle      A CryptoCC32XX_Handle
 406  *
 407  *  @param  method      An AES or DES encryption method to use on a given plain data.
 408  *
 409  *  @param  pInBuff     Pointer to plain data to encrypt.
 410  *
 411  *  @param  inLen       Size of plain data to encrypt.
 412  *
 413  *  @param  pOutBuff    Pointer to encrypted data (cipher text).
 414  *
 415  *  @param  outLen      Size of encrypted data.
 416  *
 417  *  @param  pParams     Specific parameters according to Crypto Type (AES or DES).
 418  *
 419  *  @return             Returns CryptoCC32XX_STATUS_SUCCESS if successful else would return
 420  *                      CryptoCC32XX_STATUS_ERROR on an error.
 421  *
 422  *  @sa                 CryptoCC32XX_open()
 423  */
 424 int32_t CryptoCC32XX_encrypt(  CryptoCC32XX_Handle handle, CryptoCC32XX_EncryptMethod method ,
 425                             void *pInBuff, size_t inLen,
 426                             void *pOutBuff , size_t *outLen , CryptoCC32XX_EncryptParams *pParams);
 427
 428 /*!
 429  *  @brief Function which decrypt given cipher data by a given AES or DES method.
 430  *  relevant to CryptoCC32XX_AES and CryptoCC32XX_DES
 431  *
 432  *  @param  handle      A CryptoCC32XX_Handle
 433  *
 434  *  @param  method      An AES or DES decryption method to use on a given cipher data.
 435  *
 436  *  @param  pInBuff     Pointer to cipher data to decrypt.
 437  *
 438  *  @param  inLen       Size of cipher data to decrypt.
 439  *
 440  *  @param  pOutBuff    Pointer to decrypted data (plain text).
 441  *
 442  *  @param  outLen      Size of decrypted data.
 443  *
 444  *  @param  pParams     Specific parameters according to Crypto Type (AES or DES).
 445  *
 446  *  @return             Returns CryptoCC32XX_STATUS_SUCCESS if successful else would return
 447  *                      CryptoCC32XX_STATUS_ERROR on an error.
 448  *
 449  *  @sa                 CryptoCC32XX_open()
 450  */
 451 int32_t CryptoCC32XX_decrypt(  CryptoCC32XX_Handle handle, CryptoCC32XX_EncryptMethod method ,
 452                             void *pInBuff, size_t inLen,
 453                             void *pOutBuff , size_t *outLen , CryptoCC32XX_EncryptParams *pParams);
 454
 455 /*!
 456  *  @brief Function which generates the HMAC Hash value of given plain Text.
 457  *  relevant to CryptoCC32XX_HMAC
 458  *
 459  *  @param  handle      A CryptoCC32XX_Handle
 460  *
 461  *  @param  method      HMAC Hash algorithm to use in order to generates the hash value
 462  *
 463  *  @param  pBuff       Pointer to plain data.
 464  *
 465  *  @param  len         Size of plain data.
 466  *
 467  *  @param  pSignature  As input pointer to the given HMAC Hash value in case the HMAC flag was set
 468  *                      and as output pointer for the generated Hash value.
 469  *
 470  *  @param  pParams     Specific parameters according to HMAC algorithm
 471  *
 472  *  @return             Returns CryptoCC32XX_STATUS_SUCCESS if successful else would return
 473  *                      CryptoCC32XX_STATUS_ERROR on an error.
 474  *
 475  *  @sa                 CryptoCC32XX_open()
 476  */
 477 int32_t CryptoCC32XX_sign( CryptoCC32XX_Handle handle, CryptoCC32XX_HmacMethod method ,
 478                         void *pBuff, size_t len,
 479                         uint8_t *pSignature, CryptoCC32XX_HmacParams *pParams);
 480
 481 /*!
 482  *  @brief Function which verify a given Hash value on given plain Text.
 483  *  relevant to CryptoCC32XX_HMAC
 484  *
 485  *  @param  handle      A CryptoCC32XX_Handle
 486  *
 487  *  @param  method      HMAC Hash algorithm to use in order to verify the hash value
 488  *
 489  *  @param  pBuff       Pointer to plain data.
 490  *
 491  *  @param  len         Size of plain data.
 492  *
 493  *  @param  pSignature  As input pointer to the given HMAC Hash value in case the HMAC flag was set
 494  *                      and as output pointer for the generated Hash value.
 495  *
 496  *  @param  pParams     Specific parameters according to HMAC algorithm.
 497  *
 498  *  @return             Returns CryptoCC32XX_STATUS_SUCCESS if value was successfully verified
 499  *                      else would return CryptoCC32XX_STATUS_ERROR.
 500  *
 501  *  @sa                 CryptoCC32XX_open()
 502  */
 503 int32_t CryptoCC32XX_verify(   CryptoCC32XX_Handle handle, CryptoCC32XX_HmacMethod method ,
 504                             void *pBuff, size_t len,
 505                             uint8_t *pSignature, CryptoCC32XX_HmacParams *pParams);
 506
 507
 508 #ifdef __cplusplus
 509 }
 510 #endif
 511
 512 #endif /* ti_drivers_CryptoCC32XX__include */