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