1 /*

     2 * Copyright (c) 2003-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 * MCTKeystore.h

    16 *

    17 */

    18 

    19 

    20 

    21 

    22 /**

    23  @file 

    24  @internalTechnology

    25 */

    26  

    27 #ifndef __MCTKEYSTORE_H__

    28 #define __MCTKEYSTORE_H__

    29 

    30 #include <securitydefs.h>

    31 #include <mkeystore.h>

    32 #include <s32file.h>

    33 

    34 class MCTAuthenticationObject;

    35 

    36 /** The UID of the filekey store */

    37 const TInt KTokenTypeFileKeystore = 0x101F7333;

    38 

    39 /** The UID of a key store interface */

    40 const TInt KInterfaceKeyStore = 0x101F7334;

    41 

    42 /** The type ID of CCTKeyInfo objects */

    43 const TUid KKeyInfoUID = {0x101F5152};

    44 const TUid KRSARepudiableSignerUID = {0x101F7A3C};

    45 const TUid KDSARepudiableSignerUID = {0x101F7A3D};

    46 const TUid KPrivateDecryptorUID = {0x101F7A3E};

    47 const TUid KKeyAgreementUID = {0x101F7A3F};

    48 const TUid KNonRepudiationSignerUID = {0x101F7A40};

    49 const TUid KKeyStoreAuthObjectUID = {0x101FE681};

    50 

    51 /**

    52  * Defines the interface for a read-only key store token.

    53  *

    54  * All the details are defined in MKeyStore as they are shared by the unified

    55  * key store.

    56  * 

    57  * The class adds no extra member functions or data. 

    58  * 

    59  * @publishedPartner

    60  * @released

    61  */

    62 class MCTKeyStore : public MCTTokenInterface, public MKeyStore

    63 	{

    64 	};

    65 

    66 /**

    67  * Base class for CCTKeyInfo.

    68  *

    69  * @publishedPartner

    70  * @released

    71  */

    72 class CKeyInfoBase : protected CBase

    73 	{

    74 public:

    75 

    76 	/** Key algorithms. */

    77 	enum EKeyAlgorithm

    78 		{

    79 		EInvalidAlgorithm	= 0,

    80 		ERSA				= 1,

    81 		EDSA				= 2,

    82 		EDH					= 3

    83 		};

    84 

    85 	/** Flags for key access bitfield. */

    86 	enum EKeyAccess

    87 		{

    88 		EInvalidAccess		= 0x00,

    89 		ESensitive			= 0x01,

    90 		EExtractable		= 0x02,

    91 		EAlwaysSensitive	= 0x04,

    92 		ENeverExtractable	= 0x08,

    93 		ELocal				= 0x10

    94 		};

    95 

    96 public:

    97 	

    98 	inline TKeyIdentifier ID() const;						///< The ID (SHA-1 hash) of the key 

    99 	inline TKeyUsagePKCS15 Usage() const;					///< The key usage 

   100 	inline TUint Size() const;								///< The size of the key 

   101 	inline const TDesC& Label() const;						///< The key's label.

   102 	inline const TSecurityPolicy& UsePolicy() const; 		///< The security policy for key use 

   103 	inline const TSecurityPolicy& ManagementPolicy() const; ///< The security policy for key management 

   104 	inline EKeyAlgorithm Algorithm() const;					///< The key algorithm

   105 

   106 	/**

   107 	 * The key access type. The return code is bitfield made up of 0 or more

   108 	 * values from EKeyAccess ORed together.

   109 	 */

   110 	inline TInt AccessType() const;

   111 

   112 	/**

   113 	 * Returns whether the key is native.

   114 	 *

   115 	 * A native key is one where operations on the key are performed on the same

   116 	 * hardware as the the key is stored. For instance, if a key that is stored

   117 	 * on secure hardware but calculations are carried out on the main

   118 	 * processor, it isn't native.

   119 	 */

   120 	inline TBool Native() const;

   121 	

   122 	inline TTime StartDate() const;					///< The start time, or TTime(0) if not set

   123 	inline TTime EndDate() const;					///< The end time, or TTime(0) if not set

   124 	inline const TDesC8& PKCS8AttributeSet() const;	///< The PKCS#8 attribute set.

   125 

   126 	/**

   127 	 * Externalizes the key data to stream

   128 	 */

   129 	IMPORT_C void ExternalizeL(RWriteStream& aStream) const;

   130 

   131 public:

   132 

   133 	/**

   134 	 * Get the handle of the key.  This is a identifier that uniquely identifies

   135 	 * the key within one store, and is used to construct the token handle.

   136 	 */

   137 	inline TInt HandleID() const;

   138 

   139 	/**

   140 	 * Set the handle of the key.  Called by the token when a key is created.

   141 	 *

   142 	 * @param aHandle The new handle of the key

   143 	 */

   144 	inline void SetHandle(TInt aHandle);

   145 

   146 	/**

   147 	 * Called by the token when a key is created, to set the key identifier

   148 	 * (SHA-1 hash) of the new key

   149 	 *

   150 	 * @param aId The newly generated SHA-1 hash

   151 	 */

   152 	inline void SetIdentifier(TKeyIdentifier aId);

   153 

   154 	/**

   155 	 * Set the size of a key.

   156 	 */

   157 	inline void SetSize(TUint aSize);

   158 

   159 	/**

   160 	 * Set the key algorithm.

   161 	 */

   162 	inline void SetAlgorithm(EKeyAlgorithm aAlg);

   163 

   164 protected:

   165 

   166 	/**

   167 	 * Protected constructor, called by derived classes.

   168 	 */

   169 	IMPORT_C CKeyInfoBase(TKeyIdentifier aID,

   170 						  TKeyUsagePKCS15 aUsage,

   171 						  TUint aSize,

   172 						  HBufC* aLabel,

   173 						  TInt aHandle,

   174 						  const TSecurityPolicy& aUsePolicy,

   175 						  const TSecurityPolicy& aManagementPolicy,

   176 						  EKeyAlgorithm aAlgorithm,

   177 						  TInt aAccessType,

   178 						  TBool aNative,

   179 						  TTime aStartDate,

   180 						  TTime aEndDate,

   181 						  HBufC8* aPKCS8AttributeSet);

   182 

   183 	/**

   184 	 * Protected constructor, called by derived classes.

   185 	 */

   186 	IMPORT_C CKeyInfoBase();

   187 

   188 	/**

   189 	 * Second phase constructor.  Called by derived classes' NewL methods.

   190 	 */

   191 	IMPORT_C void ConstructL();

   192 

   193 	/**

   194 	 * Second phase constructor.  Called by derived classes' NewL methods.

   195 	 */

   196 	IMPORT_C void ConstructL(RReadStream& aIn);

   197 

   198 	/**

   199 	 * Destructor is protected so CCTKeyInfo can force users to call Release.

   200 	 */

   201 	IMPORT_C ~CKeyInfoBase();

   202 

   203 private:

   204 

   205 	/**

   206 	 * Internalizes key data from a stream.

   207 	 */

   208 	void InternalizeL(RReadStream& aStream);

   209 	

   210 protected:

   211 	TKeyIdentifier iID;					///< The ID of the key

   212 	TKeyUsagePKCS15 iUsage;				///< The usage of the key 

   213 	TUint iSize;						///< The size of the key 

   214 	HBufC* iLabel;						///< The identifying label of the key

   215 	TInt iHandle;						///< The handle of the key

   216 	TSecurityPolicy iUsePolicy;			///< The secutity policy for key use

   217 	TSecurityPolicy iManagementPolicy;	///< The secutity policy for key management

   218 	EKeyAlgorithm iAlgorithm;			///< The key type (RSA, DSA etc)

   219 	TInt iAccessType;					///< Key sensitivity

   220 	TBool iNative;						///< Key is native (cryptographic operations are carried out on the store)

   221 	TTime iStartDate;					///< Key Start Date 

   222 	TTime iEndDate;						///< Key end date 

   223 	HBufC8* iPKCS8AttributeSet;			///< Attributes as a DER-encoded set

   224 	};

   225 

   226 /**

   227  * Information about a key, as returned by MCTKeyStore::List.

   228  *

   229  * @publishedPartner

   230  * @released

   231  */

   232 class CCTKeyInfo : public CKeyInfoBase, public MCTTokenObject

   233 	{

   234 public:

   235 

   236 	/**

   237 	 * @internalTechnology

   238 	 * 

   239 	 * Creates a CCTKeyInfo from constituents.  This is called by the unified

   240 	 * key store, and should not be called directly.

   241 	 *

   242 	 * @param aID The SHA1 hash of the key

   243 	 * @param aUsage The usage of the key

   244 	 * @param aSize The size of the key in bytes

   245 	 * @param aProtector A protector object if the key is protected by a PIN.

   246 	 * This may be NULL if the protector is not known.

   247 	 * @param aLabel The label of the key (takes ownership).

   248 	 * @param aToken The token the key is in

   249 	 * @param aHandle The object ID part of the object handle; an

   250 	 * integer that is unique amongst keys in this token.

   251 	 * @param aUsePolicy The security policy for key use

   252 	 * @param aManagementPolicy The security policy for key management

   253 	 * @param aAlgorithm The key algorithm (RSA, DSA or Diffie-Hellman)

   254 	 * @param aAccessType The access type of the key

   255 	 * @param aNative	Defines whether the key is native

   256 	 * @param aStartDate The key validity start date

   257 	 * @param aEndDate The key validity end date

   258 	 * @param aPKCS8AttributeSet (optional) The DER encoded PKCS8 attribute set

   259 	 * (takes ownership).

   260 	 *

   261 	 * @leave KErrKeyUsage If the key usage flags are not valid or not

   262 	 * consistent with the key algorithm.

   263 	 * @leave KErrKeyValidity If the validity start and end dates are specified

   264 	 * but do not form a valid time period.

   265 	 */

   266 	IMPORT_C static CCTKeyInfo* NewL(TKeyIdentifier aID,

   267 									 TKeyUsagePKCS15 aUsage,

   268 									 TUint aSize,

   269 									 MCTAuthenticationObject* aProtector,

   270 									 HBufC* aLabel,

   271 									 MCTToken& aToken,

   272 									 TInt aHandle,

   273 									 const TSecurityPolicy& aUsePolicy,

   274 									 const TSecurityPolicy& aManagementPolicy,

   275 									 EKeyAlgorithm aAlgorithm,

   276 									 TInt aAccessType,

   277 									 TBool aNative,

   278 									 TTime aStartDate,

   279 									 TTime aEndDate,

   280 									 HBufC8* aPKCS8AttributeSet = NULL);

   281 

   282 	/**

   283 	 * Creates a new KeyInfo from a stream.

   284 	 *

   285 	 * @param aStream The stream to read the key data from

   286 	 * @param aToken The token that the key is in

   287 	 *

   288 	 * @leave KErrKeyUsage If the key usage flags are not valid or not

   289 	 * consistent with the key algorithm.

   290 	 * @leave KErrKeyValidity If the validity start and end dates are specified

   291 	 * but do not form a valid time period.

   292 	 */

   293 	IMPORT_C static CCTKeyInfo* NewL(RReadStream& aStream, MCTToken& aToken);

   294 

   295 public:

   296 

   297 	/**

   298 	 * The PIN (or other authentication object) that protects the key, or NULL

   299 	 * if not set.  This object is owned by key store.

   300 	 */

   301 	inline MCTAuthenticationObject* Protector() const;

   302 

   303 	/**

   304 	 * Sets the authentication object for this key.  The object's Release method

   305 	 * will be called by the destructor, allowing for refence counting of auth

   306 	 * objects to be implemented if desired.

   307 	 */

   308 	inline void SetProtector(MCTAuthenticationObject& aProtector);

   309 	

   310 	/** The CT handle to this object. */

   311 	inline operator TCTTokenObjectHandle() const;

   312 

   313 public:

   314 

   315 	// from MCTTokenObject

   316 

   317 	/** The label of the key */

   318  	virtual const TDesC& Label() const;

   319 

   320 	/** The token the key is in */

   321 	virtual MCTToken& Token() const;

   322 

   323 	/** Returns KKeyInfoUID to indicate this is a key info object */

   324 	virtual TUid Type() const;

   325 

   326 	/**

   327 	 * A handle for the key. This can be used to identify a key to

   328 	 * another process.

   329 	 */

   330 	virtual TCTTokenObjectHandle Handle() const;

   331 

   332 private:

   333 

   334 	CCTKeyInfo(TKeyIdentifier aID,

   335 			   TKeyUsagePKCS15 aUsage,

   336 			   TUint aSize,

   337 			   MCTAuthenticationObject* aProtector,

   338 			   HBufC* aLabel,

   339 			   MCTToken& aToken,

   340 			   TInt aHandle,

   341 			   const TSecurityPolicy& aUsePolicy,

   342 			   const TSecurityPolicy& aManagementPolicy,

   343 			   EKeyAlgorithm aAlgorithm,

   344 			   TInt aAccessType,

   345 			   TBool aNative,

   346 			   TTime aStartDate,

   347 			   TTime aEndDate,

   348 			   HBufC8* aPKCS8AttributeSet);

   349 

   350 	CCTKeyInfo(MCTToken& aToken);

   351 

   352 	~CCTKeyInfo();

   353 

   354 private:

   355 

   356 	/** The token the key is in*/

   357 	MCTToken& iToken;

   358 

   359 	/** The protector object of the key. This pointer is not owned by the class */

   360 	MCTAuthenticationObject* iProtector;

   361 };

   362 

   363 /**

   364  * A filter to specify which keys should be returned from the store by

   365  * MCTKeyStore::List.

   366  *

   367  * @publishedPartner

   368  * @released

   369  */

   370 struct TCTKeyAttributeFilter

   371 	{

   372 	enum TPolicyFilter

   373 		{

   374 		EAllKeys,

   375 		EUsableKeys,

   376 		EManageableKeys,

   377 		EUsableOrManageableKeys

   378 		};

   379 

   380 	/** Constructor */

   381 	IMPORT_C TCTKeyAttributeFilter();

   382 

   383 	/**

   384 	 * The hash of the key we're looking for. A zero-length descriptor means

   385 	 * 'don't care

   386 	 */

   387 	TKeyIdentifier iKeyId;

   388 

   389 	/**

   390 	 * The required usage of the key. A key must match any of the usages

   391 	 * specified. Use EAllUsages to return all usages.

   392 	 */

   393 	TKeyUsagePKCS15 iUsage;

   394 

   395 	/**

   396 	 * Filter returned keys by the operations the calling process is allowed to

   397 	 * perform on them (as determined by the security policies set on them).

   398 	 * 

   399 	 * The default is EUsableKeys.  Note that if this is to set to KAllKeys, all

   400 	 * keys will be returned, including those that are unusable by the calling

   401 	 * process.

   402 	 */

   403 	TPolicyFilter iPolicyFilter;

   404 

   405 	/** The algorithm. EInvalidAlgorithm indicates 'don't care */

   406 	CCTKeyInfo::EKeyAlgorithm iKeyAlgorithm;

   407 	};

   408 

   409 #include "mctkeystore.inl"

   410 

   411 #endif // __MCTKEYSTORE_H__