1 /*

     2 * Copyright (c) 2002-2009 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of the License "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description: 

    15 * ** IMPORTANT ** PublishedPartner API's in this file are published to 3rd party developers via the 

    16 * Symbian website. Changes to these API's should be treated as PublishedAll API changes and the Security TA should be consulted.

    17 *

    18 */

    19 

    20 

    21 /**

    22  @file

    23  @publishedPartner

    24  @released

    25 */

    26 

    27 #ifndef __PBENCRYPTOR_H__

    28 #define __PBENCRYPTOR_H__

    29 

    30 #include <pbe.h>

    31 #include <padding.h>

    32 #include <msymmetriccipher.h>

    33 

    34 /**

    35  * Implements the password based encryption of elements.

    36  *

    37  * @see CPBEncryptElement

    38  * @since v7.0s

    39  */

    40 class CPBEncryptorElement : public CPBEncryptor

    41 	{

    42 public:

    43 	/**

    44 	 * Creates a new CPBEncryptorElement object from the specified cipher, 

    45 	 * key, and Initialization Vector (IV).

    46 	 *

    47 	 * @param aCipher	The encryption cipher

    48 	 * @param aKey		The encryption key

    49 	 * @param aIV		The Initialization Vector

    50 	 * @return			A pointer to the new CPBEncryptorElement object

    51 	 */

    52 	IMPORT_C static CPBEncryptorElement* NewL(TPBECipher aCipher, 

    53 		const TDesC8& aKey, const TDesC8& aIV);

    54 

    55 	/**

    56 	 * Creates a new CPBEncryptorElement object from the specified cipher, 

    57 	 * key, and IV.

    58 	 * 

    59 	 * Puts a pointer to the returned object onto the cleanup stack.

    60 	 *

    61 	 * @param aCipher	The encryption cipher

    62 	 * @param aKey		The encryption key

    63 	 * @param aIV		The Initialization Vector

    64 	 * @return			A pointer to the new CPBEncryptorElement object

    65 	 */

    66 	IMPORT_C static CPBEncryptorElement* NewLC(TPBECipher aCipher, 

    67 		const TDesC8& aKey, const TDesC8& aIV);

    68 

    69 	/** 

    70 	 * Transforms aInput into its encrypted form, aOutput.

    71 	 *

    72 	 * aOutput must have CPBEncryptorElement::MaxOutputLength() empty bytes remaining in its length. 

    73 	 *

    74 	 *	See the Cryptography api-guide documentation for an explanation of

    75 	 *	how buffering of data supplied to this function is handled.

    76 	 *

    77 	 * @param aInput	The plaintext.

    78 	 * @param aOutput	The ciphertext.

    79 	 */

    80 	void Process(const TDesC8& aInput, TDes8& aOutput);

    81 

    82 	/** 

    83 	 * Transforms aInput into its encrypted form, aOutput, and applies a

    84 	 * padding scheme to ensure a block aligned result.

    85 	 *

    86 	 * aOutput must have CPBEncryptorElement::MaxFinalOutputLength() 

    87 	 * empty bytes remaining in its length. 

    88 	 *

    89 	 *	See the Cryptography api-guide documentation for an explanation of

    90 	 *	how buffering of data supplied to this function is handled.

    91 	 * 

    92 	 * @param aInput	The plaintext.

    93 	 * @param aOutput	The ciphertext.

    94 	 */

    95 	void ProcessFinalL(const TDesC8& aInput, TDes8& aOutput);

    96 

    97 	/** 

    98 	 * Gets the maximum size of the output resulting from calling Process() with a

    99 	 * given input length.

   100 	 *

   101 	 * @param aMaxInputLength	The maximum input length in bytes.

   102 	 * @return					The maximum output length in bytes.

   103 	 */

   104 	TInt MaxOutputLength(TUint aMaxInputLength) const;

   105 

   106 	/** 

   107 	 * Gets the maximum size of the output resulting from calling ProcessFinalL()

   108 	 * with a given input length.

   109 	 *

   110 	 * @param aMaxInputLength	The maximum input length in bytes.

   111 	 * @return					TInt The maximum output length in bytes.

   112 	 */

   113 	TInt MaxFinalOutputLength(TUint aMaxInputLength) const;

   114 

   115 	/** Destructor */

   116 	virtual ~CPBEncryptorElement();

   117 protected:

   118 	CPBEncryptorElement();

   119 	void ConstructL(TPBECipher aCipher, const TDesC8& aKey, const TDesC8& aIV);

   120 private:

   121 	CSymmetricCipher* iCipher;

   122 	};

   123 

   124 /**

   125  * Implements the password based decryption of elements.

   126  *

   127  * @since v7.0s

   128  */

   129 class CPBDecryptorElement : public CPBDecryptor

   130 	{

   131 public:

   132 	/**

   133 	 * Creates a new CPBDecryptorElement object from the specified cipher, 

   134 	 * key, and IV.

   135 	 *

   136 	 * @param aCipher	The decryption cipher

   137 	 * @param aKey		The decryption key

   138 	 * @param aIV		The Initialization Vector

   139 	 * @return			A pointer to the new CPBDecryptorElement object

   140 	 */

   141 	IMPORT_C static CPBDecryptorElement* NewL(const TPBECipher aCipher, 

   142 		const TDesC8& aKey, const TDesC8& aIV);

   143 	

   144 	/**

   145 	 * Creates a new CPBDecryptorElement object from the specified cipher, 

   146 	 * key, and IV.

   147 	 * 

   148 	 * Puts a pointer to the returned object onto the cleanup stack.

   149 	 *

   150 	 * @param aCipher	The decryption cipher

   151 	 * @param aKey		The decryption key

   152 	 * @param aIV		The Initialization Vector

   153 	 * @return			A pointer to the new CPBDecryptorElement object

   154 	 */

   155 	IMPORT_C static CPBDecryptorElement* NewLC(const TPBECipher aCipher, 

   156 		const TDesC8& aKey, const TDesC8& aIV);

   157 

   158 	/** 

   159 	 * Transforms aInput into its decrypted form, aOutput.

   160 	 *

   161 	 * aOutput must have CPBDecryptorElement::MaxOutputLength() empty bytes

   162 	 * remaining in its length. 

   163 	 *

   164 	 *	See the Cryptography api-guide documentation for an explanation of

   165 	 *	how buffering of data supplied to this function is handled.

   166 	 * 

   167 	 * @param aInput	The ciphertext.

   168 	 * @param aOutput	The plaintext.

   169 	 */

   170 	void Process(const TDesC8& aInput, TDes8& aOutput);

   171 

   172 	/** 

   173 	 * Transforms aInput into its decrypted form, aOutput.

   174 	 *

   175 	 * aOutput must have CPBDecryptorElement::MaxFinalOutputLength() 

   176 	 * empty bytes remaining in its length. 

   177 	 * 

   178 	 * @param aInput	The ciphertext.

   179 	 * @param aOutput	The plaintext.

   180 	 */

   181 	void ProcessFinalL(const TDesC8& aInput, TDes8& aOutput);

   182 

   183 	/** 

   184 	 * Gets the maximum size of the output given a certain input length.

   185 	 * 

   186 	 * @param aMaxInputLength	The maximum input length in bytes.

   187 	 * @return					The maximum output length in bytes.

   188 	 */

   189 	TInt MaxOutputLength(TUint aMaxInputLength) const;

   190 

   191 	/** 

   192 	 * Gets the maximum size of the output given a certain input length.

   193 	 * 

   194 	 * @param aMaxInputLength	The maximum input length in bytes.

   195 	 * @return					The maximum output length in bytes.

   196 	 */

   197 	TInt MaxFinalOutputLength(TUint aMaxInputLength) const;

   198 

   199 	/** Destructor */

   200 	virtual ~CPBDecryptorElement();

   201 protected:

   202 	CPBDecryptorElement();

   203 	void ConstructL(const TPBECipher aCipher, const TDesC8& aKey, const TDesC8& aIV);

   204 private:

   205 	CSymmetricCipher* iCipher;

   206 	};

   207 

   208 /**

   209  * Implements the password based encryption of multiple elements.

   210  *

   211  * @see CPBEncryptSet

   212  * @since v7.0s

   213  */

   214 class CPBEncryptorSet : public CPBEncryptor

   215 	{

   216 public:

   217 	/**

   218 	 * Creates a new CPBEncryptorSet object from the specified cipher and key,

   219 	 * and a random Initialization Vector (IV).

   220 	 *

   221 	 * @param aCipher	The encryption cipher

   222 	 * @param aKey		The encryption key

   223 	 * @return			A pointer to the new CPBEncryptorSet object

   224 	 */

   225 	IMPORT_C static CPBEncryptorSet* NewL(const TPBECipher aCipher, 

   226 		const TDesC8& aKey);

   227 

   228 	/**

   229 	 * Creates a new CPBEncryptorSet object from the specified cipher and key,

   230 	 * and a random IV.

   231 	 * 

   232 	 * Puts a pointer to the returned object onto the cleanup stack.

   233 	 *

   234 	 * @param aCipher	The encryption cipher

   235 	 * @param aKey		The encryption key

   236 	 * @return			A pointer to the new CPBEncryptorSet object

   237 	 */

   238 	IMPORT_C static CPBEncryptorSet* NewLC(const TPBECipher aCipher, 

   239 		const TDesC8& aKey);

   240 

   241 	/**

   242 	 * Resets the CPBEncryptorSet object back to its original state

   243 	 * and clears all its buffers.

   244 	 */

   245 	IMPORT_C void Reset(void);

   246 

   247 	/** 

   248 	 * Transforms aInput into its encrypted form, aOutput.

   249 	 *

   250 	 * aOutput must have CPBEncryptorSet::MaxOutputLength() empty bytes

   251 	 * remaining in its length. 

   252 	 *

   253 	 * @param aInput	The plaintext.

   254 	 * @param aOutput	The ciphertext.

   255 	 */

   256 	void Process(const TDesC8& aInput, TDes8& aOutput);

   257 

   258 	/** 

   259 	 * Transforms aInput into its encrypted form, aOutput, and applies a

   260 	 * padding scheme to ensure a block aligned result.

   261 	 *

   262 	 * aOutput must have CPBEncryptorSet::MaxFinalOutputLength() 

   263 	 * empty bytes remaining in its length. 

   264 	 * 

   265 	 * @param aInput	The plaintext.

   266 	 * @param aOutput	The ciphertext.

   267 	 */

   268 	void ProcessFinalL(const TDesC8& aInput, TDes8& aOutput);

   269 

   270 	/** 

   271 	 * Gets the maximum size of the output given a certain input length.

   272 	 * 

   273 	 * @param aMaxInputLength	The maximum input length in bytes.

   274 	 * @return					The maximum output length in bytes.

   275 	 */

   276 	TInt MaxOutputLength(TUint aMaxInputLength) const;

   277 

   278 	/** 

   279 	 * Gets the maximum size of the output given a certain input length.

   280 	 * 

   281 	 * @param aMaxInputLength	The maximum input length in bytes.

   282 	 * @return					The maximum output length in bytes.

   283 	 */

   284 	TInt MaxFinalOutputLength(TUint aMaxInputLength) const;

   285 

   286 	/** Destructor */

   287 	virtual ~CPBEncryptorSet();

   288 protected:

   289 	CPBEncryptorSet();

   290 	void ConstructL(TPBECipher aCipher, const TDesC8& aKey);

   291 private:

   292 	CSymmetricCipher* iCipher;

   293 	HBufC8* iIV;

   294 	TBool iIVSent;

   295 	};

   296 

   297 

   298 /**

   299  * Implements the password based decryption of multiple elements.

   300  *

   301  * @since v7.0s

   302  */

   303 class CPBDecryptorSet : public CPBDecryptor

   304 	{

   305 public:

   306 	/**

   307 	 * Creates a new CPBDecryptorSet object from the specified cipher and key,

   308 	 * and a random IV.

   309 	 *

   310 	 * @param aCipher	The decryption cipher

   311 	 * @param aKey		The decryption key

   312 	 * @return			A pointer to the new CPBDecryptorSet object

   313 	 */

   314 	IMPORT_C static CPBDecryptorSet* NewL(const TPBECipher aCipher, 

   315 		const TDesC8& aKey);

   316 

   317 	/**

   318 	 * Creates a new CPBDecryptorSet object from the specified cipher and key,

   319 	 * and a random IV.

   320 	 * 

   321 	 * Puts a pointer to the returned object onto the cleanup stack.

   322 	 *

   323 	 * @param aCipher	The decryption cipher

   324 	 * @param aKey		The decryption key

   325 	 * @return			A pointer to the new CPBDecryptorSet object

   326 	 */

   327 	IMPORT_C static CPBDecryptorSet* NewLC(const TPBECipher aCipher, 

   328 		const TDesC8& aKey);

   329 

   330 	/**

   331 	 * Resets the CPBDecryptorSet object back to its original state

   332 	 * and clears all its buffers.

   333 	 */

   334 	IMPORT_C void Reset(void);

   335 

   336 	/** 

   337 	 * Transforms aInput into its decrypted form, aOutput.

   338 	 *

   339 	 * aOutput must have CPBDecryptorSet::MaxOutputLength() empty bytes 

   340 	 * remaining in its length. 

   341 	 *

   342 	 * @param aInput	The ciphertext.

   343 	 * @param aOutput	The plaintext.

   344 	 */

   345 	void Process(const TDesC8& aInput, TDes8& aOutput);

   346 

   347 	/** 

   348 	 * Transforms aInput into its decrypted form, aOutput, and applies a

   349 	 * padding scheme to ensure a block aligned result.

   350 	 *

   351 	 * aOutput must have CPBDecryptorSet::MaxFinalOutputLength() 

   352 	 * empty bytes remaining in its length. 

   353 	 * 

   354 	 * @param aInput	The ciphertext.

   355 	 * @param aOutput	The plaintext.

   356 	 */

   357 	void ProcessFinalL(const TDesC8& aInput, TDes8& aOutput);

   358 

   359 	/** 

   360 	 * Gets the maximum size of the output given a certain input length.

   361 	 * 

   362 	 * @param aMaxInputLength	The maximum input length in bytes.

   363 	 * @return					The maximum output length in bytes.

   364 	 */

   365 	TInt MaxOutputLength(TUint aMaxInputLength) const;

   366 

   367 	/** 

   368 	 * Gets the maximum size of the output given a certain input length.

   369 	 * 

   370 	 * @param aMaxInputLength	The maximum input length in bytes.

   371 	 * @return					The maximum output length in bytes.

   372 	 */

   373 	TInt MaxFinalOutputLength(TUint aMaxInputLength) const;

   374 

   375 	/** Destructor */

   376 	virtual ~CPBDecryptorSet();

   377 protected:

   378 	CPBDecryptorSet();

   379 	void ConstructL(TPBECipher aCipher, const TDesC8& aKey, const TDesC8& aIV);

   380 private:

   381 	TPtrC8 ProcessIV(const TDesC8& aInput);

   382 private:

   383 	CSymmetricCipher* iCipher;

   384 	HBufC8* iIVBuf;

   385 	TBool iIVSent;

   386 	};

   387 

   388 #endif