Unified Certificate Store Tutorial

Procedure

Follow these steps to perform the various certificate manipulation operations using the Unified Certificate Store:

1. Create an instance of the Unified Certificate Store and initialize it.

   You can create a certificate store in read-only or writable mode. Operations like adding and removing certificates can be performed when the certificate store is in writable mode. Basic operations like listing certificates, retrieving certificate details, viewing trust statuses of certificates can be performed when the certificate store is in read-only mode.

   The following steps explain the processing of creating and initialising a Unified Certificate Store:

   1. Create an instance of the RFs class. Use the object created as a file system session.

   2. Create an object of type CUnifiedCertStore using CUnifiedCertStore::NewL() or CUnifiedCertStore::NewLC().

      Note:

      The value that you set for the Boolean variable aOpenForWrite decides if you can open the certificate store in read-only or writable mode. Set the value of the variable to:

      • ETrue to open the certificate store with write access.

      • EFalse to open the certificate store with read-only access.

   3. Initialize the certificate store and the member functions using the asynchronous function CUnifiedCertStore::Initialize().

   The code snippet to create and initialize a Unified Certificate Store is as follows:

   
   //Create a file system session object
   RFs iFs;
   iFS.connect();
   CleanupClosePushL(iFs);
   
   
   //Create and initialize the Unified Certificate Store
   CUnifiedCertStore* iCertStore = CUnifiedCertStore::NewL(iFs, ETrue);
   
   //iStatus is a TRequestStatus
   iCertStore->Initialize(iStatus); 
   

2. Complete any of the following tasks as per your requirement:

   • Adding certificates

   • Removing certificates

   • Finding certificates

   • Retrieving certificate as a parsed object

   • Retrieving certificate details

   • Managing applicability and trust settings for certificates

Adding certificates

Before adding a certificate, it is essential to determine the certificate store to which the certificate will be added.

The following steps explain the process of retrieving the certificate store by specifying an appropriate index value and then adding a certificate to the particular store:

1. Create an object of a writable certificate store using MCTWritableCertStore and retrieve the certificate store to which the certificate will be added.

2. Specify the details of the certificate to be added and include it to the selected store using MCTWritableCertStore::Add().

The following code snippet explains how to add a certificate to the certificate store:

//Create and initialize the Unified Certificate Store
.
.
.

//Create an object of the writable certificate store 

//Retrieve the certificate store present at the specified index
//If the certificate store index is invalid 
//or the specified certificate store cannot be opened
//then the store object is NULL

MCTWritableCertStore& ustore = iCertStore->iWritableCertStore(0);
.
.
.
//Specify details of the certificate

//The certificate label
HBufC* iCertLabel; 
iCertLabel = HBufC::NewL(20);
_LIT(KTxtLabel,"CertificateLabel");
*iCertLabel = KTxtLabel;

//The certificate format
TCertificateFormat icertFormat = EX509Certificate;

//The certificate owner type
TCertificateOwnerType iCertOwnerType = ECACertificate;

//The certificate's subject key id and issuer key id
//Both are optional fields

TKeyIdentifier* aSubjectKeyId = NULL;
TKeyIdentifier* aIssuerKeyId = NULL;

//iCertData is an HBufC8* buffer that holds certificate data
HBufC* iCertData  = HBufC::NewL(200);

//Add the certificate
//The subject key id and issuer key id values are 0

ustore->Add(*iCertLabel, EX509Certificate, ECACertificate, 0, 0, iCertData->Des(), iStatus); 

Removing certificates

Specify details of the certificate to be removed and then remove it from the certificate store. The following steps provide the require details:

1. Create an object of a writable certificate store using MCTWritableCertStore and retrieve the certificate store from which the certificate will be removed.

2. Create a CCTCertInfo object of the certificate to be removed. Pass this to the CUnifiedCertStore::Remove() function to remove the particular certificate from the certificate store.

The following code snippet explains how to remove a certificate from the certificate store:

//Create and initialize the Unified Certificate Store
.
.
.

