<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept id="GUID-B946BDF0-C5D8-57E2-9D05-7BE134AD032E" xml:lang="en"><title>Unified

Certificate Store Tutorial</title><shortdesc>The Unified Certificate Store is the single point of access for

client applications to access and manipulate certificate stores in the device.

This tutorial provides information on how you can use the Unified Certificate

Store to perform various certificate-manipulation operations. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<section><title>Procedure</title> <p>Follow these steps to perform the various

certificate manipulation operations using the Unified Certificate Store: </p> <ol id="GUID-FF80C823-255E-5EF6-B433-A56190C80A8F">

<li id="GUID-B9D2FEBD-776E-5940-94CC-FDFF775DF1E6"><p>Create an instance of

the Unified Certificate Store and initialize it. </p> <p>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. </p> <p>The following steps explain the processing

of creating and initialising a Unified Certificate Store: </p> <ol id="GUID-99B8E435-FDCF-5D5A-B15F-2685B18D6E4B">

<li id="GUID-9B955334-F229-54B4-8F48-039AAED1685C"><p>Create an instance of

the <codeph>RFs</codeph> class. Use the object created as a file system session. </p> </li>

<li id="GUID-53BDC7C5-1380-53E3-840F-61E7BAB0BD53"><p>Create an object of

type <codeph>CUnifiedCertStore</codeph> using <xref href="GUID-AD63C29A-17C3-375C-840F-42A92422300D.dita#GUID-AD63C29A-17C3-375C-840F-42A92422300D/GUID-FB4204E6-EEB5-3C8E-9938-5466C8AA318E"><apiname>CUnifiedCertStore::NewL()</apiname></xref> or <xref href="GUID-AD63C29A-17C3-375C-840F-42A92422300D.dita#GUID-AD63C29A-17C3-375C-840F-42A92422300D/GUID-E66689D6-82C9-33B5-8CB6-7CE40EBAFF4E"><apiname>CUnifiedCertStore::NewLC()</apiname></xref>. </p> <p> <b>Note:</b>  </p> <p>The value that you set for the Boolean variable <codeph>aOpenForWrite</codeph> decides

if you can open the certificate store in read-only or writable mode. Set the

value of the variable to: </p> <ul>

<li id="GUID-FF0DA388-7DFC-504A-9C0F-AAB32F44C6D3"><p> <codeph>ETrue</codeph> to

open the certificate store with write access. </p> </li>

<li id="GUID-F1DF4204-DE2A-59B6-BB85-E65BFED1A929"><p> <codeph>EFalse</codeph> to

open the certificate store with read-only access. </p> </li>

</ul> </li>

<li id="GUID-C158790B-DE2D-52DC-A387-90961DC77F4B"><p>Initialize the certificate

store and the member functions using the asynchronous function <xref href="GUID-AD63C29A-17C3-375C-840F-42A92422300D.dita#GUID-AD63C29A-17C3-375C-840F-42A92422300D/GUID-949ACD5A-756A-356A-8DC5-462FBDFB0B95"><apiname>CUnifiedCertStore::Initialize()</apiname></xref>. </p> </li>

</ol> <p>The code snippet to create and initialize a Unified Certificate Store

is as follows: </p> <codeblock id="GUID-9DE1EB37-DDFE-5D22-9A3B-ADE97CBD4A5D" xml:space="preserve">

//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); 

</codeblock> </li>

<li id="GUID-ED591EC4-417B-5D57-BA41-3B4F8C97D2D6"><p>Complete any of the

following tasks as per your requirement: </p> <ul>

<li id="GUID-E5BFB9AB-1754-5D58-84E2-49395DC2A87D"><p><xref href="GUID-B946BDF0-C5D8-57E2-9D05-7BE134AD032E.dita#GUID-B946BDF0-C5D8-57E2-9D05-7BE134AD032E/GUID-A9389658-0ECD-59BA-A602-C528767456D5">Adding certificates</xref>  </p> </li>

<li id="GUID-99C0B5EC-8204-522A-94EC-08D06BB00C1D"><p><xref href="GUID-B946BDF0-C5D8-57E2-9D05-7BE134AD032E.dita#GUID-B946BDF0-C5D8-57E2-9D05-7BE134AD032E/GUID-2842C30A-579C-5E1A-8307-7AFF399BCCDE">Removing certificates</xref>  </p> </li>

