update header for Doxygen
[platform/framework/native/appfw.git] / 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_