//Create an object of the writable certificate store 

//Retrieve the certificate store present at the specified index
//If the certificate store index is invalid 
//or the specified certificate store cannot be opened
//then the store object is NULL

MCTWritableCertStore& ustore = iCertStore->iWritableCertStore(0);
.
.
.
//Create a CCTCertInfo object for the certificate to be removed

//Instantiate a token

_LIT(KTokenString,"certtoken");

class CSimpleToken:: public CBase,public MCTToken
{
public:
    static MCTToken* NewL(MCTTokenType* aTokenType);

public: //  From MCTToken
     MCTTokenType& TokenType();
     const TDesC& Label();
     TCTTokenHandle Handle();

private:
     MCTTokenType* iTokenType;
}

MCTToken* CSimpleToken::NewL(MCTTokenType* aTokenType)
     {
     CDummyTokenClient* self = new (ELeave) CSimpleTokenType(aTokenType);
     return static_cast<MCTToken*>(self);
     }
 
 CSimpleToken::CSimpleToken(MCTTokenType* aTokenType)
             :   iTokenType(aTokenType),
     {
     }

 MCTTokenType& CSimpleToken::TokenType()
     {
     return *iTokenType;
     }
 const TDesC& CSimpleToken::Label()
     {
     return KTokenString();
     }
 TCTTokenHandle CSimpleToken::Handle()
     {
     return (TCTTokenHandle(iTokenType->Type(), 0));
     }
// Create token type
TUid tokenUid = 0x103478;
CCTTokenType* tokenType =  CCTTokenType(tokenUid,iFs);
CleanupReleasePushL(*tokenType);

// Open the token
MCTToken* token = NULL;
tokenType.openToken(KTokenString, token, iStatus);  
.
.
.
//The certificate label
HBufC* iCertLabel = HBufC::NewL(20);
_LIT(KTxtLabel,"CertificateLabel2");
*iCertLabel = KTxtLabel;
  
//The certificate format
TCertificateFormat icertFormat = EX968Certificate;

//The certificate owner type
TCertificateOwnerType iCertOwnerType = EUserCertificate;

//The certificate's subject key id and issuer key id fields
TKeyIdentifier* aSubjectKeyId = NULL;
TKeyIdentifier* aIssuerKeyId = NULL;

//The certificate ID 
const TInt KCertificateId = 0x00001234;

//iCertInfo is a CCTCertInfo object that points to the certificate to be removed
CCTCertInfo* iCertInfo  = CCTCertInfo::NewLC(*iCertLabel, icertFormat, iCertOwnerType, 999, aSubjectKeyId, aIssuerKeyId, token, KCertificateId, ETrue);


//Remove the certificate
ustore->Remove(iCertInfo, iStatus);
CleanupStack::PopAndDestroy(2, tokenType);

Finding certificates

You can specify filter criteria like certificate format, certificate owner type and so on to find a particular set of certificates from the certificate store. The following steps explain the process of finding certificates:

1. Specify a filter object for the certificates to be returned.

2. Specify the filter criteria for returning a specific category of certificates.

3. Use the CUnifiedCertStore::List() function to list the filtered certificates.

The following code snippet explains how to find certificates in a certificate store:

//Create and initialize the Unified Certificate Store
.
.
.

RPointerArray<CCTCertInfo> iCerts; //This variable will contain the certificates found

//Specify filter object for the certificates
CCertAttributeFilter& iCertFilter;
iCertFilter = CCertAttributeFilter::NewL(); 


//Specify the filter criteria           
iCertFilter->SetFormat(EWTLSCertificate); 
iCertFilter->SetOwnerType(ECACertificate);


//List the certificates based on the filter criteria
iCertStore->List(iCerts, iCertFilter, iStatus);

Retrieving certificate as a parsed object

You can retrieve a certificate as a parsed object only in case of X.509 or Wireless Transport Layer Security (WTLS) certificates. This method of retrieval does not work for URL certificates.