<li id="GUID-1DCEFAE8-36AF-50AB-B925-FBBB6E35DCA4"><p><xref href="GUID-B946BDF0-C5D8-57E2-9D05-7BE134AD032E.dita#GUID-B946BDF0-C5D8-57E2-9D05-7BE134AD032E/GUID-7C74D0F9-25A3-5FDE-9FF1-EB865A31535E">Finding certificates</xref>  </p> </li>

<li id="GUID-AAB713A9-450A-5ADF-8B4D-852BF418E2C0"><p><xref href="GUID-B946BDF0-C5D8-57E2-9D05-7BE134AD032E.dita#GUID-B946BDF0-C5D8-57E2-9D05-7BE134AD032E/GUID-42C7CD98-4617-57D2-8331-C0A05DF7F7E7">Retrieving certificate as a parsed object</xref>  </p> </li>

<li id="GUID-61C6704B-4A88-5FD4-90D5-310BF7D98180"><p><xref href="GUID-B946BDF0-C5D8-57E2-9D05-7BE134AD032E.dita#GUID-B946BDF0-C5D8-57E2-9D05-7BE134AD032E/GUID-1F1F9608-C387-5597-8041-AB1BC1F65992">Retrieving certificate details</xref>  </p> </li>

<li id="GUID-71FD55FF-2619-59B0-8F96-13AFDABC0E4E"><p><xref href="GUID-B946BDF0-C5D8-57E2-9D05-7BE134AD032E.dita#GUID-B946BDF0-C5D8-57E2-9D05-7BE134AD032E/GUID-DD7D5D55-A2F1-54FB-AA38-B4A7C920B6A6"> Managing applicability and trust settings for certificates</xref>  </p> </li>

</ul> </li>

</ol> </section>

<section id="GUID-A9389658-0ECD-59BA-A602-C528767456D5"><title>Adding certificates</title> <p>Before

adding a certificate, it is essential to determine the certificate store to

which the certificate will be added. </p> <p>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: </p> <ol id="GUID-B4CC2EBE-BCCC-5BC3-B0B1-88B9086A8D7E">

<li id="GUID-33EF0F8B-C0D0-5E34-9FB6-0EC694D6F8C0"><p>Create an object of

a writable certificate store using <xref href="GUID-135A2547-5D64-3223-82DC-8133F8FEAD37.dita"><apiname>MCTWritableCertStore</apiname></xref> and

retrieve the certificate store to which the certificate will be added. </p> </li>

<li id="GUID-5095B782-EF13-5A92-B025-DFA523A5E638"><p>Specify the details

of the certificate to be added and include it to the selected store using <xref href="GUID-135A2547-5D64-3223-82DC-8133F8FEAD37.dita#GUID-135A2547-5D64-3223-82DC-8133F8FEAD37/GUID-0913D6AB-35ED-3525-BDD1-11C93514C5F5"><apiname>MCTWritableCertStore::Add()</apiname></xref>. </p> </li>

</ol> <p>The following code snippet explains how to add a certificate to the

certificate store: </p> <codeblock id="GUID-EFE9F14D-15CE-5977-A1B1-B2DCB1241C69" xml:space="preserve">

//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); 

</codeblock> </section>

<section id="GUID-2842C30A-579C-5E1A-8307-7AFF399BCCDE"><title>Removing certificates</title> <p>Specify

details of the certificate to be removed and then remove it from the certificate

store. The following steps provide the require details: </p> <ol id="GUID-C3D2E9DF-8CFA-5F23-A620-DCDE2EE49D44">

<li id="GUID-C55FC085-7037-5447-BBF4-A69EE77B0055"><p>Create an object of

a writable certificate store using <xref href="GUID-135A2547-5D64-3223-82DC-8133F8FEAD37.dita"><apiname>MCTWritableCertStore</apiname></xref> and

retrieve the certificate store from which the certificate will be removed. </p> </li>

<li id="GUID-9E4DE5E2-E0D1-5ED2-8415-B0B44C54A424"><p>Create a <codeph>CCTCertInfo</codeph> object

