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 **  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  @file 

    24  @publishedAll

    25  @released

    26 */

    27  

    28 #ifndef __PADDING_H__

    29 #define __PADDING_H__

    30 

    31 #include <random.h>

    32 /** 

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

    34 *

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

    36 *

    37 */

    38 class CPadding : public CBase

    39 	{

    40 public:

    41 	/** 

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

    43 	*

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

    45 	* 					BlockSize() minus MinPaddingLength().

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

    47 	*					appended to aOutput.  

    48 	*/

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

    50 

    51 	

    52 	/**

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

    54 	* 

    55 	* @param aInput		Data to be unpadded.

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

    57 	*/

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

    59 

    60 	/**

    61 	* Sets the block size for this padding system.

    62 	* 

    63 	* @param aBlockBytes	The block size in bytes.

    64 	*/

    65 	IMPORT_C void SetBlockSize(TInt aBlockBytes);

    66 

    67 	/**

    68 	* Retrieves the block size for this padding system.

    69 	*

    70 	* @return	The block size in bytes.

    71 	*/

    72 	IMPORT_C TInt BlockSize(void) const;

    73 

    74 	/**

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

    76 	* order to get a valid block aligned aOutput.  

    77 	*

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

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

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

    81 	* of padded data.

    82 	* 

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

    84 	*/

    85 	virtual TInt MinPaddingLength(void) const = 0;

    86 

    87 	/**

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

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

    90 	* aInputBytes.

    91 	* 

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

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

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

    95 	*

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

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

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

    99 	*/

   100 	IMPORT_C virtual TInt MaxPaddedLength(TInt aInputBytes) const;

   101 

   102 	/**

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

   104 	* order to accommodate an input size of aInputBytes.

   105 	*

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

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

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

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

   110 	*

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

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

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

   114 	*/

   115 	IMPORT_C virtual TInt MaxUnPaddedLength(TInt aInputBytes) const;

   116 	

   117 	/**

   118 	@internalComponent

   119 	Used to retrieve the extended interfaces by id. For Crypto

   120 	SPI internal use only.

   121 	*/		

   122 	TInt GetExtension(TUint aExtensionId, TAny*& a0, TAny* a1);		

   123 	

   124 protected:

   125 	/** 

   126 	* Constructor

   127 	* 

   128 	* @param aBlockBytes	The block size in bytes.

   129 	*/

   130 	IMPORT_C CPadding(TInt aBlockBytes);

   131 private:

   132 	CPadding(void);

   133 	CPadding(const CPadding&);

   134 	CPadding& operator=(const CPadding&);

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

   136 private:

   137 	TInt iBlockBytes;

   138 	};

   139 

   140 /**

   141 * This concrete subclass of CPadding appends no padding.

   142 *

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

   144 *

   145 */

   146 class CPaddingNone:public CPadding

   147 	{

   148 public:

   149 	/**

   150 	* Creates a new CPaddingNone object.

   151 	*

   152 	* @param aBlockBytes	The block size in bytes.

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

   154 	*/

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

   156 

   157 	/**

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

   159 	* 

   160 	* @param aBlockBytes	The block size in bytes.

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

   162 	*/

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

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

   165 	TInt MinPaddingLength(void) const;

   166 	TInt MaxPaddedLength(TInt aInputBytes) const;

   167 protected:

   168 	/** 

   169 	* Constructor

   170 	* 

   171 	* @param aBlockBytes	The block size in bytes.

   172 	*/

   173 	IMPORT_C CPaddingNone(TInt aBlockBytes);

   174 private:

   175 	CPaddingNone(void);

   176 	CPaddingNone(const CPaddingNone&);

   177 	CPaddingNone& operator=(const CPaddingNone&);

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

   179 	};

   180 

   181 /**

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

   183 *

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

   185 *

   186 */

   187 class CPaddingPKCS1Signature : public CPadding

   188 	{

   189 public:

   190 	/**

   191 	* Creates a new CPaddingPKCS1Signature object.

   192 	*

   193 	* @param aBlockBytes	The block size in bytes.

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

   195 	*/

   196 	IMPORT_C static CPaddingPKCS1Signature* NewL(TInt aBlockBytes);

   197 

   198 	/**

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

   200 	* cleanup stack.

   201 	*

   202 	* @param aBlockBytes	The block size in bytes.

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

   204 	*/

   205 	IMPORT_C static CPaddingPKCS1Signature* CPaddingPKCS1Signature::NewLC(

   206 		TInt aBlockBytes);

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

   208 	TInt MinPaddingLength(void) const;

   209 protected:

   210 	/** 

   211 	* Constructor

   212 	* 

   213 	* @param aBlockBytes	The block size in bytes.

   214 	*/

   215 	IMPORT_C CPaddingPKCS1Signature(TInt aBlockBytes);

   216 private:

   217 	CPaddingPKCS1Signature(void);

   218 	CPaddingPKCS1Signature(const CPaddingPKCS1Signature&);

   219 	CPaddingPKCS1Signature& operator=(const CPaddingPKCS1Signature&);

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

   221 	};

   222 

   223 /**

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

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

   226 *

   227 */

   228 class CPaddingPKCS1Encryption : public CPadding

   229 	{

   230 public:

   231 	/**

   232 	* Creates a new CPaddingPKCS1Encryption object.

   233 	*

   234 	* @param aBlockBytes	The block size in bytes.

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

   236 	*/

   237 	IMPORT_C static CPaddingPKCS1Encryption* NewL(TInt aBlockBytes);

   238 

   239 	/**

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

   241 	* cleanup stack.

   242 	*

   243 	* @param aBlockBytes	The block size in bytes.

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

   245 	*/

   246 	IMPORT_C static CPaddingPKCS1Encryption* NewLC(TInt aBlockBytes);

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

   248 	TInt MinPaddingLength(void) const;

   249 protected:

   250 	/** 

   251 	* Constructor

   252 	* 

   253 	* @param aBlockBytes	The block size in bytes.

   254 	*/

   255 	IMPORT_C CPaddingPKCS1Encryption(TInt aBlockBytes);

   256 private:

   257 	CPaddingPKCS1Encryption(void);

   258 	CPaddingPKCS1Encryption(const CPaddingPKCS1Encryption&);

   259 	CPaddingPKCS1Encryption& operator=(const CPaddingPKCS1Encryption&);

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

   261 	};

   262 

   263 /**

   264 * This concrete subclass of CPadding implements padding according to 

   265 * the SSLv3/TLS standard.

   266 *

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

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

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

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

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

   272 * 3.0.

   273 * 

   274 */

   275 class CPaddingSSLv3 : public CPadding

   276 	{

   277 public:

   278 	/**

   279 	* Creates a new CPaddingSSLv3 object.

   280 	*

   281 	* @param aBlockBytes	The block size in bytes.

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

   283 	*/

   284 	IMPORT_C static CPaddingSSLv3* NewL(TInt aBlockBytes);

   285 

   286 	/**

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

   288 	*

   289 	* @param aBlockBytes	The block size in bytes.

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

   291 	*/

   292 	IMPORT_C static CPaddingSSLv3* NewLC(TInt aBlockBytes);

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

   294 	TInt MinPaddingLength(void) const;

   295 	TInt MaxPaddedLength(TInt aInputBytes) const;

   296 

   297 protected:

   298 	/** 

   299 	* Constructor

   300 	* 

   301 	* @param aBlockBytes	The block size in bytes.

   302 	*/

   303 	IMPORT_C CPaddingSSLv3(TInt aBlockBytes);

   304 private:

   305 	CPaddingSSLv3(void);

   306 	CPaddingSSLv3(const CPaddingSSLv3&);

   307 	CPaddingSSLv3& operator=(const CPaddingSSLv3&);

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

   309 	};

   310 

   311 /**

   312 * This concrete subclass of CPadding implements padding according to 

   313 * the PKCS#7/TLS standard.

   314 *

   315 */

   316 class CPaddingPKCS7 : public CPadding

   317 	{

   318 public:

   319 	/**

   320 	* Creates a new CPaddingPKCS7 object.

   321 	* 

   322 	* @param aBlockBytes	The block size in bytes.

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

   324 	*/

   325 	IMPORT_C static CPaddingPKCS7* NewL(TInt aBlockBytes);

   326 

   327 	/**

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

   329 	*

   330 	* @param aBlockBytes	The block size in bytes.

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

   332 	*/

   333 	IMPORT_C static CPaddingPKCS7* NewLC(TInt aBlockBytes);

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

   335 	TInt MinPaddingLength(void) const;

   336 	TInt MaxPaddedLength(TInt aInputBytes) const;

   337 

   338 protected:

   339 	/** 

   340 	* Constructor

   341 	* 

   342 	* @param aBlockBytes	The block size in bytes.

   343 	*/

   344 	IMPORT_C CPaddingPKCS7(TInt aBlockBytes);

   345 private:

   346 	CPaddingPKCS7(void);

   347 	CPaddingPKCS7(const CPaddingPKCS7&);

   348 	CPaddingPKCS7& operator=(const CPaddingPKCS7&);

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

   350 	};

   351 

   352 #endif