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 * MKeystore.h

    16 *

    17 */

    18 

    19 

    20 

    21 

    22 /**

    23  @file 

    24  @internalTechnology

    25 */

    26  

    27 #ifndef __MKEYSTORE_H__

    28 #define __MKEYSTORE_H__

    29 

    30 #include <ct.h>

    31 

    32 class CDSASignature;

    33 class CRSASignature;

    34 class CDHParameters;

    35 class CDHPublicKey;

    36 class TInteger;

    37 

    38 class CCTKeyInfo;

    39 struct TCTKeyAttributeFilter;

    40 

    41 /**

    42  * A template for signer objects.  It isn't possible to use a base class as the

    43  * signature objects created are not related.

    44  *

    45  * This template is be instantiated with a CRSASignature* as the

    46  * signature class for RSA signatures and with a CDSASignature* as the Signature

    47  * for DSA.

    48  * 

    49  * @publishedPartner

    50  * @released

    51  */

    52 template <class Signature> class MCTSigner : public MCTTokenObject

    53 	{

    54  public:

    55 	/**

    56 	 * Sign some data.

    57 	 * 

    58 	 * The data is hashed before the signature is created using the SHA-1

    59 	 * algorithm.

    60 	 * 

    61 	 * @param aPlaintext The string to be signed.

    62 	 * @param aSignature The returned signature.  A new signature object is

    63 	 *     created which is owned by the caller.

    64 	 *     

    65 	 * @capability Dependent Requires the caller to have any capabilities specified in the

    66 	 *     key use security policy.

    67 	 * @leave KErrPermissionDenied If the caller does not conform to the key use

    68 	 *     security policy.

    69 	 * @leave KErrBadPassphrase If the user failed to enter the correct passphrase.

    70 	 */

    71 	virtual void SignMessage(const TDesC8& aPlaintext, Signature& aSignature, 

    72 							 TRequestStatus& aStatus) = 0;

    73 

    74 	/**

    75 	 * Perform a raw signing operation.

    76 	 *	

    77 	 * @param aPlaintext The string to be signed - this should be some form of

    78 	 *     hash of the actual message to be signed.   In order to generate valid PKCS#1 v1.5 signature 

    79 	 *     aPlainText should consist of ASN.1 encoded digest algorithm ID and hash as described in RFC2313.

    80 	 *     If the data is too long,  this method will return KErrOverflow through aStatus.

    81 	 * @param aSignature The returned signature.  A new signature object is

    82 	 *     created which is owned by the caller.

    83 	 * @capability Dependent Requires the caller to have any capabilities specified in the

    84 	 *     key use security policy.

    85 	 * @leave KErrPermissionDenied If the caller does not conform to the key use

    86 	 *     security policy.

    87 	 * @leave KErrBadPassphrase If the user failed to enter the correct passphrase.

    88 	 */

    89 	virtual void Sign(const TDesC8& aPlaintext, Signature& aSignature, 

    90 					  TRequestStatus& aStatus) = 0;

    91 

    92 	/** Cancel an ongoing Sign() or SignMessage() operation. */

    93 	virtual void CancelSign() = 0;

    94 	

    95  protected:

    96 	inline MCTSigner(MCTToken& aToken);

    97 	virtual ~MCTSigner() = 0;

    98 	};

    99 

   100 /**

   101  * An RSA signer object.

   102  * 

   103  * @publishedPartner

   104  * @released

   105  */

   106 typedef MCTSigner<CRSASignature*> MRSASigner;

   107 

   108 /**

   109  * A DSA signer object.

   110  * 

   111  * @publishedPartner

   112  * @released

   113  */

   114 typedef MCTSigner<CDSASignature*> MDSASigner; 

   115 

   116 /**

   117  * A Decryptor. To do a private decrypt, you need to get one of these

   118  * objects.

   119  * 

   120  * @publishedPartner

   121  * @released

   122  */

   123 class MCTDecryptor : public MCTTokenObject

   124 	{

   125  public:

   126 	/**

   127 	 * Do a private decrypt.

   128 	 * 

   129 	 * @param aCiphertext The data to decrypt

   130 	 * @param aPlaintext The returned plaintext

   131 	 * @capability Dependent Requires the caller to have any capabilities specified in the

   132 	 *     key use security policy.

   133 	 * @leave KErrPermissionDenied If the caller does not conform to the key use

   134 	 *     security policy.

   135 	 * @leave KErrBadPassphrase If the user failed to enter the correct passphrase.

   136 	 */

   137 	virtual void Decrypt(const TDesC8& aCiphertext, TDes8& aPlaintext,

   138 				 TRequestStatus& aStatus) = 0;

   139 	

   140 	/** Cancel an ongoing Decrypt() operation. */

   141 	virtual void CancelDecrypt() = 0;

   142 	

   143  protected:

   144 	inline MCTDecryptor(MCTToken& aToken);

   145 	inline virtual ~MCTDecryptor() = 0;

   146 	};

   147 

   148 /**

   149  * A Diffie-Hellman key agreement object.

   150  * 

   151  * @publishedPartner

   152  * @released

   153  */

   154 class MCTDH : public MCTTokenObject

   155 	{

   156  public:

   157 	/**

   158 	 * Returns the public key ('Big X') for the supplied set of parameters.

   159 	 * 

   160 	 * @param aN The DH modulus parameter.

   161 	 * @param aG The DH generator parameter.

   162 	 * @param aX The returned public key.  A new object is created which is

   163 	 *     owned by the caller.

   164 	 * @capability Dependent Requires the caller to have any capabilities specified in the

   165 	 *     key use security policy.

   166 	 * @leave KErrPermissionDenied If the caller does not conform to the key use

   167 	 *     security policy.

   168 	 * @leave KErrBadPassphrase If the user failed to enter the correct passphrase.

   169 	 */

   170 	virtual void PublicKey(const TInteger& aN, const TInteger& aG, 

   171 						   CDHPublicKey*& aX,

   172 						   TRequestStatus& aStatus) = 0;

   173 	

   174 	/**

   175 	 * Agrees a session key.

   176 	 * 

   177 	 * @param aY The public key of the other party.

   178 	 * @param aAgreedKey The returned key.  A new object is created which is

   179 	 * owned by the caller.

   180 	 * @capability Dependent Requires the caller to have any capabilities specified in the

   181 	 *     key use security policy.

   182 	 * @leave KErrPermissionDenied If the caller does not conform to the key use

   183 	 *     security policy.

   184 	 * @leave KErrBadPassphrase If the user failed to enter the correct passphrase.

   185 	 */

   186 	virtual void Agree(const CDHPublicKey& aY,

   187 					   HBufC8*& aAgreedKey,

   188 					   TRequestStatus& aStatus) = 0;

   189 	

   190 	/** Cancels either a PublicKey() or Agree() operation */

   191 	virtual void CancelAgreement() = 0;

   192 	

   193  protected:

   194 	inline MCTDH(MCTToken& aToken);

   195 	inline virtual ~MCTDH() = 0;

   196 	};

   197 

   198 /**

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

   200  *

   201  * This prvides the API for the client to query the keys and open objects

   202  * allowing crypto operations to be performed.

   203  *

   204  * This documentation describes the security policy that must be enforced by

   205  * implementations of the interface.

   206  * 

   207  * @publishedPartner

   208  * @released

   209  */

   210 class MKeyStore

   211 	{

   212 public:

   213 	/**

   214 	 * Listing keys

   215 	 */

   216 	

   217 	/** 

   218 	 * List all the keys in the store that match the filter.

   219 	 *

   220 	 * @param aKeys An array to which the returned keys are appended

   221 	 * @param aFilter a filter controlling which keys are returned

   222 	 * @param aStatus This will be completed with the final status code

   223 	 * @capability ReadUserData requires the caller to have ReadUserData capability

   224 	 * @leave KErrPermissionDenied if the caller does not have ReadUserData capability

   225 	 */

   226 	virtual void List(RMPointerArray<CCTKeyInfo>& aKeys, 

   227 					  const TCTKeyAttributeFilter& aFilter, 

   228 					  TRequestStatus& aStatus) = 0;

   229 	

   230 	/** Cancel an ongoing List() operation */

   231 	virtual void CancelList() = 0;

   232 			

   233 	/**

   234 	 * Getting a key given a TCTTokenObjectHandle

   235 	 */

   236 	 

   237 	/**

   238 	 * Retrieves a key given its handle.

   239 	 * 

   240 	 * @param aHandle The handle of the required key

   241 	 * @param aInfo The returned key info

   242 	 * @param aStatus Async request notification

   243 	 * @capability Dependent Requires the caller to have any capabilities specified in the

   244 	 *     key use security policy.

   245 	 * @leave KErrPermissionDenied If the caller does not conform to the key use

   246 	 *     security policy.

   247 	 * @leave KErrNotFound If the key the handle referes to does not exist. 

   248 	 */

   249 	virtual void GetKeyInfo(TCTTokenObjectHandle aHandle, CCTKeyInfo*& aInfo,

   250 							TRequestStatus& aStatus) = 0;

   251 	

   252 	/** Cancel an ongoing GetKeyInfo() operation */

   253 	virtual void CancelGetKeyInfo() = 0;

   254 	

   255 	/**

   256 	 * Opening keys

   257 	 */

   258 	

   259 	/**

   260 	 * Open an RSA key for signing

   261 	 * 

   262 	 * @param aHandle The handle of the key to be opened.  This must be the

   263 	 *     handle of an RSA key on this store that is usable for signing by

   264 	 *     this process or the operation will fail.

   265 	 * @param aSigner The returned signer object.

   266 	 * @param aStatus Asynchronous request notification.

   267 	 * @capability Dependent Requires the caller to have any capabilities specified in the

   268 	 *     key use security policy.

   269 	 * @leave KErrPermissionDenied If the caller does not conform to the key use

   270 	 *     security policy.

   271 	 * @leave KErrNotFound If the key the handle referes to does not exist.

   272 	 * @leave KErrKeyAlgorithm If the key is not an RSA key.

   273 	 * @leave KErrKeyUsage If the key doesn't have sign usage.

   274 	 * @leave KErrKeyValidity If the key is not currently valid.

   275 	 */

   276 	virtual void Open(const TCTTokenObjectHandle& aHandle, 

   277 					  MRSASigner*& aSigner,

   278 					  TRequestStatus& aStatus) = 0;

   279 	

   280 	/**

   281 	 * Open a DSA key for signing

   282 	 * 

   283 	 * @param aHandle The handle of the key to be opened.  This must be the

   284 	 *     handle of a DSA key on this store that is usable by this process

   285 	 *     for signing or the operation will fail.

   286 	 * @param aSigner The returned signer object

   287 	 * @param aStatus Asynchronous request notification.

   288 	 * 

   289 	 * @capability Dependent Requires the caller to have any capabilities specified in the

   290 	 *     key use security policy.

   291 	 * @leave KErrPermissionDenied If the caller does not conform to the key use

   292 	 *     security policy.

   293 	 * @leave KErrNotFound If the key the handle referes to does not exist.

   294 	 * @leave KErrKeyAlgorithm If the key is not a DSA key.

   295 	 * @leave KErrKeyUsage If the key doesn't have sign usage.

   296 	 * @leave KErrKeyValidity If the key is not currently valid.

   297 	 */

   298 	virtual void Open(const TCTTokenObjectHandle& aHandle, 

   299 					  MDSASigner*& aSigner, 

   300 					  TRequestStatus& aStatus) = 0;

   301 	

   302 	/**

   303 	 * Open a RSA key for private decryption

   304 	 * 

   305 	 * @param aHandle The handle of the key to be opened.  This must be the

   306 	 *     handle of a RSA key on this store that is usable by this process

   307 	 *     for decryption or the operation will fail.

   308 	 * @param aDecryptor The returned decryptor object

   309 	 * @param aStatus Asynchronous request notification.

   310 	 * 

   311 	 * @capability Dependent Requires the caller to have any capabilities specified in the

   312 	 *     key use security policy.

   313 	 * @leave KErrPermissionDenied If the caller does not conform to the key use

   314 	 *     security policy.

   315 	 * @leave KErrNotFound If the key the handle referes to does not exist.

   316 	 * @leave KErrKeyAlgorithm If the key is not an RSA key.

   317 	 * @leave KErrKeyUsage If the key doesn't have decrypt usage.

   318 	 * @leave KErrKeyValidity If the key is not currently valid.

   319 	 */

   320 	virtual void Open(const TCTTokenObjectHandle& aHandle, 

   321 					  MCTDecryptor*& aDecryptor,

   322 					  TRequestStatus& aStatus) = 0;

   323 	

   324 	/**

   325 	 * Open a DH key for key agreement

   326 	 * 

   327 	 * @param aHandle The handle of the key to be opened.  This must be the

   328 	 *     handle of a DH key on this store that is usable by this process

   329 	 *     for decryption or the operation will fail.

   330 	 * @param aDH The returned agreement object

   331 	 * @param aStatus Asynchronous request notification.

   332 	 * 

   333 	 * @capability Dependent Requires the caller to have any capabilities specified in the

   334 	 *     key use security policy.

   335 	 * @leave KErrPermissionDenied If the caller does not conform to the key use

   336 	 *     security policy.

   337 	 * @leave KErrNotFound If the key the handle referes to does not exist.

   338 	 * @leave KErrKeyAlgorithm If the key is not a DH key.

   339 	 * @leave KErrKeyUsage If the key doesn't have derive usage.

   340 	 * @leave KErrKeyValidity If the key is not currently valid.

   341 	 */

   342 	virtual void Open(const TCTTokenObjectHandle& aHandle, 

   343 					  MCTDH*& aDH, TRequestStatus& aStatus) = 0;

   344 

   345 	/** Cancels an ongoing Open() operation */

   346 	virtual void CancelOpen() = 0;

   347 	

   348 	/**

   349 	 * Exporting keys

   350 	 */

   351 

   352 	/**

   353 	 * Get the public half of a key pair.

   354 	 *

   355 	 * The key is returned in DER-encoded ASN-1. The format is that of the X509

   356 	 * SubjectPublicKeyInfo type.

   357 	 *

   358 	 * <p>For RSA keys, the format is:</p>

   359 	 * <pre>

   360 	 * SEQUENCE-OF

   361 	 *     SEQUENCE-OF

   362 	 *         OID of the encryption algorithm (KRSA)

   363 	 *         NULL

   364 	 *     BIT STRING encoded public key.

   365 	 * </pre>

   366 	 *

   367 	 * <p>For DSA keys, the format is:</p>

   368 	 * <pre>

   369 	 * SEQUENCE-OF

   370 	 *     SEQUENCE-OF

   371 	 *         OID dsa (1.2.840.10040.4.1)

   372 	 *         SEQUENCE-OF

   373 	 *             INTEGER p

   374 	 *             INTEGER q

   375 	 *             INTEGER g

   376 	 *     BIT STRING

   377 	 *         INTEGER public value (y)

   378 	 * </pre>

   379 	 *

   380 	 * @param aHandle The handle of the key.

   381 	 * @param aPublicKey A pointer to a buffer.  This will be set to a newly

   382 	 *     created buffer containing the exported key data.  The caller is

   383 	 *     responsible for deleting the buffer.

   384 	 * @capability Dependent Requires the caller to have any capabilities specified in the

   385 	 *     key use security policy.

   386 	 * @leave KErrPermissionDenied If the caller does not conform to the key use

   387 	 *     security policy.

   388 	 * @leave KErrNotFound If the key the handle referes to does not exist.

   389 	 * @leave KErrKeyAlgorithm If the key is not an RSA or DSA key.

   390 	 */

   391 	virtual void ExportPublic(const TCTTokenObjectHandle& aHandle,

   392 							  HBufC8*& aPublicKey,

   393 							  TRequestStatus& aStatus) = 0;

   394 	

   395 	/** Cancels an ongoing ExportPublic() operation */

   396 	virtual void CancelExportPublic() = 0;

   397 

   398 	};

   399 

   400 

   401 template <class Signature> inline MCTSigner<Signature>::MCTSigner(MCTToken& aToken)

   402 		: MCTTokenObject(aToken)

   403 	{

   404 	}

   405 

   406 template <class Signature> inline MCTSigner<Signature>::~MCTSigner()

   407 	{

   408 	}

   409 

   410 inline MCTDecryptor::MCTDecryptor(MCTToken& aToken)

   411 		: MCTTokenObject(aToken)

   412 	{

   413 	};

   414 

   415 inline MCTDecryptor::~MCTDecryptor()

   416 	{

   417 	};

   418 

   419 inline MCTDH::MCTDH(MCTToken& aToken)

   420 		: MCTTokenObject(aToken)

   421 	{

   422 	};

   423 

   424 inline MCTDH::~MCTDH()

   425 	{

   426 	};

   427 

   428 #endif // __MKEYSTORE_H__