of the certificate to be removed. Pass this to the <xref href="GUID-AD63C29A-17C3-375C-840F-42A92422300D.dita#GUID-AD63C29A-17C3-375C-840F-42A92422300D/GUID-C5782446-6A63-32E7-A4CE-1DDC4F8AC5CB"><apiname>CUnifiedCertStore::Remove()</apiname></xref> function

to remove the particular certificate from the certificate store. </p> </li>

</ol> <p>The following code snippet explains how to remove a certificate from

the certificate store: </p> <codeblock id="GUID-721E6910-928F-52E4-B7A5-F281D9947539" xml:space="preserve">

//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);

</codeblock> </section>

<section id="GUID-7C74D0F9-25A3-5FDE-9FF1-EB865A31535E"><title>Finding certificates</title> <p>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: </p> <ol id="GUID-C7E944A0-9B0C-58E0-A2D8-15CEA6369B76">

<li id="GUID-B7170624-BA1B-58A5-B52D-DDDA55B02494"><p>Specify a filter object

for the certificates to be returned. </p> </li>

<li id="GUID-63746FE1-B1D8-593D-8262-5F27635E7EEA"><p>Specify the filter criteria

for returning a specific category of certificates. </p> </li>

<li id="GUID-246E4834-0C0E-5721-BE8D-01B7B688BC1A"><p>Use the <xref href="GUID-AD63C29A-17C3-375C-840F-42A92422300D.dita#GUID-AD63C29A-17C3-375C-840F-42A92422300D/GUID-F88680D5-737A-3BF5-98E4-1BAD101A6B1C"><apiname>CUnifiedCertStore::List()</apiname></xref> function

to list the filtered certificates. </p> </li>

</ol> <p>The following code snippet explains how to find certificates in a

certificate store: </p> <codeblock id="GUID-FC4077EB-0B5A-5832-BA3F-1EA9CAA80BC5" xml:space="preserve">

//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);

</codeblock> </section>

<section id="GUID-42C7CD98-4617-57D2-8331-C0A05DF7F7E7"><title>Retrieving

certificate as a parsed object</title> <p>You can retrieve a certificate as

a parsed object only in case of <xref href="GUID-C676C4E6-93AF-59E9-886D-74D59F154490.dita">X.509</xref> or

Wireless Transport Layer Security (WTLS) certificates. This method of retrieval

does not work for URL certificates. </p> <p>Use the <xref href="GUID-AD63C29A-17C3-375C-840F-42A92422300D.dita#GUID-AD63C29A-17C3-375C-840F-42A92422300D/GUID-DE63711C-95CA-3C92-B406-3BEF04184866"><apiname>CUnifiedCertStore::Retrieve()</apiname></xref> function

to retrieve the certificate as a parsed object. </p> <p>The following code

snippet explains how to retrieve a certificate as a parsed object: </p> <codeblock id="GUID-233AA2D2-5A2B-5F29-8C30-79C2AB821C8A" xml:space="preserve">

//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);

</codeblock> </section>

<section id="GUID-1F1F9608-C387-5597-8041-AB1BC1F65992"><title>Retrieving

certificate details</title> <p>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. </p> <p>Use the <xref href="GUID-AD63C29A-17C3-375C-840F-42A92422300D.dita#GUID-AD63C29A-17C3-375C-840F-42A92422300D/GUID-DE63711C-95CA-3C92-B406-3BEF04184866"><apiname>CUnifiedCertStore::Retrieve()</apiname></xref> 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. </p> <p>The

following code snippet explains how to retrieve details of a specific certificate: </p> <codeblock id="GUID-7D781666-11BF-5BAF-A642-F5C02C79E0E7" xml:space="preserve">

//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); 

</codeblock> </section>

<section id="GUID-DD7D5D55-A2F1-54FB-AA38-B4A7C920B6A6"><title>Managing applicability

and trust settings</title> <p>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. </p> <p>The Unified Certificate Store

API provides the following functions to get and set the applicability and

trust settings for certificates: </p> <table id="GUID-B1E90AB7-D5AF-5DC2-AC8C-13922449A1A7">

<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>

<thead>

<row>

<entry>Function</entry>

<entry>Description</entry>

</row>

</thead>

<tbody>

<row>

<entry><p> <codeph>Applications()</codeph>  </p> </entry>

<entry><p>Gets a list of application UIDs for a certificate </p> </entry>

