crypto/weakcryptospi/inc/pbencryptor.h
changeset 8 35751d3474b7
equal deleted inserted replaced
2:675a964f4eb5 8:35751d3474b7
       
     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