inc/FSecCryptoIHmac.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
   4 //
   5 // Licensed under the Apache License, Version 2.0 (the License);
   6 // you may not use this file except in compliance with the License.
   7 // You may obtain a copy of the License at
   8 //
   9 //     http://www.apache.org/licenses/LICENSE-2.0
  10 //
  11 // Unless required by applicable law or agreed to in writing, software
  12 // distributed under the License is distributed on an "AS IS" BASIS,
  13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 // See the License for the specific language governing permissions and
  15 // limitations under the License.
  16 //
  17
  18 /**
  19  *      @file           FSecCryptoIHmac.h
  20  *      @brief  This is the header file for the %IHmac interface.
  21  *
  22  *      This header file contains the declarations of the %IHmac interface.
  23  */
  24 #ifndef _FSEC_CRYPTO_IHMAC_H_
  25 #define _FSEC_CRYPTO_IHMAC_H_
  26
  27 #include <FBaseString.h>
  28 #include <FBaseByteBuffer.h>
  29 #include <FSecISecretKey.h>
  30
  31
  32 namespace Tizen { namespace Security { namespace Crypto
  33 {
  34
  35 /**
  36  *      @interface      IHmac
  37  *      @brief          This interface provides the functionality of a Hash Message Authentication Code (HMAC) algorithm.
  38  *
  39  *      @since          2.0
  40  *
  41  *      The %IHmac interface provides the functionality of a Hash Message Authentication Code (HMAC) algorithm. @n
  42  *
  43  *      For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/security/hashing.htm">Hashing</a>. @n
  44  *
  45  *      The following example demonstrates how to use the %IHmac interface.
  46  *
  47  *      @code
  48  *
  49  *      result
  50  *      MyClass::TestHmacSample(void)
  51  *      {
  52  *              const int messageLen    = 64;
  53  *              static const byte message[messageLen] = {
  54  *                      0x41, 0x42, 0x43, 0x44, 0x45, 0x46, 0x47, 0x48,
  55  *                      0x49, 0x4A, 0x4B, 0x4C, 0x4D, 0x4E, 0x4F, 0x50,
  56  *                      0x51, 0x52, 0x53, 0x54, 0x55, 0x56, 0x57, 0x58,
  57  *                      0x59, 0x5A, 0x5B, 0x5C, 0x5D, 0x5E, 0x5F, 0x60,
  58  *                      0x61, 0x62, 0x63, 0x64, 0x65, 0x66, 0x67, 0x68,
  59  *                      0x69, 0x6A, 0x6B, 0x6C, 0x6D, 0x6E, 0x6F, 0x70,
  60  *                      0x71, 0x72, 0x73, 0x74, 0x75, 0x76, 0x77, 0x78,
  61  *                      0x79, 0x7A, 0x7B, 0x7C, 0x7D, 0x7E, 0x7F, 0x80
  62  *              };
  63  *
  64  *              const int macKeyLen     = 20;
  65  *              static const byte macKey[macKeyLen] = {
  66  *                      0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17,
  67  *                      0x18, 0x19, 0x1A, 0x1B, 0x1C, 0x1D, 0x1E, 0x1F,
  68  *                      0x20, 0x21, 0x22, 0x23
  69  *              };
  70  *
  71  *              const int sampleOutputLen       = 20;
  72  *              static const byte sampleOutput[sampleOutputLen] = {
  73  *                      0x0f, 0xf4, 0xd8, 0x25, 0x33, 0xe5, 0xd8, 0x22,
  74  *                      0x70, 0x8c, 0x8f, 0x76, 0xda, 0x9e, 0x6c, 0xaf,
  75  *                      0x71, 0xea, 0x1a, 0x5b
  76  *              };
  77  *
  78  *              const int Sha1Len       = 20;
  79  *
  80  *              result r = E_FAILURE;
  81  *              IHmac *pHmac    = null;
  82  *              ByteBuffer input;
  83  *              ByteBuffer *pOutput = null;
  84  *              ByteBuffer keyBytes;
  85  *              SecretKeyGenerator *pKeyGen = null;
  86  *              ISecretKey      *pKey = null;
  87  *
  88  *              input.Construct(messageLen);
  89  *              input.SetArray(message, 0, messageLen);
  90  *              input.Flip();
  91  *
  92  *              keyBytes.Construct(macKeyLen);
  93  *              keyBytes.SetArray(macKey, 0, macKeyLen);
  94  *              keyBytes.Flip();
  95  *
  96  *              // HMAC Creation
  97  *              pHmac = new Sha1Hmac();
  98  *              if (pHmac == null)
  99  *              {
 100  *                      goto CATCH;
 101  *              }
 102  *
 103  *              // Generates the key.
 104  *              pKeyGen = new SecretKeyGenerator();
 105  *              if (pKeyGen == null)
 106  *              {
 107  *                      goto CATCH;
 108  *              }
 109  *
 110  *              r = pKeyGen->Construct(keyBytes);
 111  *              if (r != E_SUCCESS)
 112  *              {
 113  *                      goto CATCH;
 114  *              }
 115  *
 116  *              pKey = pKeyGen->GenerateKeyN();
 117  *              if (pKey == null)
 118  *              {
 119  *                      goto CATCH;
 120  *              }
 121  *
 122  *              r = pHmac->SetKey(*pKey);
 123  *              if (r != E_SUCCESS)
 124  *              {
 125  *                      goto CATCH;
 126  *              }
 127  *
 128  *              pOutput = pHmac->GetHmacN(input);
 129  *              if (pOutput == null)
 130  *              {
 131  *                      r = GetLastResult();
 132  *                      goto CATCH;
 133  *              }
 134  *
 135  *              if (memcmp(pOutput->GetPointer(), sampleOutput, Sha1Len) != 0)
 136  *              {
 137  *                      goto CATCH;
 138  *              }
 139  *
 140  *              r = E_SUCCESS;
 141  *      CATCH:
 142  *              delete pHmac;
 143  *              delete pKeyGen;
 144  *              delete pOutput;
 145  *              delete pKey;
 146  *
 147  *              return r;
 148  *      }
 149  *
 150  *      result
 151  *      MyClass::TestHmacSample_Multipart(void)
 152  *      {
 153  *              const int messageLen    = 64;
 154  *              static const byte message[messageLen] = {
 155  *                      0x41, 0x42, 0x43, 0x44, 0x45, 0x46, 0x47, 0x48,
 156  *                      0x49, 0x4A, 0x4B, 0x4C, 0x4D, 0x4E, 0x4F, 0x50,
 157  *                      0x51, 0x52, 0x53, 0x54, 0x55, 0x56, 0x57, 0x58,
 158  *                      0x59, 0x5A, 0x5B, 0x5C, 0x5D, 0x5E, 0x5F, 0x60,
 159  *                      0x61, 0x62, 0x63, 0x64, 0x65, 0x66, 0x67, 0x68,
 160  *                      0x69, 0x6A, 0x6B, 0x6C, 0x6D, 0x6E, 0x6F, 0x70,
 161  *                      0x71, 0x72, 0x73, 0x74, 0x75, 0x76, 0x77, 0x78,
 162  *                      0x79, 0x7A, 0x7B, 0x7C, 0x7D, 0x7E, 0x7F, 0x80
 163  *              };
 164  *
 165  *              // This contains the MAC key to be used.
 166  *              const int macKeyLen     = 20;
 167  *              static const byte macKey[macKeyLen] = {
 168  *                      0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17,
 169  *                      0x18, 0x19, 0x1A, 0x1B, 0x1C, 0x1D, 0x1E, 0x1F,
 170  *                      0x20, 0x21, 0x22, 0x23
 171  *              };
 172  *
 173  *              const int sampleOutputLen       = 20;
 174  *              static const byte sampleOutput[sampleOutputLen] = {
 175  *                      0x0f, 0xf4, 0xd8, 0x25, 0x33, 0xe5, 0xd8, 0x22,
 176  *                      0x70, 0x8c, 0x8f, 0x76, 0xda, 0x9e, 0x6c, 0xaf,
 177  *                      0x71, 0xea, 0x1a, 0x5b
 178  *              };
 179  *
 180  *              const int Sha1Len       = 20;
 181  *              int     unitLen = messageLen / 5;
 182  *              int dataLen = 0;
 183  *
 184  *              result r = E_FAILURE;
 185  *              IHmac * pHmac   = null;
 186  *              ByteBuffer input;
 187  *              ByteBuffer *pOutput = null;
 188  *              ByteBuffer keyBytes;
 189  *              SecretKeyGenerator* pKeyGen = null;
 190  *              ISecretKey      *pKey   = null;
 191  *
 192  *              input.Construct(messageLen);
 193  *              input.SetArray(message, 0, messageLen);
 194  *              input.Flip();
 195  *
 196  *              keyBytes.Construct(macKeyLen);
 197  *              keyBytes.SetArray(macKey, 0, macKeyLen);
 198  *              keyBytes.Flip();
 199  *
 200  *              // HMAC Creation
 201  *              pHmac = new Sha1Hmac();
 202  *              if (pHmac == null)
 203  *              {
 204  *                      goto CATCH;
 205  *              }
 206  *
 207  *              // Generates the key.
 208  *              pKeyGen = new SecretKeyGenerator();
 209  *              if (pKeyGen == null)
 210  *              {
 211  *                      goto CATCH;
 212  *              }
 213  *
 214  *              r = pKeyGen->Construct(keyBytes);
 215  *              if (r != E_SUCCESS)
 216  *              {
 217  *                      goto CATCH;
 218  *              }
 219  *
 220  *              pKey = pKeyGen->GenerateKeyN();
 221  *              if (pKey == null)
 222  *              {
 223  *                      goto CATCH;
 224  *              }
 225  *
 226  *              r = pHmac->SetKey(*pKey);
 227  *              if (r != E_SUCCESS)
 228  *              {
 229  *                      goto CATCH;
 230  *              }
 231  *
 232  *              r = pHmac->Initialize();
 233  *              if (r != E_SUCCESS)
 234  *              {
 235  *                      goto CATCH;
 236  *              }
 237  *
 238  *              for (int i = 0; i *     unitLen < messageLen; i++)
 239  *              {
 240  *                      if (messageLen - (i *   unitLen) < unitLen)
 241  *                      {
 242  *                              dataLen = messageLen - (i *     unitLen);
 243  *                      }
 244  *                      else
 245  *                      {
 246  *                              dataLen = unitLen;
 247  *                      }
 248  *
 249  *                      // MessageLen == 98
 250  *                      input.Construct(dataLen);
 251  *                      input.SetArray(message + (i *   unitLen), 0, dataLen);
 252  *                      input.Flip();
 253  *
 254  *                      r = pHmac->Update(input);
 255  *                      if (r != E_SUCCESS)
 256  *                      {
 257  *                              goto CATCH;
 258  *                      }
 259  *
 260  *                      input.Clear();
 261  *              }
 262  *
 263  *              pOutput = pHmac->FinalizeN();
 264  *              if (pOutput == null)
 265  *              {
 266  *                      r = GetLastResult();
 267  *                      goto CATCH;
 268  *              }
 269  *
 270  *              if (memcmp(pOutput->GetPointer(), sampleOutput, Sha1Len) != 0)
 271  *              {
 272  *                      goto CATCH;
 273  *              }
 274  *
 275  *              r = E_SUCCESS;
 276  *      CATCH:
 277  *              delete pHmac;
 278  *              delete pKeyGen;
 279  *              delete pOutput;
 280  *              delete pKey;
 281  *
 282  *              return r;
 283  *      }
 284  *
 285  *       @endcode
 286  */
 287
 288 class _OSP_EXPORT_ IHmac
 289 {
 290
 291 public:
 292         /**
 293          * This polymorphic destructor should be overridden if required. This way, the destructors of the derived classes @n
 294          * are called when the destructor of this interface is called.
 295          *
 296          *      @since          2.0
 297          */
 298         virtual ~IHmac(void) {}
 299
 300         /**
 301          *      Sets the HMAC algorithm.
 302          *
 303          *      @since          2.0
 304          *
 305          *      @return         An error code
 306          *      @param[in]      algorithm                               The name of the HMAC algorithm @n
 307          *                                                                              For example, "HMACSHA2/224", "HMACSHA2/256", "HMACSHA2/384", or "HMACSHA2/512".
 308          *      @exception      E_SUCCESS                               The method is successful.
 309          *      @exception      E_UNSUPPORTED_ALGORITHM The algorithm is not supported.
 310          */
 311         virtual result SetAlgorithm(const Tizen::Base::String& algorithm) = 0;
 312
 313         /**
 314          *      Sets the secret key.
 315          *
 316          *      @since          2.0
 317          *
 318          *      @return         An error code
 319          *      @param[in]      key                                             An instance of ISecretKey
 320          *      @exception      E_SUCCESS                               The method is successful.
 321          *      @exception      E_INVALID_ARG                   The specified key is invalid.
 322          *      @exception      E_OUT_OF_MEMORY                 The memory is insufficient.
 323          */
 324         virtual result SetKey(const Tizen::Security::ISecretKey& key) = 0;
 325
 326         /**
 327          *      Gets the HMAC with the given input.
 328          *
 329          *      @since                  2.0
 330          *
 331          *      @return         A pointer to the Tizen::Base::ByteBuffer class that contains the output, @n
 332          *                              else @c null if an error occurs
 333          *      @param[in]      input                                   An instance of Tizen::Base::ByteBuffer
 334          *      @exception      E_SUCCESS                               The method is successful.
 335          *      @exception      E_INVALID_ARG                   The input Tizen::Base::ByteBuffer is empty or contains invalid data.
 336          *      @exception      E_OUT_OF_MEMORY                 The memory is insufficient.
 337          *      @exception      E_KEY_NOT_FOUND                 The key is not found.
 338          *      @exception      E_SYSTEM                                A system error has occurred. @n
 339          *                                                                              The method has failed to operate with the openssl library, or
 340          *                                                                              the Tizen::Base::ByteBuffer operation has failed.
 341          */
 342         virtual Tizen::Base::ByteBuffer* GetHmacN(const Tizen::Base::ByteBuffer& input) const = 0;
 343
 344         /**
 345          *      Initializes the multiple-part HMAC operation.
 346          *
 347          *      @since          2.0
 348          *
 349          *      @return         An error code
 350          *      @exception      E_SUCCESS                               The method is successful.
 351          *      @exception      E_OUT_OF_MEMORY                 The memory is insufficient.
 352          *      @exception      E_KEY_NOT_FOUND                 The key is not found.
 353          *      @exception      E_SYSTEM                                A system error has occurred. @n
 354          *                                                                              The method has failed to operate with the openssl library.
 355          */
 356         virtual result Initialize(void) = 0;
 357
 358         /**
 359          *      Updates a multiple-part HMAC operation while processing another data part.
 360          *
 361          *      @since          2.0
 362          *
 363          *      @return         An error code
 364          *      @param[in]      input                                   An instance of Tizen::Base::ByteBuffer
 365          *      @exception      E_SUCCESS                               The method is successful.
 366          *      @exception      E_INVALID_ARG                   The input Tizen::Base::ByteBuffer is empty or contains invalid data.
 367          *      @exception      E_OUT_OF_MEMORY                 The memory is insufficient.
 368          *      @exception      E_SYSTEM                                A system error has occurred. @n
 369          *                                                                              The method has failed to operate with the openssl library, or
 370          *                                                                              the Tizen::Base::ByteBuffer operation has failed.
 371          */
 372         virtual result Update(const Tizen::Base::ByteBuffer& input) = 0;
 373
 374         /**
 375          *      Finalizes a multiple-part HMAC operation.
 376          *
 377          *      @since          2.0
 378          *
 379          *      @return         A pointer to the Tizen::Base::ByteBuffer class that contains the output, @n
 380          *                                      else @c null if an error occurs
 381          *      @exception      E_SUCCESS                               The method is successful.
 382          *      @exception      E_OUT_OF_MEMORY                 The memory is insufficient.
 383          *      @exception      E_SYSTEM                                A system error has occurred. @n
 384          *                                                                              The method has failed to operate with the openssl library, or
 385          *                                                                              the Tizen::Base::ByteBuffer operation has failed.
 386          */
 387         virtual Tizen::Base::ByteBuffer* FinalizeN(void) = 0;
 388
 389 protected:
 390         //
 391         //      This method is for internal use only. Using this method can cause behavioral, security-related,
 392         //      and consistency-related issues in the application.
 393         //
 394         //      This method is reserved and may change its name at any time without prior notice.
 395         //
 396         //      @since 2.0
 397         //
 398         virtual void IHmac_Reserved1(void) {}
 399
 400 }; //IHmac
 401
 402 } } } //Tizen::Security::Crypto
 403
 404 #endif //_FSEC_CRYPTO_IHMAC_H_