inc/FSecCryptoISymmetricCipher.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           FSecCryptoISymmetricCipher.h
  20  *      @brief  This is the header file for the %ISymmetricCipher interface.
  21  *
  22  *      This header file contains the declarations of the %ISymmetricCipher interface.
  23  */
  24 #ifndef _FSEC_CRYPTO_ISYMMETRIC_CIPHER_H_
  25 #define _FSEC_CRYPTO_ISYMMETRIC_CIPHER_H_
  26
  27 #include <FBaseString.h>
  28 #include <FBaseByteBuffer.h>
  29 #include <FSecISecretKey.h>
  30 #include <FSecCryptoTypes.h>
  31
  32
  33 namespace Tizen { namespace Security { namespace Crypto
  34 {
  35 /**
  36  *      @interface      ISymmetricCipher
  37  *      @brief          This interface provides the functionalities of a symmetric cryptographic cipher for encryption and decryption.
  38  *
  39  *      @since          2.0
  40  *
  41  *      The %ISymmetricCipher interface provides the functionalities of a symmetric cryptographic cipher for encryption and decryption. @n
  42  *
  43  *      For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/security/ciphers.htm">Ciphers</a>. @n
  44  *
  45  *      The following example demonstrates how to use the %ISymmetricCipher interface.
  46  *      @code
  47  *
  48  *      void
  49  *      MyClass::TestSymmetricCipherSample(void)
  50  *      {
  51  *              // #####AES CBC Test Vector(128-bits key)#####
  52  *              // PlainText: 48 Bytes
  53  *              const int messageLen    = 48;
  54  *              static const byte message[messageLen] = {
  55  *                      0x87, 0x3C, 0x66, 0x1D, 0x2C, 0x0D, 0x49, 0x2D,
  56  *                      0x6C, 0x76, 0xBE, 0x44, 0x57, 0x39, 0xB8, 0x28,
  57  *                      0x84, 0x5E, 0x2A, 0x15, 0x18, 0x3B, 0x1D, 0x00,
  58  *                      0xA7, 0x6E, 0x80, 0x4D, 0x22, 0xF1, 0x2A, 0x6B,
  59  *                      0xBA, 0xFE, 0xA8, 0x02, 0x2B, 0xC2, 0x97, 0x01,
  60  *                      0x59, 0x0F, 0x3C, 0x2A, 0x67, 0x8B, 0x98, 0x69
  61  *              };
  62  *
  63  *              // CipherText: 48 Bytes
  64  *              const int cipherLen     = 48;
  65  *              static const byte cipher[cipherLen] = {
  66  *                      0x10, 0x84, 0x9D, 0x24, 0xEB, 0x22, 0xE0, 0x7F,
  67  *                      0xA8, 0x57, 0xE9, 0xA0, 0x4F, 0xE2, 0x3D, 0xE5,
  68  *                      0xC1, 0x51, 0x7E, 0xEB, 0xF8, 0xB3, 0x3A, 0xA2,
  69  *                      0xDC, 0xF4, 0x8B, 0xDC, 0x14, 0x0A, 0xC7, 0x58,
  70  *                      0x85, 0x6B, 0x0D, 0xE9, 0x30, 0x8B, 0xA1, 0x71,
  71  *                      0xD5, 0x0B, 0x14, 0x97, 0xEF, 0xAD, 0x22, 0x8D
  72  *              };
  73  *
  74  *              // KEY: 16Bytes
  75  *              const int secretKeyLen  = 16;
  76  *              static const byte secretKey[secretKeyLen] = {
  77  *                      0x62, 0x5C, 0xC7, 0x7E, 0xEA, 0x7B, 0xA5, 0x4D,
  78  *                      0x47, 0xCE, 0xAF, 0x26, 0x9E, 0xB1, 0x6C, 0x2D
  79  *              };
  80  *
  81  *              // IV: 16Bytes
  82  *              const int ivectorLen    = 16;
  83  *              static const byte ivector[ivectorLen] = {
  84  *                              0x3E, 0xB5, 0x01, 0x45, 0xE4, 0xF8, 0x75, 0x3F,
  85  *                      0x08, 0x9D, 0x9F, 0x57, 0x3B, 0x63, 0xEF, 0x4B
  86  *              };
  87  *
  88  *              result r = E_FAILURE;
  89  *              String transformation;
  90  *              ISymmetricCipher        *pCipherEnc     = null;
  91  *              ISymmetricCipher        *pCipherDec     = null;
  92  *              SecretKeyGenerator      *pKeyGen        = null;
  93  *              ISecretKey                      *pKey           = null;
  94  *              ByteBuffer                      input;
  95  *              ByteBuffer                      *pOutput        = null;
  96  *              ByteBuffer                      *pOutput2       = null;
  97  *              ByteBuffer                      keyBytes;
  98  *              ByteBuffer                      iv;
  99  *
 100  *              // Input
 101  *              input.Construct(messageLen);
 102  *              input.SetArray(message, 0, messageLen);
 103  *              input.Flip();
 104  *
 105  *              // Key
 106  *              keyBytes.Construct(secretKeyLen);
 107  *              keyBytes.SetArray(secretKey, 0, secretKeyLen);
 108  *              keyBytes.Flip();
 109  *
 110  *              // IV setting
 111  *              iv.Construct(ivectorLen);
 112  *              iv.SetArray(ivector, 0, ivectorLen);
 113  *              iv.Flip();
 114  *
 115  *              pCipherEnc = new AesCipher();
 116  *              if (pCipherEnc == null)
 117  *              {
 118  *                      goto CATCH;
 119  *              }
 120  *
 121  *              transformation  = "CBC/128/NOPADDING";
 122  *
 123  *              r = pCipherEnc->Construct(transformation, CIPHER_ENCRYPT);
 124  *              if (IsFailed(r))
 125  *              {
 126  *                      goto CATCH;
 127  *              }
 128  *
 129  *              // Generates the key.
 130  *              pKeyGen = new SecretKeyGenerator();
 131  *              if (pKeyGen == null)
 132  *              {
 133  *                      goto CATCH;
 134  *              }
 135  *
 136  *              r = pKeyGen->Construct(keyBytes);
 137  *              if (IsFailed(r))
 138  *              {
 139  *                      goto CATCH;
 140  *              }
 141  *
 142  *              pKey = pKeyGen->GenerateKeyN();
 143  *              if (pKey == null)
 144  *              {
 145  *                      goto CATCH;
 146  *              }
 147  *
 148  *              r = pCipherEnc->SetKey(*pKey);
 149  *              if (IsFailed(r))
 150  *              {
 151  *                      goto CATCH;
 152  *              }
 153  *
 154  *              r = pCipherEnc->SetInitialVector(iv);
 155  *              if (IsFailed(r))
 156  *              {
 157  *                      goto CATCH;
 158  *              }
 159  *
 160  *              pOutput = pCipherEnc->EncryptN(input);
 161  *              if (pOutput == null)
 162  *              {
 163  *                      r = GetLastResult();
 164  *                      goto CATCH;
 165  *              }
 166  *
 167  *              pCipherDec = new AesCipher();
 168  *              if (pCipherDec == null)
 169  *              {
 170  *                      goto CATCH;
 171  *              }
 172  *
 173  *              r = pCipherDec->Construct(transformation, CIPHER_DECRYPT);
 174  *              if (IsFailed(r))
 175  *              {
 176  *                      goto CATCH;
 177  *              }
 178  *
 179  *              r = pCipherDec->SetKey(*pKey);
 180  *              if (IsFailed(r))
 181  *              {
 182  *                      goto CATCH;
 183  *              }
 184  *
 185  *              r = pCipherDec->SetInitialVector(iv);
 186  *              if (IsFailed(r))
 187  *              {
 188  *                      goto CATCH;
 189  *              }
 190  *
 191  *              pOutput2 = pCipherDec->DecryptN(*pOutput);
 192  *              if (pOutput2 == null)
 193  *              {
 194  *                      r = GetLastResult();
 195  *                      goto CATCH;
 196  *              }
 197  *
 198  *              if (memcmp(pOutput->GetPointer(), cipher, cipherLen) != 0)
 199  *              {
 200  *                      goto CATCH;
 201  *              }
 202  *
 203  *              if (memcmp(pOutput2->GetPointer(), input.GetPointer(), input.GetRemaining()) != 0)
 204  *              {
 205  *                      goto CATCH;
 206  *              }
 207  *
 208  *      CATCH:
 209  *              delete pCipherEnc;
 210  *              delete pCipherDec;
 211  *              delete pKeyGen;
 212  *              delete pOutput;
 213  *              delete pOutput2;
 214  *              delete pKey;
 215  *      }
 216  *
 217  *       @endcode
 218  *
 219  *
 220  */
 221
 222 class _OSP_EXPORT_ ISymmetricCipher
 223 {
 224
 225 public:
 226         /**
 227          * This polymorphic destructor should be overridden if required. This way, the destructors of the derived classes @n
 228          * are called when the destructor of this interface is called.
 229          *
 230          *      @since          2.0
 231          */
 232         virtual ~ISymmetricCipher(void) {}
 233
 234         /**
 235          *      Initializes this instance of %ISymmetricCipher with the specified operation mode and padding scheme.
 236          *
 237          *      @since          2.0
 238          *
 239          *      @return         An error code
 240          *      @param[in]      transformation                  The name of the requested mode or key bit or padding scheme
 241          *      @param[in]      opMode                                  The cipher operation mode @n
 242          *                                                                              For example, @c CIPHER_ENCRYPT, @c CIPHER_DECRYPT, @c CIPHER_WRAP, or @c CIPHER_UNWRAP.
 243          *      @exception      E_SUCCESS                               The method is successful.
 244          *      @exception      E_OUT_OF_MEMORY                 The memory is insufficient.
 245          *      @exception      E_INVALID_ARG                   The specified @c opMode does not contain a valid value for the cipher operation.
 246          *      @exception      E_UNSUPPORTED_ALGORITHM The algorithm is not supported.
 247          */
 248         virtual result Construct(const Tizen::Base::String& transformation, enum CipherOperation opMode = Tizen::Security::Crypto::CIPHER_ENCRYPT) = 0;
 249
 250         /**
 251          *      Sets a symmetric key for encryption or decryption.
 252          *
 253          *      @since          2.0
 254          *
 255          *      @return         An error code
 256          *      @param[in]      key                                             An instance of ISecretKey
 257          *      @exception      E_SUCCESS                               The method is successful.
 258          *      @exception      E_INVALID_ARG                   The specified @c key is invalid.
 259          *      @exception      E_OUT_OF_MEMORY                 The memory is insufficient.
 260          */
 261         virtual result SetKey(const Tizen::Security::ISecretKey& key) = 0;
 262
 263         /**
 264          *      Sets the initial vector.
 265          *
 266          *      @since          2.0
 267          *
 268          *      @return         An error code
 269          *      @param[in]      initialVector                   The initial vector
 270          *      @exception      E_SUCCESS                               The method is successful.
 271          *      @exception      E_INVALID_ARG                   The specified input parameter is invalid.
 272          *      @exception      E_OUT_OF_MEMORY                 The memory is insufficient.
 273          */
 274         virtual result SetInitialVector(const Tizen::Base::ByteBuffer& initialVector) = 0;
 275
 276         /**
 277          *      Encrypts the data (single-part).
 278          *
 279          *      @since          2.0
 280          *
 281          *      @return         A pointer to the Tizen::Base::ByteBuffer class that contains the output, @n
 282          *                              else @c null if an error occurs
 283          *      @param[in]      input                                   An instance of Tizen::Base::ByteBuffer
 284          *      @exception      E_SUCCESS                               The method is successful.
 285          *      @exception      E_INVALID_ARG                   The input Tizen::Base::ByteBuffer is empty or contains invalid data.
 286          *      @exception      E_OUT_OF_MEMORY                 The memory is insufficient.
 287          *      @exception      E_KEY_NOT_FOUND                 The key is not found.
 288          *      @exception      E_INVALID_OPERATION             The specified cipher operation mode for this method is invalid.
 289          *      @exception      E_OVERFLOW                              This operation has caused the memory to overflow.
 290          *      @exception      E_SYSTEM                                A system error has occurred. @n
 291          *                                                                              The method has failed to operate with the openssl library, or
 292          *                                                                              the Tizen::Base::ByteBuffer operation has failed.
 293          */
 294         virtual Tizen::Base::ByteBuffer* EncryptN(const Tizen::Base::ByteBuffer& input) = 0;
 295
 296         /**
 297          *      Decrypts the data (single-part).
 298          *
 299          *      @since          2.0
 300          *
 301          *      @return         A pointer to the Tizen::Base::ByteBuffer class that contains the output, @n
 302          *                              else @c null if an error occurs
 303          *      @param[in]      input                                   An instance of Tizen::Base::ByteBuffer
 304          *      @exception      E_SUCCESS                               The method is successful.
 305          *      @exception      E_INVALID_ARG                   The input Tizen::Base::ByteBuffer is empty or contains invalid data.
 306          *      @exception      E_OUT_OF_MEMORY                 The memory is insufficient.
 307          *      @exception      E_KEY_NOT_FOUND                 The key is not found.
 308          *      @exception      E_INVALID_OPERATION             The specified cipher operation mode for this method is invalid.
 309          *      @exception      E_OVERFLOW                              This operation has caused the memory to overflow.
 310          *      @exception      E_SYSTEM                                A system error has occurred. @n
 311          *                                                                              The method has failed to operate with the openssl library, or
 312          *                                                                              the Tizen::Base::ByteBuffer operation has failed.
 313          */
 314         virtual Tizen::Base::ByteBuffer* DecryptN(const Tizen::Base::ByteBuffer& input) = 0;
 315
 316         /**
 317          *      Initializes a multiple-part encryption or decryption operation.
 318          *
 319          *      @since          2.0
 320          *
 321          *      @return         An error code
 322          *      @exception      E_SUCCESS                               The method is successful.
 323          *      @exception      E_OUT_OF_MEMORY                 The memory is insufficient.
 324          *      @exception      E_KEY_NOT_FOUND                 The key is not found.
 325          *      @exception      E_INVALID_OPERATION             The specified cipher operation mode for this method is invalid.
 326          *      @exception      E_SYSTEM                                A system error has occurred. @n
 327          *                                                                              The method has failed to operate with the openssl library.
 328          */
 329         virtual result Initialize(void) = 0;
 330
 331         /**
 332          *      Updates a multiple-part encryption or decryption operation.
 333          *
 334          *      @since          2.0
 335          *
 336          *      @return         A pointer to the Tizen::Base::ByteBuffer class that contains the output, @n
 337          *                              else @c null if an error occurs
 338          *      @param[in]      input                                   An instance of Tizen::Base::ByteBuffer
 339          *      @exception      E_SUCCESS                               The method is successful.
 340          *      @exception      E_OUT_OF_MEMORY                 The memory is insufficient.
 341          *      @exception      E_OVERFLOW                              This operation has caused the memory to overflow.
 342          *      @exception      E_INVALID_ARG                   The input Tizen::Base::ByteBuffer is empty or contains invalid data.
 343          *      @exception      E_SYSTEM                                A system error has occurred. @n
 344          *                                                                              The method has failed to operate with the openssl library, or
 345          *                                                                              the Tizen::Base::ByteBuffer operation has failed.
 346          *      @remarks                The specific error code can be accessed using the GetLastResult() method.
 347          */
 348         virtual Tizen::Base::ByteBuffer* UpdateN(const Tizen::Base::ByteBuffer& input) = 0;
 349
 350         /**
 351          *      Finalizes a multiple-part encryption or decryption operation.
 352          *
 353          *      @since          2.0
 354          *
 355          *      @return         A pointer to the Tizen::Base::ByteBuffer class that contains the output, @n
 356          *                              else @c null if an error occurs
 357          *      @exception      E_SUCCESS                               The method is successful.
 358          *      @exception      E_OUT_OF_MEMORY                 The memory is insufficient.
 359          *      @exception      E_OVERFLOW                              This operation has caused the memory to overflow.
 360          *      @exception      E_SYSTEM                                A system error has occurred. @n
 361          *                                                                              The method has failed to operate with the openssl library, or
 362          *                                                                              the Tizen::Base::ByteBuffer operation has failed.
 363          *      @remarks                The specific error code can be accessed using the GetLastResult() method.
 364          */
 365         virtual Tizen::Base::ByteBuffer* FinalizeN(void) = 0;
 366
 367         /**
 368          *      Wraps the specified key.
 369          *
 370          *      @since          2.0
 371          *
 372          *      @return         A pointer to the Tizen::Base::ByteBuffer class that contains the output, @n
 373          *                              else @c null if an error occurs
 374          *      @param[in]      secretKey                               The secret key to wrap
 375          *      @exception      E_SUCCESS                               The method is successful.
 376          *      @exception      E_INVALID_ARG                   The input Tizen::Base::ByteBuffer is empty or contains invalid data.
 377          *      @exception      E_OUT_OF_MEMORY                 The memory is insufficient.
 378          *      @exception      E_KEY_NOT_FOUND                 The key is not found.
 379          *      @exception      E_INVALID_OPERATION             The specified cipher operation mode for this method is invalid.
 380          *      @exception      E_SYSTEM                                A system error has occurred. @n
 381          *                                                                              The method has failed to operate with the openssl library, or
 382          *                                                                              the Tizen::Base::ByteBuffer operation has failed.
 383          *      @remarks                The specific error code can be accessed using the GetLastResult() method.
 384          *      @remarks                This operation is only supported in AesCipher.
 385          */
 386         virtual Tizen::Base::ByteBuffer* WrapN(const Tizen::Base::ByteBuffer& secretKey) = 0;
 387
 388         /**
 389          *      Unwraps a previously wrapped key.
 390          *
 391          *      @since          2.0
 392          *
 393          *      @return         A pointer to the Tizen::Base::ByteBuffer class that contains the output, @n
 394          *                              else @c null if an error occurs
 395          *      @param[in]      wrappedKey                              The wrapped key to unwrap
 396          *      @exception      E_SUCCESS                               The method is successful.
 397          *      @exception      E_INVALID_ARG                   The specified @c wrappedKey Tizen::Base::ByteBuffer is invalid.
 398          *      @exception      E_OUT_OF_MEMORY                 The memory is insufficient.
 399          *      @exception      E_KEY_NOT_FOUND                 The key is not found.
 400          *      @exception      E_INVALID_OPERATION             The specified cipher operation mode for this method is invalid.
 401          *      @exception      E_SYSTEM                                A system error has occurred. @n
 402          *                                                                              The method has failed to operate with the openssl library, or
 403          *                                                                              the Tizen::Base::ByteBuffer operation has failed.
 404          *      @remarks                The specific error code can be accessed using the GetLastResult() method.
 405          *      @remarks                This operation is only supported in AesCipher.
 406          */
 407         virtual Tizen::Base::ByteBuffer* UnwrapN(const Tizen::Base::ByteBuffer& wrappedKey) = 0;
 408
 409 protected:
 410         //
 411         //      This method is for internal use only. Using this method can cause behavioral, security-related,
 412         //      and consistency-related issues in the application.
 413         //
 414         //      This method is reserved and may change its name at any time without prior notice.
 415         //
 416         //      @since 2.0
 417         //
 418         virtual void ISymmetricCipher_Reserved1(void) {}
 419
 420 }; //ISymmetricCipher
 421
 422 } } } //Tizen::Security::Crypto
 423
 424 #endif //_FSEC_CRYPTO_ISYMMETRIC_CIPHER_H_