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 

    23 /**

    24  @file

    25  @publishedPartner

    26  @released

    27 */

    28 

    29 #ifndef __PBENCRYPTOR_H__

    30 #define __PBENCRYPTOR_H__

    31 

    32 #include "pbe.h"

    33 #include "padding.h"

    34 #include "msymmetriccipher.h"

    35 

    36 /**

    37  * Implements the password based encryption of elements.

    38  *

    39  * @see CPBEncryptElement

    40  * @since v7.0s

    41  */

    42 class CPBEncryptorElement : public CPBEncryptor

    43 	{

    44 public:

    45 	/**

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

    47 	 * key, and Initialization Vector (IV).

    48 	 *

    49 	 * @param aCipher	The encryption cipher

    50 	 * @param aKey		The encryption key

    51 	 * @param aIV		The Initialization Vector

    52 	 * @return			A pointer to the new CPBEncryptorElement object

    53 	 */

    54 	IMPORT_C static CPBEncryptorElement* NewL(TPBECipher aCipher, 

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

    56 

    57 	/**

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

    59 	 * key, and IV.

    60 	 * 

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

    62 	 *

    63 	 * @param aCipher	The encryption cipher

    64 	 * @param aKey		The encryption key

    65 	 * @param aIV		The Initialization Vector

    66 	 * @return			A pointer to the new CPBEncryptorElement object

    67 	 */

    68 	IMPORT_C static CPBEncryptorElement* NewLC(TPBECipher aCipher, 

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

    70 

    71 	/** 

    72 	 * Transforms aInput into its encrypted form, aOutput.

    73 	 *

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

    75 	 *

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

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

    78 	 *

    79 	 * @param aInput	The plaintext.

    80 	 * @param aOutput	The ciphertext.

    81 	 */

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

    83 

    84 	/** 

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

    86 	 * padding scheme to ensure a block aligned result.

    87 	 *

    88 	 * aOutput must have CPBEncryptorElement::MaxFinalOutputLength() 

    89 	 * empty bytes remaining in its length. 

    90 	 *

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

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

    93 	 * 

    94 	 * @param aInput	The plaintext.

    95 	 * @param aOutput	The ciphertext.

    96 	 */

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

    98 

    99 	/** 

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

   101 	 * given input length.

   102 	 *

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

   104 	 * @return					The maximum output length in bytes.

   105 	 */

   106 	TInt MaxOutputLength(TUint aMaxInputLength) const;

   107 

   108 	/** 

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

   110 	 * with a given input length.

   111 	 *

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

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

   114 	 */

   115 	TInt MaxFinalOutputLength(TUint aMaxInputLength) const;

   116 

   117 	/** Destructor */

   118 	virtual ~CPBEncryptorElement();

   119 protected:

   120 	/* @internalComponent */

   121 	CPBEncryptorElement();

   122 	/* @internalComponent */

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

   124 private:

   125 	CSymmetricCipher* iCipher;

   126 	};

   127 

   128 /**

   129  * Implements the password based decryption of elements.

   130  *

   131  * @since v7.0s

   132  */

   133 class CPBDecryptorElement : public CPBDecryptor

   134 	{

   135 public:

   136 	/**

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

   138 	 * key, and IV.

   139 	 *

   140 	 * @param aCipher	The decryption cipher

   141 	 * @param aKey		The decryption key

   142 	 * @param aIV		The Initialization Vector

   143 	 * @return			A pointer to the new CPBDecryptorElement object

   144 	 */

   145 	IMPORT_C static CPBDecryptorElement* NewL(const TPBECipher aCipher, 

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

   147 	

   148 	/**

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

   150 	 * key, and IV.

   151 	 * 

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

   153 	 *

   154 	 * @param aCipher	The decryption cipher

   155 	 * @param aKey		The decryption key

   156 	 * @param aIV		The Initialization Vector

   157 	 * @return			A pointer to the new CPBDecryptorElement object

   158 	 */

   159 	IMPORT_C static CPBDecryptorElement* NewLC(const TPBECipher aCipher, 

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

   161 

   162 	/** 

   163 	 * Transforms aInput into its decrypted form, aOutput.

   164 	 *

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

   166 	 * remaining in its length. 

   167 	 *

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

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

   170 	 * 

   171 	 * @param aInput	The ciphertext.

   172 	 * @param aOutput	The plaintext.

   173 	 */

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

   175 

   176 	/** 

   177 	 * Transforms aInput into its decrypted form, aOutput.

   178 	 *

   179 	 * aOutput must have CPBDecryptorElement::MaxFinalOutputLength() 

   180 	 * empty bytes remaining in its length. 

   181 	 * 

   182 	 * @param aInput	The ciphertext.

   183 	 * @param aOutput	The plaintext.

   184 	 */

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

   186 

   187 	/** 

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

   189 	 * 

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

   191 	 * @return					The maximum output length in bytes.

   192 	 */

   193 	TInt MaxOutputLength(TUint aMaxInputLength) const;

   194 

   195 	/** 

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

   197 	 * 

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

   199 	 * @return					The maximum output length in bytes.

   200 	 */

   201 	TInt MaxFinalOutputLength(TUint aMaxInputLength) const;

   202 

   203 	/** Destructor */

   204 	virtual ~CPBDecryptorElement();

   205 protected:

   206 	/* @internalComponent */

   207 	CPBDecryptorElement();

   208 	/* @internalComponent */

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

   210 private:

   211 	CSymmetricCipher* iCipher;

   212 	};

   213 

   214 /**

   215  * Implements the password based encryption of multiple elements.

   216  *

   217  * @see CPBEncryptSet

   218  * @since v7.0s

   219  */

   220 class CPBEncryptorSet : public CPBEncryptor

   221 	{

   222 public:

   223 	/**

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

   225 	 * and a random Initialization Vector (IV).

   226 	 *

   227 	 * @param aCipher	The encryption cipher

   228 	 * @param aKey		The encryption key

   229 	 * @return			A pointer to the new CPBEncryptorSet object

   230 	 */

   231 	IMPORT_C static CPBEncryptorSet* NewL(const TPBECipher aCipher, 

   232 		const TDesC8& aKey);

   233 

   234 	/**

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

   236 	 * and a random IV.

   237 	 * 

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

   239 	 *

   240 	 * @param aCipher	The encryption cipher

   241 	 * @param aKey		The encryption key

   242 	 * @return			A pointer to the new CPBEncryptorSet object

   243 	 */

   244 	IMPORT_C static CPBEncryptorSet* NewLC(const TPBECipher aCipher, 

   245 		const TDesC8& aKey);

   246 

   247 	/**

   248 	 * Resets the CPBEncryptorSet object back to its original state

   249 	 * and clears all its buffers.

   250 	 */

   251 	IMPORT_C void Reset(void);

   252 

   253 	/** 

   254 	 * Transforms aInput into its encrypted form, aOutput.

   255 	 *

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

   257 	 * remaining in its length. 

   258 	 *

   259 	 * @param aInput	The plaintext.

   260 	 * @param aOutput	The ciphertext.

   261 	 */

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

   263 

   264 	/** 

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

   266 	 * padding scheme to ensure a block aligned result.

   267 	 *

   268 	 * aOutput must have CPBEncryptorSet::MaxFinalOutputLength() 

   269 	 * empty bytes remaining in its length. 

   270 	 * 

   271 	 * @param aInput	The plaintext.

   272 	 * @param aOutput	The ciphertext.

   273 	 */

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

   275 

   276 	/** 

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

   278 	 * 

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

   280 	 * @return					The maximum output length in bytes.

   281 	 */

   282 	TInt MaxOutputLength(TUint aMaxInputLength) const;

   283 

   284 	/** 

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

   286 	 * 

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

   288 	 * @return					The maximum output length in bytes.

   289 	 */

   290 	TInt MaxFinalOutputLength(TUint aMaxInputLength) const;

   291 

   292 	/** Destructor */

   293 	virtual ~CPBEncryptorSet();

   294 protected:

   295 	/* @internalComponent */

   296 	CPBEncryptorSet();

   297 	/* @internalComponent */

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

   299 private:

   300 	CSymmetricCipher* iCipher;

   301 	HBufC8* iIV;

   302 	TBool iIVSent;

   303 	};

   304 

   305 

   306 /**

   307  * Implements the password based decryption of multiple elements.

   308  *

   309  * @since v7.0s

   310  */

   311 class CPBDecryptorSet : public CPBDecryptor

   312 	{

   313 public:

   314 	/**

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

   316 	 * and a random IV.

   317 	 *

   318 	 * @param aCipher	The decryption cipher

   319 	 * @param aKey		The decryption key

   320 	 * @return			A pointer to the new CPBDecryptorSet object

   321 	 */

   322 	IMPORT_C static CPBDecryptorSet* NewL(const TPBECipher aCipher, 

   323 		const TDesC8& aKey);

   324 

   325 	/**

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

   327 	 * and a random IV.

   328 	 * 

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

   330 	 *

   331 	 * @param aCipher	The decryption cipher

   332 	 * @param aKey		The decryption key

   333 	 * @return			A pointer to the new CPBDecryptorSet object

   334 	 */

   335 	IMPORT_C static CPBDecryptorSet* NewLC(const TPBECipher aCipher, 

   336 		const TDesC8& aKey);

   337 

   338 	/**

   339 	 * Resets the CPBDecryptorSet object back to its original state

   340 	 * and clears all its buffers.

   341 	 */

   342 	IMPORT_C void Reset(void);

   343 

   344 	/** 

   345 	 * Transforms aInput into its decrypted form, aOutput.

   346 	 *

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

   348 	 * remaining in its length. 

   349 	 *

   350 	 * @param aInput	The ciphertext.

   351 	 * @param aOutput	The plaintext.

   352 	 */

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

   354 

   355 	/** 

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

   357 	 * padding scheme to ensure a block aligned result.

   358 	 *

   359 	 * aOutput must have CPBDecryptorSet::MaxFinalOutputLength() 

   360 	 * empty bytes remaining in its length. 

   361 	 * 

   362 	 * @param aInput	The ciphertext.

   363 	 * @param aOutput	The plaintext.

   364 	 */

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

   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 MaxOutputLength(TUint aMaxInputLength) const;

   374 

   375 	/** 

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

   377 	 * 

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

   379 	 * @return					The maximum output length in bytes.

   380 	 */

   381 	TInt MaxFinalOutputLength(TUint aMaxInputLength) const;

   382 

   383 	/** Destructor */

   384 	virtual ~CPBDecryptorSet();

   385 protected:

   386 	/* @internalComponent */

   387 	CPBDecryptorSet();

   388 	/* @internalComponent */

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

   390 private:

   391 	TPtrC8 ProcessIV(const TDesC8& aInput);

   392 private:

   393 	CSymmetricCipher* iCipher;

   394 	HBufC8* iIVBuf;

   395 	TBool iIVSent;

   396 	};

   397 

   398 #endif