The unified stores overview

• Introduction

• Programming with the unified stores

• Common concepts

• Token object handle - TCTTokenObjectHandle

A Symbian OS device may contain zero or more individual certificate 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 act as central interfaces for certificate and key management, so that application writers do not need to know details of the specific implementations present. The unified store classes automatically discover all implementations of the relevant interface on the device using the crypto token framework (i.e., the ctframework component).

The unified stores centralise and amalgamate the individual certstore and keystore implementations. The stores are unified in the sense that client requests, which relate 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.

The ctframework component provides the interfaces for key store and certificate store implementations, and the unified stores themselves are implemented in Certificate Management's (certman's) certstore component (see Dependency diagram for certstore.dll). 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 certificate store and the unified key store.

The software certificate 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.exe, 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 unifiedkeystore.h, and you should refer to them while reading the example code.

Within these files, most of the functions are asynchronous and this means that clients need to be implemented as active objects to work. All calls to asynchronous functions must be called from the context of active objects - the active scheduler will call the client's RunL() function when the asynchronous function completes.

This means that the following code will not work:

 
// Broken!
TRequestStatus status;
certStore->DoSomething(parameters, status);
User::WaitForRequest(&status);

This section describes concepts common to both unified stores.

Token object handle - TCTTokenObjectHandle

See the API reference documentation for the TCTTokenObjectHandle class.

A token object handle is a concept from the crypto token framework that is used to identify an object (e.g., a key or a certificate) 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 token object handle is lightweight and can be easily passed between processes.

Token object handles 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.