</row>

<row>

<entry><p> <codeph> IsApplicable()</codeph>  </p> </entry>

<entry><p>Determines whether a certificate has a specific application UID </p> </entry>

</row>

<row>

<entry><p> <codeph> Trusted()</codeph>  </p> </entry>

<entry><p>Determines whether a certificate is trusted </p> </entry>

</row>

<row>

<entry><p> <codeph>SetApplicability()</codeph>  </p> </entry>

<entry><p>Sets the list of application UIDs </p> </entry>

</row>

<row>

<entry><p> <codeph>SetTrust() </codeph>  </p> </entry>

<entry><p>Sets the trust flag. </p> </entry>

</row>

</tbody>

</tgroup>

</table> <p><b>Setting applicability and trust settings</b> </p> <p>You can

change the existing applicability and trust settings of a certificate. The

details are as follows: </p> <ul>

<li id="GUID-97330D30-CE30-5B54-9E8D-54DDCB469BC4"><p> <b>Set applicability:</b> Specify

a <codeph>CCTCertInfo</codeph> 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 <xref href="GUID-AD63C29A-17C3-375C-840F-42A92422300D.dita#GUID-AD63C29A-17C3-375C-840F-42A92422300D/GUID-2A38AD3B-A04A-3382-858A-232E4BD64207"><apiname>CUnifiedCertStore::SetApplicability()</apiname></xref> function

and apply the settings. </p> </li>

<li id="GUID-783FF55B-65EF-5ED3-BE18-DAE1E596EA79"><p> <b>Set trust: </b> Specify

a <codeph>CCTCertInfo</codeph> object for the certificate, a <codeph>TBool</codeph> object

to decide if the certificate is to be trusted (<codeph>ETrue</codeph> if trusted

and <codeph>EFalse</codeph> 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 <xref href="GUID-AD63C29A-17C3-375C-840F-42A92422300D.dita#GUID-AD63C29A-17C3-375C-840F-42A92422300D/GUID-96640E22-0F69-3053-A609-4708AE3E6559"><apiname>CUnifiedCertStore::SetTrust()</apiname></xref> function

and apply the trust settings. </p> </li>

</ul> <p>The following code snippet explains how to set the applicability

and trust settings for a certificate: </p> <codeblock id="GUID-11E65DD8-F148-5241-8C9C-693E076973C0" xml:space="preserve">

//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);

</codeblock> <p><b>Getting applicability and trust settings</b> </p> <p>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: </p> <ul>

<li id="GUID-0083812D-C352-5BB3-A4FD-09A10FBB7375"><p> <b>Get applicability:</b> Specify

a <codeph>CCTCertInfo</codeph> 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 <xref href="GUID-AD63C29A-17C3-375C-840F-42A92422300D.dita#GUID-AD63C29A-17C3-375C-840F-42A92422300D/GUID-7B518009-7848-30FB-BE52-7F38E3C88C59"><apiname>CUnifiedCertStore::Applications()</apiname></xref> function. </p> </li>

<li id="GUID-1FD626D2-965C-5CBC-AD13-6D8DA90F065D"><p> <b>Get trust:</b> Specify

a <codeph>CCTCertInfo</codeph> object for the certificate, a <codeph>TBool</codeph> object

that returns the trust status of the certificate (<codeph>ETrue</codeph> if

trusted and <codeph>EFalse</codeph> if not) and a request status object that

will contain the trust settings. Pass these as parameters to the <xref href="GUID-AD63C29A-17C3-375C-840F-42A92422300D.dita#GUID-AD63C29A-17C3-375C-840F-42A92422300D/GUID-183B8E74-1F85-380D-B69C-0303FD4B9A1C"><apiname>CUnifiedCertStore::Trusted()</apiname></xref> function. </p> </li>

</ul> <p>The following code snippet explains how to get the applicability

and trust settings for a certificate: </p> <codeblock id="GUID-309E1640-E00E-59CF-A4B3-17FC0C8AE3C7" xml:space="preserve">

//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);

</codeblock> </section>

</conbody><related-links>

<link href="GUID-037225BC-AC45-540E-A899-1B8AB9112D6E.dita"><linktext>Unified Certificate

Store Overview</linktext></link>

</related-links></concept>