|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <concept id="GUID-2800C486-2FB4-5C5C-990F-CC1A290F7E0C" xml:lang="en"><title>Root |
|
13 Certificates</title><shortdesc>To validate a certificate, a client application must have at least |
|
14 one certificate which it directly trusts. This is a root certificate. Different |
|
15 applications trust different root certificates. For example, TLS might trust |
|
16 VeriSign's secure server root, but Software Install may not. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
17 <section><title>Root Certificate Management and Storage</title> <p><b>The |
|
18 file certificate store</b> </p> <p>There is a single 'file' certificate store |
|
19 (certstore), <filepath>CACerts.dat</filepath>, initially populated with default |
|
20 root certificates, located in <filepath>c:\system\data\</filepath> (or a private |
|
21 directory). When a certstore object is constructed it looks for the store |
|
22 in this location. If it cannot be found the original store is copied over |
|
23 from ROM. </p> <p>A certificate is marked with zero or more UIDs, each of |
|
24 which identifies an application that trusts this certificate. These can be |
|
25 edited and the resulting entry put back in the store, this changes the trust |
|
26 settings for that certificate. </p> <p><b>The certificate applications store</b> </p> <p>The |
|
27 certificate applications (certapps) store, <filepath>certclients.dat</filepath>, |
|
28 which is used by the file certstore, contains a set of zero or more clients. |
|
29 Each client consists of a UID and a human-readable name, and represents an |
|
30 application that requires the services of Certificate Management (certman). |
|
31 For example, TLS is a client, as is Software Installation. The word 'application' |
|
32 is used in its broadest possible sense; the UIDs do not have to be Symbian |
|
33 platform application UIDs, although this may be a sensible choice. Each certificate |
|
34 is marked as trusted by zero or more of these clients, this is what makes |
|
35 it a root certificate for that application. </p> <p>The <codeph>CCertificateAppInfoManager</codeph> class |
|
36 (<xref href="GUID-2800C486-2FB4-5C5C-990F-CC1A290F7E0C.dita#GUID-2800C486-2FB4-5C5C-990F-CC1A290F7E0C/GUID-10C59313-821D-5AC4-8E45-1650F6305C7A">see |
|
37 below</xref>) provides functions to add, remove and list these UID/name pairs. |
|
38 A certman application can retrieve the UID/name pairs for all clients of Certificate |
|
39 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> |
|
40 <section id="GUID-5B7437DC-D8FD-59E3-B15E-4A16B75991E7"><title>Client registration</title> <p>Clients |
|
41 that use certificates register with certificate storage by providing a UID |
|
42 and a name. To reiterate, each certificate is marked with zero or more of |
|
43 these UIDs, indicating that it is trusted by that particular application. |
|
44 This enables a client(s) to mark a certificate as being trusted for use by |
|
45 a particular program. </p> <p>In practice, known applications that use certification, |
|
46 such as a web browser or the software installer, will already be registered. |
|
47 Currently, the following applications/UIDs are defined: </p> <table id="GUID-B5783775-6FB4-50A0-AA29-D25D5D27C953"> |
|
48 <tgroup cols="3"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/> |
|
49 <thead> |
|
50 <row> |
|
51 <entry>Client/Application name </entry> |
|
52 <entry>UID</entry> |
|
53 <entry>Description</entry> |
|
54 </row> |
|
55 </thead> |
|
56 <tbody> |
|
57 <row> |
|
58 <entry><p>SWInstall </p> </entry> |
|
59 <entry><p> <codeph>268452523</codeph>, <codeph>0X100042AB</codeph> </p> </entry> |
|
60 <entry><p>Certificate is suitable for software installation (SIS files) </p> </entry> |
|
61 </row> |
|
62 <row> |
|
63 <entry><p>SWInstallOCSP </p> </entry> |
|
64 <entry><p> <codeph>268478646</codeph>, <codeph>0X1000A8B6</codeph> </p> </entry> |
|
65 <entry><p>Certificate is suitable for OCSP checking (SIS files) </p> </entry> |
|
66 </row> |
|
67 <row> |
|
68 <entry><p>TLS/SSL </p> </entry> |
|
69 <entry><p> <codeph>268441661</codeph>, <codeph>0X1000183D</codeph> </p> </entry> |
|
70 <entry><p>Certificate is suitable for SSL/TLS server authentication. </p> </entry> |
|
71 </row> |
|
72 </tbody> |
|
73 </tgroup> |
|
74 </table> <p>These UIDs are stored in <filepath>certclients.dat</filepath>; |
|
75 see the <xref href="GUID-2800C486-2FB4-5C5C-990F-CC1A290F7E0C.dita#GUID-2800C486-2FB4-5C5C-990F-CC1A290F7E0C/GUID-ABB767AE-0595-5EAE-8DBF-73538CFA756B">Location |
|
76 of the certstore and certapps store</xref> section below. </p> <p>An application |
|
77 using the certificate validation interface needs to supply the appropriate |
|
78 UID to the certificate validation object, which uses this to select the subset |
|
79 of certificates that are trusted by that application: these form the set of |
|
80 'candidate' root certificates. </p> <p>For a client to work with certificate |
|
81 validation, it needs: </p> <ul> |
|
82 <li id="GUID-EBAFF1BD-3771-5BF9-9620-1CDF0A1BA1B6"><p>an entry for the application |
|
83 added to the list of clients </p> </li> |
|
84 <li id="GUID-E9EF1284-5AFD-55D1-81C2-E29A14CE4088"><p>any needed certificates |
|
85 added to the store </p> </li> |
|
86 <li id="GUID-83A6F618-0290-5976-AB5E-5DAF16C089B3"><p>any of the above certificates |
|
87 marked as trusted by the client. </p> </li> |
|
88 </ul> <p id="GUID-10C59313-821D-5AC4-8E45-1650F6305C7A"><b>CCertificateAppInfoManager</b> </p> <p>The <codeph>CCertificateAppInfoManager</codeph> class |
|
89 provides the following functions for client registration: </p> <ul> |
|
90 <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"> |
|
91 IMPORT_C void AddL(const TCertificateAppInfo& aClient); |
|
92 </codeblock> <p>Leaves with <codeph>KErrPermissionDenied</codeph> if the caller |
|
93 does not have the required capability </p> </li> |
|
94 <li id="GUID-AA763F58-D7C6-563E-B9EA-2BF69F6D18C8"><p> <b>Remove an existing |
|
95 client</b> </p> <codeblock id="GUID-83C72B54-C3FD-567D-A15A-C2719C011B43" xml:space="preserve"> |
|
96 IMPORT_C void RemoveL(const TUid& aUid); |
|
97 </codeblock> <p>Leaves with <codeph>KErrNotFound</codeph> if the client does |
|
98 not exist, and <codeph>KErrPermissionDenied</codeph> if the caller does not |
|
99 have the required capability </p> </li> |
|
100 <li id="GUID-B176271E-9B77-5A80-B00F-6F5ABDA951D1"><p> <b>List the registered |
|
101 clients</b> </p> <codeblock id="GUID-6ABD5D35-C336-5AD0-9930-B6D679922AD0" xml:space="preserve">IMPORT_C const RArray<TCertificateAppInfo>& Applications() const; |
|
102 </codeblock> <p>The returned array becomes the property of the caller who |
|
103 is responsible for its destruction. </p> </li> |
|
104 </ul> <p>When a certificate is added to the certstore it is added along with |
|
105 a set of trusters: this set can be edited subsequently. Then, when clients |
|
106 retrieve sets of certificates they can parameterise the request with a set |
|
107 of trusters, and only certificates trusted by those trusters will be retrieved. |
|
108 See the sections on adding and retrieving certificates in the <xref href="GUID-B946BDF0-C5D8-57E2-9D05-7BE134AD032E.dita">Unified |
|
109 Certificate Store Tutorial</xref>. </p> <p id="GUID-22FECC82-EFF6-5F89-B730-569350B6CE68"><b>TCertificateAppInfo </b> </p> <p>This |
|
110 simple class consists of a UID and a name. The UID does not have to be the |
|
111 application UID, but must be unique; it is anticipated that this can be ensured |
|
112 through the standard UID allocation scheme. Certificate storage does not check |
|
113 UIDs for uniqueness. </p> <codeblock id="GUID-7BA95F3B-F481-565D-BECE-09AFD138A16D" xml:space="preserve"> |
|
114 IMPORT_C TCertManClientInfo(const TUid& aUid, const TName& aName); |
|
115 IMPORT_C TCertificateAppInfo(const TUid& aUid, const TName& aName); |
|
116 |
|
117 IMPORT_C const TUid& Id() const; |
|
118 IMPORT_C const TUid& Id() const; |
|
119 |
|
120 IMPORT_C const TName& Name() const; |
|
121 IMPORT_C const TName& Name() const; |
|
122 </codeblock> </section> |
|
123 <section id="GUID-ABB767AE-0595-5EAE-8DBF-73538CFA756B"><title>Location of |
|
124 the certstore and certapps store</title> <ul> |
|
125 <li id="GUID-979A23A2-F25E-59A3-9D40-8BDBCA703BCF"><p>Certificates are stored, |
|
126 along with suitable trust settings, in a file called <filepath>CACerts.dat</filepath> </p> </li> |
|
127 <li id="GUID-D0D209BC-5717-5746-890D-895267515512"><p>Clients (certificate |
|
128 applications, or UID/name pairs) are stored in a separate file called <filepath>certclients.dat</filepath> </p> </li> |
|
129 </ul> <p>These files are located in ROM on a phone. They are necessary for |
|
130 applications such as Software Install and SSL/TLS. </p> <p>On a cold boot |
|
131 the store is copied over to <filepath>system\data</filepath> (or, in Symbian |
|
132 OS v9.0, to a private directory) on the device's internal RAM drive. Subsequently, |
|
133 certificate storage will look for the store on that hardcoded path. If the |
|
134 store can't be found there, the original will be copied from ROM. </p> </section> |
|
135 </conbody><related-links> |
|
136 <link href="GUID-A3B58436-07E4-565B-800B-86435D205461.dita"><linktext>Certificate |
|
137 Validation in PKIX</linktext></link> |
|
138 </related-links></concept> |