Use the CUnifiedCertStore::Retrieve() function to retrieve the certificate as a parsed object.

The following code snippet explains how to retrieve a certificate as a parsed object:

//Create and initialize the Unified Certificate Store
.
.
.

//Retrieve the certificate

//iCertInfo is a CCTCertInfo object that points to the certificate to be retrieved
//iCert contains the returned certificate
 
iCertStore->Retrieve(iCertInfo, iCert, iStatus);

Retrieving certificate details

You can retrieve Abstract Syntax Notation One (ASN.1) encoded certificate data from the certificate store. The certificate data is returned as an ASN.1-encoded string.

Use the CUnifiedCertStore::Retrieve() function to retrieve the certificate details. Unlike the function used to retrieve a certificate as a parsed object, this function also accepts a buffer object to hold the details of the certificate that is being retrieved.

The following code snippet explains how to retrieve details of a specific certificate:

//Create and initialize the Unified Certificate Store
.
.
.

//Retrieve the certificate details

//iCertInfo is a CCTCertInfo object that points to the certificate to be retrieved
//iCertData is an HBufC8* buffer that holds certificate data

iCertStore->Retrieve(iCertInfo, iCertData->Des(), iStatus); 

Managing applicability and trust settings

The trust status of a certificate indicates if it can be considered as a trust anchor for validating any application. This status is valid only for certificates issued by the Certificate Authority (CA). The applicability settings of a certificate indicate the applications for which the trust status is valid.

The Unified Certificate Store API provides the following functions to get and set the applicability and trust settings for certificates:

Setting applicability and trust settings

You can change the existing applicability and trust settings of a certificate. The details are as follows:

• Set applicability: Specify a CCTCertInfo object for the certificate, an array for containing the new applicability settings and a request status object that will contain the result of the applicability setting operation when complete. Pass these as parameters to the CUnifiedCertStore::SetApplicability() function and apply the settings.

• Set trust: Specify a CCTCertInfo object for the certificate, a TBool object to decide if the certificate is to be trusted (ETrue if trusted and EFalse if not) and a request status object that will contain the result of the trust setting operation when complete. Pass these as parameters to the CUnifiedCertStore::SetTrust() function and apply the trust settings.

The following code snippet explains how to set the applicability and trust settings for a certificate:

//Create and initialize the Unified Certificate Store
.
.
.

//Parameters for applicability and trust settings 

RArray<TUid> iApplications; //The applicability settings
TBool iTrustStatus = ETrue; //The trust setting

//Set Applicability

//iCertInfo is a CCTCertInfo object that points to the certificate whose applicability and trust settings are to be updated

iCertStore->SetApplicability(iCertInfo, iApplications, iStatus); 

//Set Trust

iCertStore->SetTrust(iCertInfo, iTrustStatus, iStatus);

Getting applicability and trust settings

You can determine whether a certificate is trusted as well as get a list of application UIDs for a certificate. The details are as follows:

• Get applicability: Specify a CCTCertInfo object for the certificate, an array for containing applicability settings (Application UIDs pertaining to the certificate) and a request status object that will contain the result of getting the applicability settings when the operation is complete. Pass these as parameters to the CUnifiedCertStore::Applications() function.

• Get trust: Specify a CCTCertInfo object for the certificate, a TBool object that returns the trust status of the certificate (ETrue if trusted and EFalse if not) and a request status object that will contain the trust settings. Pass these as parameters to the CUnifiedCertStore::Trusted() function.

The following code snippet explains how to get the applicability and trust settings for a certificate:

//Create and initialize the Unified Certificate Store
.
.
.
//Get Applicability

//iCertInfo is a CCTCertInfo object that points to the certificate whose applicability and trust settings are to be updated
//iApplications is an RArray<TUid> that returns the application UIDs for the certificate

iCertStore->Applications(iCertInfo, iApplications, iStatus); 

//Get Trust
//iTrustStatus is a TBool returns the trust status of a certificate

iCertStore->Trusted(iCertInfo, iTrustStatus, iStatus);