inc/FSecCryptoIHash.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                FSecCryptoIHash.h
  19  * @brief               This is the header file for the %IHash interface.
  20  *
  21  * This header file contains the declarations of the %IHash interface.
  22  */
  23 #ifndef _FSEC_CRYPTO_IHASH_H_
  24 #define _FSEC_CRYPTO_IHASH_H_
  25
  26 #include <FBaseString.h>
  27 #include <FBaseByteBuffer.h>
  28
  29 namespace Tizen { namespace Security { namespace Crypto
  30 {
  31
  32 /**
  33  *      @interface      IHash
  34  *      @brief          This interface provides the functionality of a hash algorithm.
  35  *
  36  *      @since          2.0
  37  *
  38  *      The %IHash interface provides the functionality of a hash algorithm. @n
  39  *
  40  *      For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/security/hashing.htm">Hashing</a>. @n
  41  *
  42  *      The following example demonstrates how to use the %IHash interface.
  43  *      @code
  44  *
  45  *      result
  46  *      MyClass::TestHashSample(void)
  47  *      {
  48  *              const int messageLen    = 49;
  49  *              static const byte message[messageLen] = {
  50  *                      0xF4,  0xA4,  0xA2,  0x40,  0xB0,  0xAB,  0x73,  0x1B,  0xC8,  0x10,  0xEA,  0x08,  0x9C,  0xD0,  0x78,  0x0D,
  51  *                      0x40,  0xB9,  0x94,  0x02,  0x21,  0x79,  0xFD,  0x5A,  0xA3,  0xC9,  0x17,  0x64,  0x9B,  0x27,  0xC5,  0x20,
  52  *                      0x03,  0x7B,  0x4D,  0x7C,  0x4D,  0xE6,  0xEE,  0x64,  0x78,  0xA2,  0xBE,  0x2C,  0x22,  0x0A,  0x8E,  0x37,
  53  *                      0xB4,
  54  *              };
  55  *
  56  *              const int sampleOutputLen       = 20;
  57  *              static const byte sampleOutput[sampleOutputLen] = {
  58  *                      0xC4,  0x10,  0xB8,  0x6E,  0xDA,  0x00,  0xE3,  0x2C,  0x8A,  0xC4,
  59  *                      0xE5,  0xDC,  0xB0,  0xE0,  0xE8,  0x2C,  0x21,  0xB6,  0x4E,  0x73
  60  *              };
  61  *
  62  *              const int Sha1Len       = 20;
  63  *
  64  *              result r = E_FAILURE;
  65  *              IHash * pHash   = null;
  66  *
  67  *              ByteBuffer input;
  68  *              ByteBuffer *pOutput = null;
  69  *
  70  *              input.Construct(messageLen);
  71  *              input.SetArray(message, 0, messageLen);
  72  *              input.Flip();
  73  *
  74  *              pHash = new Sha1Hash();
  75  *              if (pHash == null)
  76  *              {
  77  *                      goto CATCH;
  78  *              }
  79  *
  80  *              pOutput = pHash->GetHashN(input);
  81  *              if (pOutput == null)
  82  *              {
  83  *                      r = GetLastResult();
  84  *                      goto CATCH;
  85  *              }
  86  *
  87  *              if (memcmp(pOutput->GetPointer(), sampleOutput, Sha1Len) != 0)
  88  *              {
  89  *                      goto CATCH;
  90  *              }
  91  *              r = E_SUCCESS;
  92  *
  93  *      CATCH:
  94  *              delete pHash;
  95  *              delete pOutput;
  96  *
  97  *              return r;
  98  *      }
  99  *
 100  *
 101  *      result
 102  *      MyClass::TestHashSample_Multipart(void)
 103  *      {
 104  *              const int messageLen    = 49;
 105  *              static const byte message[messageLen] = {
 106  *                      0xF4,  0xA4,  0xA2,  0x40,  0xB0,  0xAB,  0x73,  0x1B,  0xC8,  0x10,  0xEA,  0x08,  0x9C,  0xD0,  0x78,  0x0D,
 107  *                      0x40,  0xB9,  0x94,  0x02,  0x21,  0x79,  0xFD,  0x5A,  0xA3,  0xC9,  0x17,  0x64,  0x9B,  0x27,  0xC5,  0x20,
 108  *                      0x03,  0x7B,  0x4D,  0x7C,  0x4D,  0xE6,  0xEE,  0x64,  0x78,  0xA2,  0xBE,  0x2C,  0x22,  0x0A,  0x8E,  0x37,
 109  *                      0xB4,
 110  *              };
 111  *
 112  *              const int sampleOutputLen       = 20;
 113  *              static const byte sampleOutput[sampleOutputLen] = {
 114  *                      0xC4,  0x10,  0xB8,  0x6E,  0xDA,  0x00,  0xE3,  0x2C,  0x8A,  0xC4,
 115  *                      0xE5,  0xDC,  0xB0,  0xE0,  0xE8,  0x2C,  0x21,  0xB6,  0x4E,  0x73
 116  *              };
 117  *
 118  *              const int Sha1Len       = 20;
 119  *              int     unitLen = messageLen / 5;
 120  *              int dataLen = 0;
 121  *
 122  *              result r = E_FAILURE;
 123  *              IHash * pHash   = null;
 124  *
 125  *              ByteBuffer input;
 126  *              ByteBuffer *pOutput = null;
 127  *
 128  *              input.Construct(messageLen);
 129  *              input.SetArray(message, 0, messageLen);
 130  *              input.Flip();
 131  *
 132  *              pHash = new Sha1Hash();
 133  *              if (pHash == null)
 134  *              {
 135  *                      goto CATCH;
 136  *              }
 137  *
 138  *              r = pHash->Initialize();
 139  *              if (r != E_SUCCESS)
 140  *              {
 141  *                      goto CATCH;
 142  *              }
 143  *
 144  *              for (int i = 0; i * unitLen < messageLen; i++)
 145  *              {
 146  *                      if (messageLen - (i * unitLen) < unitLen)
 147  *                      {
 148  *                              dataLen = messageLen - (i * unitLen);
 149  *                      }
 150  *                      else
 151  *                      {
 152  *                              dataLen = unitLen;
 153  *                      }
 154  *
 155  *                      // messageLen == 98
 156  *                      input.Construct(dataLen);
 157  *                      input.SetArray(message + (i * unitLen), 0, dataLen);
 158  *                      input.Flip();
 159  *
 160  *                      r = pHash->Update(input);
 161  *                      if (r != E_SUCCESS)
 162  *                      {
 163  *                              goto CATCH;
 164  *                      }
 165  *
 166  *                      input.Clear();
 167  *              }
 168  *
 169  *              pOutput = pHash->FinalizeN();
 170  *              if (pOutput == null)
 171  *              {
 172  *                      r = GetLastResult();
 173  *                      goto CATCH;
 174  *              }
 175  *
 176  *              if (memcmp(pOutput->GetPointer(), sampleOutput, Sha1Len) != 0)
 177  *              {
 178  *                      goto CATCH;
 179  *              }
 180  *
 181  *              r = E_SUCCESS;
 182  *
 183  *      CATCH:
 184  *              delete pHash;
 185  *              delete pOutput;
 186  *
 187  *              return r;
 188  *      }
 189  *
 190  *  @endcode
 191  */
 192
 193 class _OSP_EXPORT_ IHash
 194 {
 195
 196 public:
 197         /**
 198          * This polymorphic destructor should be overridden if required. @n
 199          * This way, the destructors of the derived classes are called when the destructor of this interface is called.
 200          *
 201          * @since               2.0
 202          */
 203         virtual ~IHash(void) {}
 204
 205         /**
 206          *      Sets the hash algorithm. @n
 207          *      This method is only supported in Secure Hash Algorithm-2 (SHA-2).
 208          *
 209          *      @since          2.0
 210          *
 211          *      @return         An error code
 212          *      @param[in]      algorithm                               The hash algorithm name @n
 213          *                                                                              For example, "SHA2/224", "SHA2/256", "SHA2/384", or "SHA2/512".
 214          *      @exception      E_SUCCESS                               The method is successful.
 215          *      @exception      E_UNSUPPORTED_ALGORITHM The algorithm is not supported.
 216          */
 217         virtual result SetAlgorithm(const Tizen::Base::String& algorithm) = 0;
 218
 219         /**
 220          *      Gets the hashes of the data (single-part).
 221          *
 222          *      @since          2.0
 223          *
 224          *      @return         A pointer to the Tizen::Base::ByteBuffer class that contains the output, @n
 225          *                              else @c null if an error occurs
 226          *      @param[in]      input                                   An instance of Tizen::Base::ByteBuffer containing the data
 227          *      @exception      E_SUCCESS                               The method is successful.
 228          *      @exception      E_INVALID_ARG                   The input Tizen::Base::ByteBuffer is empty or contains invalid data.
 229          *      @exception      E_OUT_OF_MEMORY                 The memory is insufficient.
 230          *      @exception      E_SYSTEM                                Either of the following conditions has occurred:
 231          *                                                                              - A system error has occurred.
 232          *                                                                              - The method has failed to operate with the openssl library.
 233          *                                                                              - The Tizen::Base::ByteBuffer operation has failed.
 234          */
 235         virtual Tizen::Base::ByteBuffer* GetHashN(const Tizen::Base::ByteBuffer& input) const = 0;
 236
 237         /**
 238          *      Initializes the multiple-part hash operation.
 239          *
 240          *      @since          2.0
 241          *
 242          *      @return         An error code
 243          *      @exception      E_SUCCESS                               The method is successful.
 244          *      @exception      E_OUT_OF_MEMORY                 The memory is insufficient.
 245          *      @exception      E_SYSTEM                                Either of the following conditions has occurred:
 246          *                                                                              - A system error has occurred.
 247          *                                                                              - The method has failed to operate with the openssl library.
 248          */
 249         virtual result Initialize(void) = 0;
 250
 251         /**
 252          *      Updates the multiple-part hash operation while processing another data part.
 253          *
 254          *      @since          2.0
 255          *
 256          *      @return         An error code
 257          *      @param[in]      input                                   An instance of Tizen::Base::ByteBuffer
 258          *      @exception      E_SUCCESS                               The method is successful.
 259          *      @exception      E_INVALID_ARG                   The input Tizen::Base::ByteBuffer is empty or contains invalid data.
 260          *      @exception      E_OUT_OF_MEMORY                 The memory is insufficient.
 261          *      @exception      E_SYSTEM                                Either of the following conditions has occurred:
 262          *                                                                              - A system error has occurred.
 263          *                                                                              - The method has failed to operate with the openssl library.
 264          *                                                                              - The Tizen::Base::ByteBuffer operation has failed.
 265          */
 266         virtual result Update(const Tizen::Base::ByteBuffer& input) = 0;
 267
 268         /**
 269          *      Finalizes the multiple-part hash operation.
 270          *
 271          *      @since          2.0
 272          *
 273          *      @return         A pointer to the Tizen::Base::ByteBuffer class that contains the output, @n
 274          *                              else @c null if an error occurs
 275          *      @exception      E_SUCCESS                               The method is successful.
 276          *      @exception      E_OUT_OF_MEMORY                 The memory is insufficient.
 277          *      @exception      E_SYSTEM                                Either of the following conditions has occurred:
 278          *                                                                              - A system error has occurred.
 279          *                                                                              - The method has failed to operate with the openssl library.
 280          *                                                                              - The Tizen::Base::ByteBuffer operation has failed.
 281          */
 282         virtual Tizen::Base::ByteBuffer* FinalizeN(void) = 0;
 283
 284 protected:
 285         //
 286         //      This method is for internal use only. Using this method can cause behavioral, security-related,
 287         //      and consistency-related issues in the application.
 288         //
 289         //      This method is reserved and may change its name at any time without prior notice.
 290         //
 291         //      @since 2.0
 292         //
 293         virtual void IHash_Reserved1(void) {}
 294
 295 }; //IHash
 296
 297 } } } //Tizen::Security::Crypto
 298
 299 #endif //_FSEC_CRYPTO_IHASH_H_