Week 23 contribution of SDK documentation content. See release notes for details. Fixes bugs Bug 2714, Bug 462.
<?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>