sync with tizen_2.0
[platform/framework/native/appfw.git] / inc / FSecCryptoRc2Cipher.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                FSecCryptoRc2Cipher.h
20  * @brief               This is the header file for the %Rc2Cipher class.
21  *
22  * This header file contains the declarations of the %Rc2Cipher class.
23  */
24 #ifndef _FSEC_CRYPTO_RC2_CIPHER_H_
25 #define _FSEC_CRYPTO_RC2_CIPHER_H_
26
27 #include <FSecCryptoISymmetricCipher.h>
28
29 struct evp_cipher_st;
30
31 namespace Tizen { namespace Security { namespace Crypto
32 {
33
34 class _SymmetricCipher;
35 /**
36  *      @class          Rc2Cipher
37  *      @brief          This class provides methods for encryption and decryption using the RC2 algorithm.
38  *
39  *      @since          2.0
40  *
41  *      The %Rc2Cipher class provides a symmetric cipher using the RC2 algorithm.
42  *      It sets appropriate values for the requested mode/key bit/padding scheme and cipher operation (CIPHER_ENCRYPT or CIPHER_DECRYPT) parameters. @n
43  *
44  *      For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/security/ciphers.htm">Ciphers</a>.
45  *
46  *      @see    ISymmetricCipher
47  *  @see        DesCipher
48  *  @see        DesEdeCipher
49  */
50 class _OSP_EXPORT_ Rc2Cipher
51         : public virtual ISymmetricCipher
52         , public Tizen::Base::Object
53 {
54
55 public:
56         /**
57          *      The object is not fully constructed after this constructor is called. For full construction, @n
58          *      the Construct() method must be called right after calling this constructor.
59          *
60          *      @since          2.0
61          */
62         Rc2Cipher(void);
63
64         /**
65          *      This destructor overrides Tizen::Base::Object::~Object().
66          *
67          *      @since          2.0
68          */
69         virtual ~Rc2Cipher(void);
70
71         /**
72          *      Constructs and initializes this instance of %Rc2Cipher with the specified parameters.
73          *
74          *      @since          2.0
75          *
76          *      @return         An error code
77          *      @param[in]      transformation                  The name of the requested mode/padding scheme @n
78          *                                                                              The RC2 support variable length key ranges from 8 bits to 128 bits, in steps of 8 bits.
79          *                                                                              The key bits are not required to be mentioned in the transformation.
80          *                                                                              There are four valid transformations for RC2, "CBC/NOPADDING",
81          *                                                                              "CBC/PKCS7PADDING", "ECB/PKCS7PADDING", and "ECB/NOPADDING".
82          *      @param[in]      opMode                                  The cipher operation mode @n
83          *                                                                              The valid values for %Rc2Cipher are @c CIPHER_ENCRYPT and @c CIPHER_DECRYPT.
84          *      @exception      E_SUCCESS                               The method is successful.
85          *  @exception  E_OUT_OF_MEMORY                 The memory is insufficient.
86          *      @exception      E_INVALID_ARG                   A specified input parameter is invalid, or the specified @c opMode does not contain a valid value for the cipher operation.
87          *      @remarks        If @c opMode is not matching the actual operation, the result of the operation is @c null and an exception is returned. @n
88          *      For example, if @c opMode is set to @c CIPHER_ENCRYPT, @c CIPHER_WRAP, or @c CIPHER_UNWRAP and the DecryptN() method is used, then the result obtained is @c null and an exception is returned.
89          */
90         virtual result Construct(const Tizen::Base::String& transformation, enum CipherOperation opMode);
91
92         /**
93          *      Sets a symmetric key for encryption or decryption. @n
94          *  The variable length key ranges from 8 bits to 128 bits, in steps of 8 bits.
95          *
96          *      @since          2.0
97          *
98          *      @return         An error code
99          *      @param[in]      key                                             An instance of ISecretKey
100          *      @exception      E_SUCCESS                               The method is successful.
101          *      @exception      E_INVALID_ARG                   The specified @c key is invalid.
102          *      @exception      E_OUT_OF_MEMORY                 The memory is insufficient.
103          */
104         virtual result SetKey(const Tizen::Security::ISecretKey& key);
105
106         /**
107          *      Sets the initial vector.
108          *
109          *      @since          2.0
110          *
111          *      @return         An error code
112          *      @param[in]      initialVector                   The initial vector
113          *      @exception      E_SUCCESS                               The method is successful.
114          *      @exception      E_INVALID_ARG                   The specified input parameter is invalid.
115          *      @exception      E_OUT_OF_MEMORY                 The memory is insufficient.
116          */
117         virtual result SetInitialVector(const Tizen::Base::ByteBuffer& initialVector);
118
119         /**
120          *      Encrypts the data (single-part).
121          *
122          *      @since          2.0
123          *
124          *      @return         A pointer to the Tizen::Base::ByteBuffer class that contains the output, @n
125          *                              else @c null if an error occurs
126          *      @param[in]      input                                   An instance of Tizen::Base::ByteBuffer
127          *      @exception      E_SUCCESS                               The method is successful.
128          *      @exception      E_INVALID_ARG                   The specified instance of Tizen::Base::ByteBuffer is invalid or empty.
129          *      @exception      E_OUT_OF_MEMORY                 The memory is insufficient.
130          *      @exception      E_KEY_NOT_FOUND                 The specified key is not found.
131          *      @exception      E_INVALID_OPERATION             The specified cipher operation mode for this method is invalid.
132          *      @exception      E_OVERFLOW                              This operation has caused the memory to overflow.
133          *      @exception      E_SYSTEM                                A system error has occurred. @n
134          *                                                                              The method has failed to operate with the OpenSSL library, or
135          *                                                                              the Tizen::Base::ByteBuffer operation has failed.
136          *      @remarks        The specific error code can be accessed using the GetLastResult() method.
137          *      @remarks        A secret key and an initial vector are set before calling this method.
138          */
139         virtual Tizen::Base::ByteBuffer* EncryptN(const Tizen::Base::ByteBuffer& input);
140
141         /**
142          *      Decrypts the data (single-part).
143          *
144          *      @since          2.0
145          *
146          *      @return         A pointer to the Tizen::Base::ByteBuffer class that contains the output, @n
147          *                              else @c null if an error occurs
148          *      @param[in]      input                                   An instance of Tizen::Base::ByteBuffer
149          *      @exception      E_SUCCESS                               The method is successful.
150          *      @exception      E_INVALID_ARG                   The specified instance of Tizen::Base::ByteBuffer is invalid or empty.
151          *      @exception      E_OUT_OF_MEMORY                 The memory is insufficient.
152          *      @exception      E_KEY_NOT_FOUND                 The specified key is not found.
153          *      @exception      E_INVALID_OPERATION             The specified cipher operation mode for this method is invalid.
154          *      @exception      E_OVERFLOW                              This operation has caused the memory to overflow.
155          *      @exception      E_SYSTEM                                A system error has occurred. @n
156          *                                                                              The method has failed to operate with the OpenSSL library, or
157          *                                                                              the Tizen::Base::ByteBuffer operation has failed.
158          *      @remarks        The specific error code can be accessed using the GetLastResult() method.
159          *      @remarks        A secret key and an initial vector are set before calling this method.
160          */
161         virtual Tizen::Base::ByteBuffer* DecryptN(const Tizen::Base::ByteBuffer& input);
162
163         /**
164          *      Initializes a multiple-part encryption or decryption operation.
165          *
166          *      @since          2.0
167          *
168          *      @return         An error code
169          *      @exception      E_SUCCESS                               The method is successful.
170          *      @exception      E_OUT_OF_MEMORY                 The memory is insufficient.
171          *      @exception      E_KEY_NOT_FOUND                 The specified key is not found.
172          *      @exception      E_INVALID_OPERATION             The specified cipher operation mode for this method is invalid.
173          *      @exception      E_SYSTEM                                A system error has occurred. @n
174          *                                                                              The method has failed to operate with the OpenSSL library.
175          *      @remarks        A secret key and an initial vector are set before calling this method.
176          */
177         virtual result Initialize(void);
178
179         /**
180          *      Updates a multiple-part encryption or decryption operation.
181          *
182          *      @since          2.0
183          *
184          *      @return         A pointer to the Tizen::Base::ByteBuffer class that contains the output, @n
185          *                              else @c null if an error occurs
186          *      @param[in]      input                                   An instance of Tizen::Base::ByteBuffer
187          *      @exception      E_SUCCESS                               The method is successful.
188          *      @exception      E_OUT_OF_MEMORY                 The memory is insufficient.
189          *      @exception      E_OVERFLOW                              This operation has caused the memory to overflow.
190          *      @exception      E_INVALID_ARG                   The specified instance of Tizen::Base::ByteBuffer is invalid or empty.
191          *      @exception      E_SYSTEM                                A system error has occurred. @n
192          *                                                                              The method has failed to operate with the OpenSSL library, or
193          *                                                                              the Tizen::Base::ByteBuffer operation has failed.
194          *      @remarks        The specific error code can be accessed using the GetLastResult() method.
195          */
196         virtual Tizen::Base::ByteBuffer* UpdateN(const Tizen::Base::ByteBuffer& input);
197
198         /**
199          *      Finalizes a multiple-part encryption or decryption operation.
200          *
201          *      @since          2.0
202          *
203          *      @return         A pointer to the Tizen::Base::ByteBuffer class that contains the output, @n
204          *                              else @c null if an error occurs
205          *      @exception      E_SUCCESS                               The method is successful.
206          *      @exception      E_OUT_OF_MEMORY                 The memory is insufficient.
207          *      @exception      E_OVERFLOW                              This operation has caused the memory to overflow.
208          *      @exception      E_SYSTEM                                A system error has occurred. @n
209          *                                                                              The method has failed to operate with the OpenSSL library, or
210          *                                                                              the Tizen::Base::ByteBuffer operation has failed.
211          *      @remarks        The specific error code can be accessed using the GetLastResult() method.
212          */
213         virtual Tizen::Base::ByteBuffer* FinalizeN(void);
214
215         /**
216          *      Wraps a key.
217          *
218          *      @since          2.0
219          *
220          *      @return         A pointer to the Tizen::Base::ByteBuffer class that contains the output, @n
221          *                              else @c null if an error occurs
222          *      @param[in]      secretKey                               The secret key to wrap
223          *      @remarks        This operation is not supported in the %Rc2Cipher class.
224          *                              Therefore, this method always returns @c null.
225          *      @remarks        The @c E_UNSUPPORTED_ALGORITHM exception is returned using the GetLastResult() method.
226          */
227         virtual Tizen::Base::ByteBuffer* WrapN(const Tizen::Base::ByteBuffer& secretKey);
228
229         /**
230          *      Unwraps a previously wrapped key.
231          *
232          *      @since          2.0
233          *
234          *      @return         A pointer to the Tizen::Base::ByteBuffer class that contains the output, @n
235          *                              else @c null if an error occurs
236          *      @param[in]      wrappedKey                              The wrapped key to unwrap
237          *      @remarks        This operation is not supported in the %Rc2Cipher class.
238          *                              Therefore, this method always returns @c null.
239          *      @remarks        The @c E_UNSUPPORTED_ALGORITHM exception is returned using the GetLastResult() method.
240          */
241         virtual Tizen::Base::ByteBuffer* UnwrapN(const Tizen::Base::ByteBuffer& wrappedKey);
242
243 private:
244
245         //
246         // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
247         //
248         // @since 2.0
249         //
250         Rc2Cipher(const Rc2Cipher& rhs);
251
252         //
253         // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
254         //
255         // @since 2.0
256         //
257         Rc2Cipher& operator =(const Rc2Cipher& rhs);
258
259 private:
260         _SymmetricCipher* __pSymmetricCipher;
261         const evp_cipher_st* __pCipherAlgorithm;
262         Tizen::Base::String __cipherAlgorithm;
263
264         class _Rc2CipherImpl* __pRc2CipherImpl;
265         friend class _Rc2CipherImpl;
266
267 }; //Rc2Cipher
268
269 } } } //Tizen::Security::Crypto
270
271 #endif //_FSEC_CRYPTO_RC2_CIPHER_H_