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 __PKCS5KDF_H__

    30 #define __PKCS5KDF_H__

    31 

    32 #include <hash.h>

    33 

    34 /** The number of times the hashing algorithm is run. */

    35 const TUint KDefaultIterations = 1000;

    36 

    37 /**

    38  * A PKCS#5 compliant Key Derivation Function (KDF).

    39  *

    40  * This class allows the derivation of deterministic arbitrary length byte 

    41  * streams from an input string. The output byte stream is generated using 

    42  * multiple iterations of a CSHA1 message digest and is suitable for use 

    43  * as a cryptographic symmetric key.

    44  *

    45  * @since v7.0s

    46  */

    47 class TPKCS5KDF

    48 	{

    49 public:

    50 	/** 

    51 	 * Derives deterministic arbitrary length byte streams (aKey) from an input

    52 	 * string (aPasswd) and a randomly chosen salt (aSalt) for use as a

    53 	 * symmetric key.

    54 	 *

    55 	 * Attention -- Improperly chosen values for these parameters will seriously

    56 	 * impact the security of the derived key and as a result the security of 

    57 	 * your application. 

    58 	 *

    59 	 * See the Cryptography api-guide documentation for more information and 

    60 	 * recommended usage patterns.

    61 	 * 

    62 	 * @param aKey			Output Value. The key resulting from the operation.

    63 	 * 						The length of the key will be equal to the length of

    64 	 * 						the input descriptor. All data, from the first byte 

    65 	 * 						to the set length, will be overwritten with the resulting

    66 	 *						byte stream.

    67 	 * @param aPasswd		Input Value. The password you wish to derive a key from.

    68 	 * @param aSalt			Input Value. A <B><I>randomly</I></B> selected second

    69 	 * 						input to the key derivation function to discourage certain

    70 	 * 						attacks. PKCS5 recommends a minimum of 8 randomly chosen bytes.

    71 	 * @param aIterations	Input Value. The number of times the internal hashing

    72 	 * 						function should be run over the password and salt.

    73 	 *						Minimum recommendation is KDefaultIterations.

    74 	 */

    75 	IMPORT_C static void DeriveKeyL(TDes8& aKey, const TDesC8& aPasswd, 

    76 		const TDesC8& aSalt, TUint aIterations = KDefaultIterations);

    77 private:

    78 	/** 

    79 	 * Internal iterative function that performs the actual hashing. 

    80 	 */

    81 	static void F(CMessageDigest& aDigest, TUint32* aAccumulator, TUint32* S,

    82 	TUint32* Ui, TUint aHashBytes, const TUint32* aSalt, TUint aSaltBytes, 

    83 	TUint c, TUint i);

    84 	

    85 	/** 

    86 	 * XOR's the values of two equal length descriptors.  Internally, it

    87 	 * operates on a word by word basis.  Data stored beyond the end of the

    88 	 * descriptor, but before the end of the final word, will be xored as well.

    89 	 */

    90 	static inline void XORString(const TUint32* aOp1, TUint32* aOp2,

    91 		TUint aLength);

    92 	};

    93 

    94 #endif