<?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-2800C486-2FB4-5C5C-990F-CC1A290F7E0C" xml:lang="en"><title>Root
Certificates</title><shortdesc>To validate a certificate, a client application must have at least
one certificate which it directly trusts. This is a root certificate. Different
applications trust different root certificates. For example, TLS might trust
VeriSign's secure server root, but Software Install may not. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<section id="GUID-F57DDD2B-16B7-44DC-94DE-10512A765AF2"><title>Root Certificate Management and Storage</title> <p><b>The
file certificate store</b> </p> <p>There is a single 'file' certificate store
(certstore), <filepath>CACerts.dat</filepath>, initially populated with default
root certificates, located in <filepath>c:\system\data\</filepath> (or a private
directory). When a certstore object is constructed it looks for the store
in this location. If it cannot be found the original store is copied over
from ROM. </p> <p>A certificate is marked with zero or more UIDs, each of
which identifies an application that trusts this certificate. These can be
edited and the resulting entry put back in the store, this changes the trust
settings for that certificate. </p> <p><b>The certificate applications store</b> </p> <p>The
certificate applications (certapps) store, <filepath>certclients.dat</filepath>,
which is used by the file certstore, contains a set of zero or more clients.
Each client consists of a UID and a human-readable name, and represents an
application that requires the services of Certificate Management (certman).
For example, TLS is a client, as is Software Installation. The word 'application'
is used in its broadest possible sense; the UIDs do not have to be the Symbian
platform application UIDs, although this may be a sensible choice. Each certificate
is marked as trusted by zero or more of these clients, this is what makes
it a root certificate for that application. </p> <p>The <codeph>CCertificateAppInfoManager</codeph> class
(<xref href="GUID-2800C486-2FB4-5C5C-990F-CC1A290F7E0C.dita#GUID-2800C486-2FB4-5C5C-990F-CC1A290F7E0C/GUID-10C59313-821D-5AC4-8E45-1650F6305C7A">see
below</xref>) provides functions to add, remove and list these UID/name pairs.
A certman application can retrieve the UID/name pairs for all clients of Certificate
Management. The <codeph>TCertificateAppInfo</codeph> class (<xref href="GUID-2800C486-2FB4-5C5C-990F-CC1A290F7E0C.dita#GUID-2800C486-2FB4-5C5C-990F-CC1A290F7E0C/GUID-22FECC82-EFF6-5F89-B730-569350B6CE68">see below</xref>) encapsulates the UID/name pairs. </p> </section>
<section id="GUID-5B7437DC-D8FD-59E3-B15E-4A16B75991E7"><title>Client registration</title> <p>Clients
that use certificates register with certificate storage by providing a UID
and a name. To reiterate, each certificate is marked with zero or more of
these UIDs, indicating that it is trusted by that particular application.
This enables a client(s) to mark a certificate as being trusted for use by
a particular program. </p> <p>In practice, known applications that use certification,
such as a web browser or the software installer, will already be registered.
Currently, the following applications/UIDs are defined: </p> <table id="GUID-B5783775-6FB4-50A0-AA29-D25D5D27C953">
<tgroup cols="3"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/>
<thead>
<row>
<entry>Client/Application name </entry>
<entry>UID</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><p>SWInstall </p> </entry>
<entry><p> <codeph>268452523</codeph>, <codeph>0X100042AB</codeph>  </p> </entry>
<entry><p>Certificate is suitable for software installation (SIS files) </p> </entry>
</row>
<row>
<entry><p>SWInstallOCSP </p> </entry>
<entry><p> <codeph>268478646</codeph>, <codeph>0X1000A8B6</codeph>  </p> </entry>
<entry><p>Certificate is suitable for OCSP checking (SIS files) </p> </entry>
</row>
<row>
<entry><p>TLS/SSL </p> </entry>
<entry><p> <codeph>268441661</codeph>, <codeph>0X1000183D</codeph>  </p> </entry>
<entry><p>Certificate is suitable for SSL/TLS server authentication. </p> </entry>
</row>
</tbody>
</tgroup>
</table> <p>These UIDs are stored in <filepath>certclients.dat</filepath>;
see the <xref href="GUID-2800C486-2FB4-5C5C-990F-CC1A290F7E0C.dita#GUID-2800C486-2FB4-5C5C-990F-CC1A290F7E0C/GUID-ABB767AE-0595-5EAE-8DBF-73538CFA756B">Location
of the certstore and certapps store</xref> section below. </p> <p>An application
using the certificate validation interface needs to supply the appropriate
UID to the certificate validation object, which uses this to select the subset
of certificates that are trusted by that application: these form the set of
'candidate' root certificates. </p> <p>For a client to work with certificate
validation, it needs: </p> <ul>
<li id="GUID-EBAFF1BD-3771-5BF9-9620-1CDF0A1BA1B6"><p>an entry for the application
added to the list of clients </p> </li>
<li id="GUID-E9EF1284-5AFD-55D1-81C2-E29A14CE4088"><p>any needed certificates
added to the store </p> </li>
<li id="GUID-83A6F618-0290-5976-AB5E-5DAF16C089B3"><p>any of the above certificates
marked as trusted by the client. </p> </li>
</ul> <p id="GUID-10C59313-821D-5AC4-8E45-1650F6305C7A"><b>CCertificateAppInfoManager</b> </p> <p>The <codeph>CCertificateAppInfoManager</codeph> class
provides the following functions for client registration: </p> <ul>
<li id="GUID-EE258CCA-E411-5D3E-8777-E03405F6B203"><p> <b>Add a new client</b>  </p> <codeblock id="GUID-B17F0BF0-6539-5F96-A4D1-419518D4FCD8" xml:space="preserve">
IMPORT_C void AddL(const TCertificateAppInfo&amp; aClient);
</codeblock> <p>Leaves with <codeph>KErrPermissionDenied</codeph> if the caller
does not have the required capability </p> </li>
<li id="GUID-AA763F58-D7C6-563E-B9EA-2BF69F6D18C8"><p> <b>Remove an existing
client</b>  </p> <codeblock id="GUID-83C72B54-C3FD-567D-A15A-C2719C011B43" xml:space="preserve">
IMPORT_C void RemoveL(const TUid&amp; aUid);
</codeblock> <p>Leaves with <codeph>KErrNotFound</codeph> if the client does
not exist, and <codeph>KErrPermissionDenied</codeph> if the caller does not
have the required capability </p> </li>
<li id="GUID-B176271E-9B77-5A80-B00F-6F5ABDA951D1"><p> <b>List the registered
clients</b>  </p> <codeblock id="GUID-6ABD5D35-C336-5AD0-9930-B6D679922AD0" xml:space="preserve">IMPORT_C const RArray&lt;TCertificateAppInfo&gt;&amp; Applications() const;
</codeblock> <p>The returned array becomes the property of the caller who
is responsible for its destruction. </p> </li>
</ul> <p>When a certificate is added to the certstore it is added along with
a set of trusters: this set can be edited subsequently. Then, when clients
retrieve sets of certificates they can parameterise the request with a set
of trusters, and only certificates trusted by those trusters will be retrieved.
See the sections on adding and retrieving certificates in the <xref href="GUID-B946BDF0-C5D8-57E2-9D05-7BE134AD032E.dita">Unified
Certificate Store Tutorial</xref>. </p> <p id="GUID-22FECC82-EFF6-5F89-B730-569350B6CE68"><b>TCertificateAppInfo </b> </p> <p>This
simple class consists of a UID and a name. The UID does not have to be the
application UID, but must be unique; it is anticipated that this can be ensured
through the standard UID allocation scheme. Certificate storage does not check
UIDs for uniqueness. </p> <codeblock id="GUID-7BA95F3B-F481-565D-BECE-09AFD138A16D" xml:space="preserve">
IMPORT_C TCertManClientInfo(const TUid&amp; aUid, const TName&amp; aName);
IMPORT_C TCertificateAppInfo(const TUid&amp; aUid, const TName&amp; aName);

