/**

@page UnifiedStores The unified stores

@section intro Introduction

This document describes the unified certificate store and unified key store.

A Symbian OS device may contain zero or more individual cert stores, and zero or

more key stores.  Software implementations for both of these are supplied, and

licensees may add their own, perhaps using special hardware on the device - for

example using a WIM.  The unified store classes acts as an central interfaces

for certificate and key management, so that application writers do not need to

know details of the specific implementations present.  They automatically

discovers all implementations of the relevant interface on the device using the

crypto token framework.

These stores are unified in the sense that client requests which related to all

store implementations (such as "list keys" or "list certificates") are passed to

every implementation in turn, and the results collated.  Requests that relate to

a specific store are routed to the correct implementation.

Clients should only use the unified store class to access certificates and keys.

There is no need to use the crypto token framework directly, and although this

is possible, it is not recommended.

This document gives a description of how to perform basic certificate and key

operations using the unified stores.  

@section programmingUnifiedStores Programming with the unified stores

The ctframework component provides the interfaces for key store and cert store

implementations, and the unified stores themselves are implemented in certman's

certstore component.  Programs wishing to use the unified stores should

therefore be linked against both certstore.lib and ctframework.lib.  Note that

certstore.lib provides both the unified cert store and the unified key store.

The software cert store implementation supplied with Symbian OS is provided by

filecertstore.dll, and this runs entirely in the client application.  The

software key store runs in a separate server process - this is implemented by

fstokenserver.dll, and the client side part that communicates with the server is

provided by fstokencli.dll.  The unified stores use the ECom framework to load

these DLLs automatically, so there is no need to link against them in client

applications.

The main header files used are unifiedcertstore.h and unfiedkeystore.h, and you

should refer to them while reading the example code.

Most methods are asynchronous and this means that clients need to be implemented

as active objects to work.  All calls to asynchronous methods must be called

from the context of active objects - the active scheduler will call the client's

RunL() method when the asynchronous method completes.

This means that the following code will not work:

@code 

// Broken!

TRequestStatus status;

certStore->DoSomething(parameters, status);

User::WaitForRequest(&status);

@endcode

@section commonConcepts Common concepts

This section describes concepts common to both unified stores.

@subsection tokenObjectHandler Token object handle - TCTTokenObjectHandle

A token object handle is a concept from the crypto token framework that is used

to identify an object associated with a particular token.  It consists of a

token identifier and an object identifier which is unique among all objects with

that token.  The object is lightweight and can be easily passed between

processes.

These are used to identify keys and certificates.  This allows the unified store

to route client requests that concern a particular object onto the token that

actually has that object.

This class is defined in tcttokenobjecthandle.h.

@section unifiedKeyStore The unified key store

@subsection limiatations Limitations

Currently, this document does not cover owners and users, authentication or

private key export.

@subsection sec2 Key store concepts

@subsubsection sec21 Key info - CCTKeyInfo

Detailed information about a key is represented as a CCTKeyInfo object.  Objects

of this type are passed back to the client by "list" and "get key info"

operations.  The class is defined in the mctkeystore.h header file.  It has

accessors for the following attributes:

@li ID - a SHA-1 hash of the public key, used to uniquely identify it.

@li Usage - a bitfield representing the allowed usages of the key.  This is of

	type TKeyUsagePKCS15, defined in securitydefs.h.

@li Size - the size of the key in bits.

@li Label - a text string to identify the key to users.

@li Owner - the UID of the application that created or imported the key.  

@li Users - a list of UIDs of applications that are allowed to use the key.

@li Algorithm - the key algorithm: RSA, DSA or DH.

@li AccessType - a bitfield that determines the sensitivity of the key.

@li Native - indicates whether cryptographic operations involving the key are

	carried out within the key store implementation itself (ie in hardware if

	the key store is implemented in hardware).

@li StartDate - the start of the validity period of the key.

@li EndDate - the end of the validity period of the key.

@li PKCS8AttributeSet - additional key attributes as a DER-encoded set.

@li Protector - an MCTAuthenticationObject that can be used to access the

	authentication mechanism for the key store.

@li Token - an MCTToken object that represents the actual key store

	implementation the key is in.  It is possible to use this to get access to the

	key store implementation, but this is not recommended.

For a description of owners, users and authentication objects, please see the

functional specification and architecture analysis documents.

CCTKeyInfo has a conversion operator to TCTTokenObjectHandle, so instances of

this class can be passed to any methods in the unified key store requiring a

token object handle.

@subsubsection authObject Authentication objects - MCTAuthenticationObject

Authentication objects are used to control the authentication mechanism of the

key store.  They are accessed by calling the Protector() method of a CCTKeyInfo.

The authentication object returned is owned by the keystore implementation and

you should not attempt to free it yourself - this is managed automatically.

They may also be shared between keys - ie, the same object may be returned for

more than one key.  The software key store implementation works like this - it

associates one auth object instance with each key owner application.  In other

words, every key with the same owner has the same auth object.  This is because

authetication properties like the passphrase timeout are set on a per-owner

basis in this implementation.

@subsection sec3 Creating a CUnifiedKeyStore

The object is created in the usual way, by calling the static NewL() or NewLC()

methods, and then must be initialised by calling the asynchronous Initialize()

method.  

For example, a client might use the following code to create and initialise a

unified key store object:

@code

void CKeyStoreExample::CreateUnifiedKeystoreL()

	{

	// iKeyStore is a CUnifiedKeyStore* 

	// iFS is an RFs (file server client)

	// iState is an enum that records the state of the active object

	iKeyStore = CUnifiedKeyStore::NewL(iFs);

	iKeyStore->Initialize(iStatus);

	iState = EInitializingKeystore;

	SetActive();

	// RunL called when this completes

	}

@endcode

@subsection sec4 Finding keys

The unified key store allows a client to search all keys on a device regardless

of which physical store they are in.  A filter object is specified which determines

which keys are returned - you can filter on:

@li The key indentifier - used when you are searching for a particular key.

@li The key usage

@li Tke key owner UID

@li The key algorithm

All of these default to "don't care".  So, an application that wishes to find

all DSA keys owned by a certain application that are usable for signing might do

the following:

@code

void CKeyStoreExample::FindSomeKeys()

{

	// KApplicationUID is UID of key owner application

	// iKeys is an RMPointerArray<CCTKeyInfo> that is filled with the keys found

	TCTKeyAttributeFilter filter;

	filter.iOwner = KApplicationUID;

	filter.iUsage = EPKCS15UsageSign;

	filter.iKeyAlgorithm = CCTKeyInfo::EDSA;

	iKeyStore->List(iKeys, filter, iStatus);

	iState = EFindingKeys;

	SetActive();

	// RunL called when this completes

}

@endcode

@subsection sec5 Performing cryptographic operations with keys

Performing a cryptographic operation is a two stage process.  First, the key

must be "opened", which creates an object capable of performing the required

operation.  Then the new object's methods are called to actually execute

it. Below is a list of the supported operations together with the objects

created:

@li DSA Sign - MDSASigner

@li RSA Sign - MRSASigner

@li RSA Decrypt - MCTDecryptor

@li DH agreement - MCTDH

These interfaces are defined in the header file mkeystore.h.

The created objects are owned by the client, and hence must be disposed of by

calling their Release() method when they are no longer required.

To perform an RSA signing operation, the key is opened to create an MRSASigner

object.  This object supports two signing methods:

@li SignMessage, which computes a SHA-1 digest of the input data and signs that.

@li Sign, which takes as input a message digest to sign (ie does a raw RSA sign

operation).

These signing methods create a CRSASignature object as output.

For example, to RSA sign some data in iDataToSign:

@code

void CKeyStoreExample::RSASign(const CCTKeyInfo& aKey)

{

	// iRSASigner is an MRSASigner*

	// iDataToSign is a HBufC8* containing data to be signed

	// iRSASignature is a CRSASignature* which will contain the result

	iKeyStore->Open(aKey, iRSASigner, iStatus);

	iState = EOpenRSAKeyForSigning;

	SetActive();

}

void CKeyStoreExample::RunL()

{

	switch (iState)

	{

		...

		case EOpenRSAKeyForSigning:

			PerformRSASignOperation();

			break;

		...

	}

}

void CKeyStoreExample::PerformRSASignOperation()

{

	iRSASigner->SignMessage(*iData, iRSASignature, iStatus);

	iState = EPerformRSASignOperation;

	SetActive();

	// RunL called again when this completes

}

@endcode

DSA Signing works much the same as for RSA Signing described above.  The only

difference is that the Open() method creates an MDSASigner object (The Open()

methods are overloaded on the type of the created object).  The DSA signer

differs from an MRSASigner only in that the signing method creates a

CDSASignature object.

RSA encryption and Diffie-Hellman key agreement are analogous.

@subsection sec6 Generating keys

For this operation it is necessary to know in advance which of the key stores

implementations on the device the new key should be stored in.  The application

could ask the user for this information, or it could choose a store itself based

on some policy.  Either way, the available key stores that support write

operations can be found using the KeyStoreManagerCount() and KeyStoreManager()

accessor methods.

A key store manager object is a token interface (see MCTTokenInteface defined in

mcttokeninterface.h), and from this it is possible the get the token via the

Token() method and hence the token label.  So, in order to ask the user which

key store they wanted a key to be created in, a list of the labels of available

key stores could be built up like this:

@code

void CKeyStoreExample::GetKeyStoreManagerLabelsL()

{

	// iLabelList is a RPointerArray<HBufC8>

	for (TInt index = 0 ; index < iKeyStore->KeyStoreManagerCount() ; ++i)

	{

		MCTKeyStoreManager& manager = iKeyStore->KeyStoreManager(index);

		MCTToken& token = manager->Token();

		HBufC* label = token->Label().AllocLC();

		User::LeaveIfError(iLabelList.Append(label));

		CleanupStack::Pop(label);

	}

}

@endcode

Once the index of the key store manager has been determined, the key can be

created by calling the CreateKey() method.  Among other things it takes the

following parameters that are a subset of the attributes of a CCTKeyInfo:

@li aUsage - The key usage flags in the PKCS15 format.

@li aSize - The key size in bits.

@li aLabel - The textual label for the key.

@li aAlgorithm - The key algorithm - RSA, DSA or DH.

@li aAccessType - The key's access type bitfield.  Only two of the bits defined

	may be set when creating a key - EExtractable and ESensitive.

@li aStartDate - the start of the validity period of the key.

@li aEndDate - the end of the validity period of the key.

For example:

@code

void CKeyStoreExample::CreateRSAKey(TInt aKeyStoreIndex)

{

	// iKey is a CCTKeyInfo* that will be set if the method succeeds

	_LIT(KMyKeyName, "Example key");

	TTime startDate, endDate;

	startDate.UniversalTime();

	endDate.UniversalTime();

	endDate += TTimeIntervalYears(1); // key valid for a year

	iKeyStore->CreateKey(

		aKeyStoreIndex,

		EPKCS15UsageSign,

		1024,

		KMyKeyName,

		CCTKeyInfo::ERSA,

		CCTKeyInfo::EExtractable,

		startDate,

		endDate,

		iKey,

		iStatus);

	iState = ECreateKey;

	SetActive();

	// RunL called when this completes

}

@endcode

@subsection importKey Importing keys

Importing keys is very similar to creating keys, except that the ImportKey()

method takes an additional two parameters:

@li aKeyData - the key data in pkcs#8 format.

@li aIsEncrypted - whether the key data is pkcs#5 encrypted.

@subsection deleteKey Deleting keys

Keys can be deleted with the DeleteKey() method, for example:

@code

void CKeyStoreExample::DeleteKey()

{

	// iKey is a CCTKeyInfo*

	iKeyStore->DeleteKey(*iKey, iStatus);

	iState = EDeleteKey;

	SetActive();

	// RunL called when this completes

}

@endcode

@subsection exportPublicKey Getting the public key

The ExportPublic() method allows the public key to be exported, in DER-encoded

ASN.1 format.  To export an RSA public key, and then reconstruct a useful key

object from it, an application might do the following:

@code

CKeyStoreExample::ExportRSAPublicKey()

{

	// iKey is a CCTKeyInfo*

	// iPublicKeyData is an HBufC8*

	iKeyStore->ExportPublic(*iKey, iPublicKeyData, iStatus);

	iState = EExportPublic;

	SetActive();

}

void CKeyStoreExample::RunL()

{

	switch (iState)

	{

		...

		case EExportPublic:

			DecodeRSAPublicKeyData();

			break;

		...

	}

}

void CKeyStoreExample::DecodeRSAPublicKeyData()

{

	// iRSAPublicKey is a CRSAPublicKey*

	TX509KeyFactory factory; 

	iRSAPublicKey = factory.RSAPublicKeyL(*iPublicKeyData);

}

@endcode

@subsection changePassphrase Changing the passphrase

Changing the passphrase is accomplished by telling a key store to ask the user

for the new passphrase.  This is done by obtaining the authentication object for

a key in the appropriate key store, and calling its ChangeReferenceData()

method.  The keystore will then prompt the user for the old and new passphrases,

and it the old passphrase is entered correctly, the passphrase is changed.  The

old and new passphrases are never seen by the calling application.

For example:

@code

void ChangePassphraseL(CCTKeyInfo& aKey)

{

	MCTAuthenticationObject* authObject = aKey.Protector();

	if (authObject == NULL)

		User::Leave(KErrNotSupported);

	authObject->ChangeReferenceData(iStatus);

	iState = EChangePassphrase;

	SetActive();

	// RunL called when this completes

}

@endcode

@section unifiedCertStore The Unified Certificate Store

@subsection certstoreConcepts Certificate store concepts

@subsubsection certTypes Supported certificate types

The certificate store APIs support X509 and WTLS certificates.  Certificates can

be physically present in the store (as is normally the case), or they can be

referenced by a URL.  There are three "owner types" supported:

@li CA - CA certs are used as trust roots when validating certificate chains.

@li User - User certs are used to establish the user's identity with a remote server.

@li Peer - Peer certs are a third party's user certs.

@subsubsection certInfo Certificate info - CCTCertInfo

This class holds information about a certificate, and is used to represent that

certificate in the unified cert store API.  It has accessors for the following

attributes:

@li Label - a text string to identify the cert to users.

@li SubjectKeyId - A hash of the subject's public key.

@li IssuerKeyId - A hash of the issuer's public key

@li CertificateFormat - The format of the certificate - X509, WTLS X509 URL or

	WTLS URL - as defined by the TCertificateFormat enum.

@li CertificateOwnerType - The type of the certificate - CA, user or peer - as

	defined by the TCertificateOwnerType enum

@li Size - The size of the actual certificate data in bytes.

@li IsDeletable - Whether it is possible to delete this certificate.

@li IssuerHash - A hash of the issuer's X500 distinguished name, or NULL if it is

	unknown.

@li Token - an MCTToken object that represents the actual cert store

	implementation the cert is in.  It is possible to use this to get access to the

	cert store implementation, but this is not recommended.

Like CCTKeyInfo, this object has a conversion operator to TCTTokenObjectHandle.

@subsubsection appTrustConcept Applicability and trust

Certificates are marked to indicate what purpose they are to be used for - these

uses are referred to as "applications".  Examples of applications include

"software install" and "TLS client authentication".  Certs also have a "trust"

setting - this indicates whether or not the certificate should be trusted for

any of its application.  The idea is that a program will look for all

certificates which have the correct application and that are trusted, in order

to restrict its search to relevant certificates.

@subsection creatingUnifiedCertStore Creating a Unified Certificate Store

The unified cert store can be opened in two modes - writeable and read only.

The mode is determined by a parameter passed to the NewL() and NewLC() methods.

Once the object has been created, it must be initialised, and this is done by

the asynchronous Initialize() method.

For example, to create and open a unified cert store in writable mode a client

might use the following code:

@code

void CCertStoreExample::OpenUnifiedCertStoreL()

	{

	// iCertStore is a CUnifiedCertStore* 

	// iFS is an RFs (file server client)

	// iState is an enum that records the state of the active object

	iCertStore = CUnifiedCertStore::NewL(iFs, ETrue);

	iCertStore->Initialize(iStatus);

	iState = EInitializingCertStore;

	SetActive();

	// RunL called when this completes

	}

@endcode

@subsection listCerts Finding certificates

The unified cert store supplies a List() methods to find certificates in the

stores.  A filter object of type CCertAttibuteFilter is passed in to restrict

the certificates returned.  This is defined in ccertattributefilter.h.  It has

setter methods for the following attributes:

@li Label - The label to match.

@li Uid - The UID of an application the certificates must support.

@li Format - The desired format.

@li OwnerType - The desired owner type.

@li KeyUsage - The key usage the certificates must support.

@li SubjectKeyId - Used when searching for a certificate that matches a key.

@li IssuerKeyId - Used when searching for all certs issued by particular cert.

These attributes default to a "don't care" setting.  All attributes that have

been set must match for a certificate to be returned.

The first version of the list method just takes a filter and a reference to an