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