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