IMPORT_C const TUid&amp; Id() const;
IMPORT_C const TUid&amp; Id() const;

IMPORT_C const TName&amp; Name() const;
IMPORT_C const TName&amp; Name() const;
</codeblock> </section>
<section id="GUID-ABB767AE-0595-5EAE-8DBF-73538CFA756B"><title>Location of
the certstore and certapps store</title> <ul>
<li id="GUID-979A23A2-F25E-59A3-9D40-8BDBCA703BCF"><p>Certificates are stored,
along with suitable trust settings, in a file called <filepath>CACerts.dat</filepath>  </p> </li>
<li id="GUID-D0D209BC-5717-5746-890D-895267515512"><p>Clients (certificate
applications, or UID/name pairs) are stored in a separate file called <filepath>certclients.dat</filepath>  </p> </li>
</ul> <p>These files are located in ROM on a phone. They are necessary for
applications such as Software Install and SSL/TLS. </p> <p>On a cold boot
the store is copied over to <filepath>system\data</filepath> (or, in Symbian
OS v9.0, to a private directory) on the device's internal RAM drive. Subsequently,
certificate storage will look for the store on that hardcoded path. If the
store can't be found there, the original will be copied from ROM. </p> </section>
</conbody><related-links>
<link href="GUID-A3B58436-07E4-565B-800B-86435D205461.dita"><linktext>Certificate
Validation in PKIX</linktext></link>
</related-links></concept>