The unified certificate store

• Introduction

• Certificate store concepts

• Supported certificate types

• Certificate info - CCTCertInfo

• Applicability and trust

• Creating a unified certificate store

• Finding certificates

• Adding certificates

• Removing certificates

• Retrieving certificates

• Certificate applications and trust

• Class diagrams

  • CUnifiedCertStore

  • CCheckedCertStore

  • CUnifiedCertStoreWorkingVars

Certificate storage uses the interface defined by the crypto token framework. The unified certificate store (unified certstore) unifies all the available implementations of the certstore interface. If a product manufacturer implements one of the certstore interfaces using, for example, a WIM, then it will automatically be picked up by the unified certstore. The unified certstore offers:

• An API to access the certificates stored on the device

• Assignment of trust status to a certificate on an application by application basis

• Certificate chain construction and validation.

The certstore APIs support X.509, WTLS, and X.968 certificates. Certificates can be physically present in the store (as is normally the case), or they can be referenced by a URL. When clients retrieve or add certificates they have to indicate which kind of certificate they are interested in retrieving or which kind of certificate they are adding. They do this using TCertificateFormat, an enumeration which currently has one of the following (self-descriptive) values:

This enables the certstore to commit only to the interface offered by crypto.dll, so new certificate specifications can be kept in the store without changing it.

Also, there are three supported "owner types":

defined by the TCertificateOwnerType enumeration.

This class holds information about a certificate, and is used to represent that certificate in the unified certstore API. It has accessors for the following attributes:

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

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". Certificates 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.

See the Certificate applications and trust section below.

The unified certstore can be opened in two modes - writeable and read-only. The mode is determined by a parameter passed to the NewL() and NewLC() functions. Once the object has been created, it must be initialised, and this is done by the asynchronous Initialize() function.

For example, to create and open a unified certstore in writable mode a client might use the following 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
    }

The unified certstore supplies List() functions 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 functions for the following attributes:

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() function just takes a filter and a reference to an array of certificate info objects, which it populates with the results of the search. For example to list all X.509 CA certificates on a device:

void CCertStoreExample::ListCertsL()
{
    // iCerts is an RMPointerArray<CCTCertInfo> which will be filled with the certificates found 
    // iCertFilter is a CCertAttributeFilter*, initially set to NULL

    // Create filter object
    iCertFilter = CCertAttributeFilter::NewL();       
    iCertFilter->SetFormat(EX509Certificate);
    iCertFilter->SetOwnerType(ECACertificate);

    iCertStore->List(iCerts, *iCertFilter, iStatus);
    iState = EListCerts;
    SetActive();        

    // RunL called when this completes
}

There are two further List() overloads that allow filtering based on the issuer's distinguished name (DN). These take a single DN to match, and a list of possible DNs to match.

To add a certificate it is first necessary to determine which actual certstore the new certificate should reside in. The unified certstore gives access to all writable certificate stores through the WritableCertStoreCount() and WritableCertStore() functions. Note that if the unified certstore has been opened in read-only mode, it will report that there are no writable certificate stores available. Writable certstores implement the MCTWritableCertStore interface, defined in mctwritablecertstore.h.

Using these functions is much the same as for the equivalent functions to get key store managers in the unified key store. So, to compile a list of the available writable certstores, an application might use the following code:

void CCertStoreExample::GetWritableCertStoreLabelsL()
{
    // iLabelList is a RPointerArray<HBufC8>

    for (TInt index = 0 ; index < iCertStore->WritableCertStoreCount() ; ++i)
    {
        MCTWritableCertStore& store = iCertStore->WritableCertStore(index);
        MCTToken& token = store->Token();
        HBufC* label = token->Label().AllocLC();
        User::LeaveIfError(iLabelList.Append(label));
        CleanupStack::Pop(label);
    }
}

When a writable certstore has been chosen, the certificate can be added. The Add() function takes the following parameters:

For example, to add an X.509 CA certificate, an application might do the following:

void CCertStoreExample::AddCert()
{
// iWritableStore is an MCTWritableCertStore object
// iCertLabel is an HBufC* containing the label
// iCertData is an HBufC8* containing the certificate

    iWritableStore->Add(*iCertLabel, ECACert, NULL, NULL, *iCertData, iStatus);
    iState = EAddingCert;
    SetActive();

    // RunL called when this completes
}

Removing a certificate is done by simply calling the Remove() function and passing it the CCTCertInfo of the certificate to be removed. For example:

void CCertStoreExample::RemoveCert()
{
// iWritableStore is an MCTWritableCertStore object
// iCert is a CCTCertInfo*

    iWritableStore->Remove(iCert, iStatus);
    iState = ERemovingCert;
    SetActive();

    // RunL called when this completes
}

There are two Retrieve() functions - one allows the caller to retrieve the ASN.1 certificate data and the other the parsed representation, a CCertificate-derived object (CCertificate is defined in signed.h).

It is not possible to retrieve the parsed representation of URL certificates - the function will complete with KErrNotSupported in this case.

For example, to get the ASN.1 data for a certificate:

void CCertStoreExample::RetrieveCertData()
{
    // iCert is a CCTCertInfo* object - the certificate to retrieve
    // iCertData is an HBufC8*

    // Allocate buffer of appropriate length
    iCertData = HBufC8::NewMaxL(iCert->Size());

    iCertStore->Retrieve(iCert, iCertData->Des(), iStatus);
    iState = ERetrievingCertData;
    SetActive();

    // RunL called when this completes
}

And to get the parsed representation:

void CCertStoreExample::RetrieveCertObject()
{
    // iCert is a CCTCertInfo*
    // iCertObject is an CCertificate*

    iCertStore->Retrieve(iCert, iCertObject, iStatus);
    iState = ERetrievingCertObject;
    SetActive();

    // RunL called when this completes
}

The unified certstore API provides the following functions to get and set the applicability and trust settings for certificates:

The diagrams below show the main classes used in the unified certstore. Blue dotted arrows indicate that a class is contained or used by another class. The arrows are labelled with the variable(s) through which the pointed class is accessible. The colour of the boxes indicates the type of Symbian class, i.e., M, C, R or T class. For detailed information on each component see the certman API Reference material.