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 * Padding codes

    18 *

    19 */

    20 

    21 

    22 

    23 

    24 /**

    25  @file 

    26  @publishedPartner

    27  @released

    28 */

    29  

    30 #ifndef __PADDING_H__

    31 #define __PADDING_H__

    32 

    33 #include <random.h>

    34 /** 

    35 * Abstract base class defining the interface to padding schemes.

    36 *

    37 * It is designed to be used by both symmetric and asymmetric ciphers.

    38 *

    39 * @publishedPartner

    40 * @released

    41 */

    42 class CPadding : public CBase

    43 	{

    44 public:

    45 	/** 

    46 	* Pads aInput to be BlockSize() bytes long and places the result in aOutput.  

    47 	*

    48 	* @param aInput		Data to be padded.  The size must be less than or equal to

    49 	* 					BlockSize() minus MinPaddingLength().

    50 	* @param aOutput	On return, the resulting padded, block size aligned data

    51 	*					appended to aOutput.  

    52 	*/

    53 	IMPORT_C void PadL(const TDesC8& aInput,TDes8& aOutput);

    54 

    55 	/**

    56 	* Pads aInput to be BlockSize() long and places the result in aOutput.  

    57 	*

    58 	* Deriving implementations of DoPadL() can assume that aInput is less than or

    59 	* equal to BlockSize() minus MinPaddingLength().

    60 	*

    61 	* @param aInput		Data to be padded.  

    62 	* @param aOutput	On return, the resulting padded, aBlockBytes aligned data 

    63 	*					appended to aOutput.  

    64 	*/

    65 	virtual void DoPadL(const TDesC8& aInput,TDes8& aOutput) = 0;

    66 

    67 	/**

    68 	* Removes padding from aInput and appends unpadded result to aOutput.

    69 	* 

    70 	* @param aInput		Data to be unpadded.

    71 	* @param aOutput	On return, the unpadded data.

    72 	*/

    73 	virtual void UnPadL(const TDesC8& aInput,TDes8& aOutput) = 0;

    74 

    75 	/**

    76 	* Sets the block size for this padding system.

    77 	* 

    78 	* @param aBlockBytes	The block size in bytes.

    79 	*/

    80 	IMPORT_C void SetBlockSize(TInt aBlockBytes);

    81 

    82 	/**

    83 	* Retrieves the block size for this padding system.

    84 	*

    85 	* @return	The block size in bytes.

    86 	*/

    87 	IMPORT_C TInt BlockSize(void) const;

    88 

    89 	/**

    90 	* Gets the smallest number of bytes that PadL() will ever add to aInput in

    91 	* order to get a valid block aligned aOutput.  

    92 	*

    93 	* For example, in SSLv3 padding, if the block size is 8 and aInput is 7 bytes,

    94 	* it will append 1 byte of padding. For SSLv3 padding, this is the smallest 

    95 	* amount possible as an 8 byte input will add another block size (8 more bytes)

    96 	* of padded data.

    97 	* 

    98 	* @return	A TInt containing the smallest number of padding bytes possible.

    99 	*/

   100 	virtual TInt MinPaddingLength(void) const = 0;

   101 

   102 	/**

   103 	* Gets the size of the aOutput buffer, in a call to PadL(), must be in

   104 	* order to accommodate a block size of BlockSize() and an input size of

   105 	* aInputBytes.

   106 	* 

   107 	* @note	By default, this function returns the output of BlockSize().  If

   108 	*		a derived padding system outputs more than a single block of padding,

   109 	*		one must override this function and return the appropriate value.

   110 	*

   111 	* @param aInputBytes	The amount of data to be padded out in bytes.

   112 	* @return				A TInt representing the maximum amount of padded output data

   113 	*						(in bytes) for a given block and input size.

   114 	*/

   115 	IMPORT_C virtual TInt MaxPaddedLength(TInt aInputBytes) const;

   116 

   117 	/**

   118 	* Gets the size of the aOutput buffer, in a call to UnPadL(), must be in

   119 	* order to accommodate an input size of aInputBytes.

   120 	*

   121 	* @note	By default, this function returns the value of aInputBytes minus MinPaddingBytes().

   122 	*		Most padding systems cannot determine anything about the unpadded length

   123 	*		without looking at the data.  If your padding system allows you to give a

   124 	*		better bound, then you should reimplement this function.

   125 	*

   126 	* @param aInputBytes	The amount of data to be unpadded in bytes.

   127 	* @return				A TInt containing the maximum amount of unpadded output data

   128 	*						(in bytes) for a given padded input.

   129 	*/

   130 	IMPORT_C virtual TInt MaxUnPaddedLength(TInt aInputBytes) const;

   131 protected:

   132 	/** 

   133 	* Constructor

   134 	* 

   135 	* @param aBlockBytes	The block size in bytes.

   136 	*/

   137 	IMPORT_C CPadding(TInt aBlockBytes);

   138 private:

   139 	CPadding(void);

   140 	CPadding(const CPadding&);

   141 	CPadding& operator=(const CPadding&);

   142 private:

   143 	TInt iBlockBytes;

   144 	};

   145 

   146 /**

   147 * This concrete subclass of CPadding appends no padding.

   148 *

   149 * aOutput will be a copy of aInput after any call to PadL() or UnPadL().

   150 *

   151 * @publishedPartner

   152 * @released

   153 */

   154 class CPaddingNone:public CPadding

   155 	{

   156 public:

   157 	/**

   158 	* Creates a new CPaddingNone object.

   159 	*

   160 	* @param aBlockBytes	The block size in bytes.

   161 	* @return				A pointer to the new CPaddingNone object.

   162 	*/

   163 	IMPORT_C static CPaddingNone* NewL(TInt aBlockBytes=KMaxTInt);

   164 

   165 	/**

   166 	* Creates a new CPaddingNone object and leaves a pointer to it on the cleanup stack.

   167 	* 

   168 	* @param aBlockBytes	The block size in bytes.

   169 	* @return				A pointer to the new CPaddingNone object.

   170 	*/

   171 	IMPORT_C static CPaddingNone* NewLC(TInt aBlockBytes=KMaxTInt);

   172 	void DoPadL(const TDesC8& aInput,TDes8& aOutput);

   173 	void UnPadL(const TDesC8& aInput,TDes8& aOutput);

   174 	TInt MinPaddingLength(void) const;

   175 	TInt MaxPaddedLength(TInt aInputBytes) const;

   176 protected:

   177 	/** 

   178 	* Constructor

   179 	* 

   180 	* @param aBlockBytes	The block size in bytes.

   181 	*/

   182 	IMPORT_C CPaddingNone(TInt aBlockBytes);

   183 private:

   184 	CPaddingNone(void);

   185 	CPaddingNone(const CPaddingNone&);

   186 	CPaddingNone& operator=(const CPaddingNone&);

   187 	};

   188 

   189 /**

   190 * This concrete subclass of CPadding implements PKCS#1 v1.5 signature padding.

   191 *

   192 * It is intended for use with RSA signing/verifying.

   193 *

   194 * @publishedPartner

   195 * @released

   196 */

   197 class CPaddingPKCS1Signature : public CPadding

   198 	{

   199 public:

   200 	/**

   201 	* Creates a new CPaddingPKCS1Signature object.

   202 	*

   203 	* @param aBlockBytes	The block size in bytes.

   204 	* @return				A pointer to the new CPaddingPKCS1Signature object.

   205 	*/

   206 	IMPORT_C static CPaddingPKCS1Signature* NewL(TInt aBlockBytes);

   207 

   208 	/**

   209 	* Creates a new CPaddingPKCS1Signature object and leaves a pointer to it on the

   210 	* cleanup stack.

   211 	*

   212 	* @param aBlockBytes	The block size in bytes.

   213 	* @return				A pointer to the new CPaddingPKCS1Signature object.

   214 	*/

   215 	IMPORT_C static CPaddingPKCS1Signature* CPaddingPKCS1Signature::NewLC(

   216 		TInt aBlockBytes);

   217 	void DoPadL(const TDesC8& aInput,TDes8& aOutput);

   218 	void UnPadL(const TDesC8& aInput,TDes8& aOutput);

   219 	TInt MinPaddingLength(void) const;

   220 protected:

   221 	/** 

   222 	* Constructor

   223 	* 

   224 	* @param aBlockBytes	The block size in bytes.

   225 	*/

   226 	IMPORT_C CPaddingPKCS1Signature(TInt aBlockBytes);

   227 private:

   228 	CPaddingPKCS1Signature(void);

   229 	CPaddingPKCS1Signature(const CPaddingPKCS1Signature&);

   230 	CPaddingPKCS1Signature& operator=(const CPaddingPKCS1Signature&);

   231 	};

   232 

   233 /**

   234 * This concrete subclass of CPadding implements PKCS#1 v1.5 encryption padding.

   235 * It is intended for use with RSA encryption/decryption.

   236 *

   237 * @publishedPartner

   238 * @released

   239 */

   240 class CPaddingPKCS1Encryption : public CPadding

   241 	{

   242 public:

   243 	/**

   244 	* Creates a new CPaddingPKCS1Encryption object.

   245 	*

   246 	* @param aBlockBytes	The block size in bytes.

   247 	* @return				A pointer to the new CPaddingPKCS1Encryption object.

   248 	*/

   249 	IMPORT_C static CPaddingPKCS1Encryption* NewL(TInt aBlockBytes);

   250 

   251 	/**

   252 	* Creates a new CPaddingPKCS1Encryption object and leaves a pointer to it on the

   253 	* cleanup stack.

   254 	*

   255 	* @param aBlockBytes	The block size in bytes.

   256 	* @return				A pointer to the new CPaddingPKCS1Encryption object.

   257 	*/

   258 	IMPORT_C static CPaddingPKCS1Encryption* NewLC(TInt aBlockBytes);

   259 	void DoPadL(const TDesC8& aInput,TDes8& aOutput);

   260 	void UnPadL(const TDesC8& aInput,TDes8& aOutput);

   261 	TInt MinPaddingLength(void) const;

   262 protected:

   263 	/** 

   264 	* Constructor

   265 	* 

   266 	* @param aBlockBytes	The block size in bytes.

   267 	*/

   268 	IMPORT_C CPaddingPKCS1Encryption(TInt aBlockBytes);

   269 private:

   270 	CPaddingPKCS1Encryption(void);

   271 	CPaddingPKCS1Encryption(const CPaddingPKCS1Encryption&);

   272 	CPaddingPKCS1Encryption& operator=(const CPaddingPKCS1Encryption&);

   273 	};

   274 

   275 /**

   276 * This concrete subclass of CPadding implements padding according to 

   277 * the SSLv3/TLS standard.

   278 *

   279 * The SSL 3.0 spec does not specifiy the padding bytes to be used - it is

   280 * assumed to be arbitrary (and the openssl implementation uses non-zero random

   281 * data).  The TLS spec however states that padding bytes should be the length

   282 * of the padding - 1.  This class implements the latter when padding, but does

   283 * not check the padding byes when unpadding, so as to be interoperable with SSL

   284 * 3.0.

   285 * 

   286 * @publishedPartner

   287 * @released

   288 */

   289 class CPaddingSSLv3 : public CPadding

   290 	{

   291 public:

   292 	/**

   293 	* Creates a new CPaddingSSLv3 object.

   294 	*

   295 	* @param aBlockBytes	The block size in bytes.

   296 	* @return				A pointer to the new CPaddingSSLv3 object.

   297 	*/

   298 	IMPORT_C static CPaddingSSLv3* NewL(TInt aBlockBytes);

   299 

   300 	/**

   301 	* Creates a new CPaddingSSLv3 object and leaves a pointer to it on the cleanup stack.

   302 	*

   303 	* @param aBlockBytes	The block size in bytes.

   304 	* @return				A pointer to the new CPaddingSSLv3 object.

   305 	*/

   306 	IMPORT_C static CPaddingSSLv3* NewLC(TInt aBlockBytes);

   307 	void DoPadL(const TDesC8& aInput,TDes8& aOutput);

   308 	void UnPadL(const TDesC8& aInput,TDes8& aOutput);

   309 	TInt MinPaddingLength(void) const;

   310 	TInt MaxPaddedLength(TInt aInputBytes) const;

   311 

   312 protected:

   313 	/** 

   314 	* Constructor

   315 	* 

   316 	* @param aBlockBytes	The block size in bytes.

   317 	*/

   318 	IMPORT_C CPaddingSSLv3(TInt aBlockBytes);

   319 private:

   320 	CPaddingSSLv3(void);

   321 	CPaddingSSLv3(const CPaddingSSLv3&);

   322 	CPaddingSSLv3& operator=(const CPaddingSSLv3&);

   323 	};

   324 

   325 /**

   326 * This concrete subclass of CPadding implements padding according to 

   327 * the PKCS#7/TLS standard.

   328 *

   329 * @publishedPartner

   330 * @released

   331 */

   332 class CPaddingPKCS7 : public CPadding

   333 	{

   334 public:

   335 	/**

   336 	* Creates a new CPaddingPKCS7 object.

   337 	* 

   338 	* @param aBlockBytes	The block size in bytes.

   339 	* @return				A pointer to the new CPaddingPKCS7 object.

   340 	*/

   341 	IMPORT_C static CPaddingPKCS7* NewL(TInt aBlockBytes);

   342 

   343 	/**

   344 	* Creates a new CPaddingPKCS7 object and leaves a pointer to it on the cleanup stack.

   345 	*

   346 	* @param aBlockBytes	The block size in bytes.

   347 	* @return				A pointer to the new CPaddingPKCS7 object.

   348 	*/

   349 	IMPORT_C static CPaddingPKCS7* NewLC(TInt aBlockBytes);

   350 	void DoPadL(const TDesC8& aInput,TDes8& aOutput);

   351 	void UnPadL(const TDesC8& aInput,TDes8& aOutput);

   352 	TInt MinPaddingLength(void) const;

   353 	TInt MaxPaddedLength(TInt aInputBytes) const;

   354 

   355 protected:

   356 	/** 

   357 	* Constructor

   358 	* 

   359 	* @param aBlockBytes	The block size in bytes.

   360 	*/

   361 	IMPORT_C CPaddingPKCS7(TInt aBlockBytes);

   362 private:

   363 	CPaddingPKCS7(void);

   364 	CPaddingPKCS7(const CPaddingPKCS7&);

   365 	CPaddingPKCS7& operator=(const CPaddingPKCS7&);

   366 	};

   367 

   368 #endif