--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-2800C486-2FB4-5C5C-990F-CC1A290F7E0C.dita	Thu Jan 21 18:18:20 2010 +0000
@@ -0,0 +1,138 @@
+<?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><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 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>
\ No newline at end of file