inc/FSecCryptoIHmac.h

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