--- a/Symbian3/PDK/Source/GUID-2800C486-2FB4-5C5C-990F-CC1A290F7E0C.dita Thu Mar 11 15:24:26 2010 +0000
+++ b/Symbian3/PDK/Source/GUID-2800C486-2FB4-5C5C-990F-CC1A290F7E0C.dita Thu Mar 11 18:02:22 2010 +0000
@@ -1,138 +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& 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& 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<TCertificateAppInfo>& 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& aUid, const TName& aName);
-IMPORT_C TCertificateAppInfo(const TUid& aUid, const TName& aName);
-
-IMPORT_C const TUid& Id() const;
-IMPORT_C const TUid& Id() const;
-
-IMPORT_C const TName& Name() const;
-IMPORT_C const TName& 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>
+<?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& 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& 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<TCertificateAppInfo>& 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& aUid, const TName& aName);
+IMPORT_C TCertificateAppInfo(const TUid& aUid, const TName& aName);
+
+IMPORT_C const TUid& Id() const;
+IMPORT_C const TUid& Id() const;
+
+IMPORT_C const TName& Name() const;
+IMPORT_C const TName& 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