|
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 reference |
|
11 PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd"> |
|
12 <reference id="GUID-C119A79A-D705-50B3-B174-70F517947BBD" xml:lang="en"><title>How |
|
13 certapp Processes Input File Information</title><abstract><p>This section provides information on the guidelines that the <codeph>certapp</codeph> tool |
|
14 follows to process various entities in the input files used to create certificate |
|
15 store files. </p><note> Input text files can be 7-bit text or UTF-8. If a |
|
16 file is UTF-8, it can optionally start with a UTF-8 Byte Order Marker. This |
|
17 is the marker that Windows uses when saving files as UTF-8.</note></abstract><prolog><metadata><keywords/></metadata></prolog><refbody> |
|
18 <section><title>White spaces</title> <p>The <codeph>certapp</codeph> tool |
|
19 ignores white space (space, tab, carriage return and line feed characters) |
|
20 in input files. Instead, the line-ending convention of the platform on which |
|
21 the tool runs is followed. </p> </section> |
|
22 <refsyn><title>Double-quoted strings</title> <p>The <codeph>certapp</codeph> tool |
|
23 treats a series of bytes within double quote characters (in the input files) |
|
24 as a single token. </p> <p>A double quote character can be included in a double-quoted |
|
25 string by preceding it with a back slash, as shown in the following example: </p> <p>This |
|
26 is how you include \” in a double-quoted string. </p> <p>A backslash character |
|
27 can be included in a double quoted string by preceding it with another back |
|
28 slash, as shown in the following example: </p> <p>This is how you include |
|
29 \\ in a double-quoted string. </p> <p>The double quote syntax can be used |
|
30 to set any text field value, such as the certificate label, to any UTF-8 value, |
|
31 including quote characters, spaces, UTF-8 escape sequences and so on. </p> <p><note>UTF-8 |
|
32 values are defined such that a UTF-8 escape sequence never contains a back |
|
33 slash character.</note> </p> </refsyn> |
|
34 <section><title>Enumerated types</title> <p>All enumerated values can be specified |
|
35 as numeric values, though using text values is strongly recommended. </p> </section> |
|
36 <refsyn><title>Numeric values</title> <p>Any numeric value can be entered |
|
37 in decimal as a raw number or in hexadecimal by prefixing the number with |
|
38 0x. </p> </refsyn> |
|
39 <section><title>Capability sets</title> <p>For a certificate, a capability |
|
40 set is a list of capabilities allowed in applications that have the certificate |
|
41 as their trust anchor. Capability set values can be specified as numeric bit |
|
42 offsets (starting from 0), though using text values is strongly recommended, |
|
43 as shown in the following example: </p> <codeblock id="GUID-DAB82140-EDF4-51D8-A483-CD41852C9B19" xml:space="preserve">CapabilitySet {ProtServ DiskAdmin NetworkControl |
|
44 AllFiles SwEvent NetworkServices LocalServices}</codeblock> </section> |
|
45 <section><title>Subject and issuer key identifiers</title> <p>It is recommended |
|
46 that you set the <codeph>SubjectKeyId</codeph> field to an <codeph>auto</codeph> value |
|
47 in the input file for creating the certificate store file. In addition, set |
|
48 the <codeph>IssuerKeyId</codeph> field either to <codeph>auto</codeph> or |
|
49 to an empty octet string. </p> <p>When the <codeph>SubjectKeyId</codeph> and |
|
50 the <codeph>IssuerKeyId</codeph> fields are set to <codeph>auto</codeph> or |
|
51 if you omit setting values for these fields in the input file, the certapp |
|
52 tool performs its own processing to determine their values. The following |
|
53 sub-sections provide the details. </p> <p><b>Setting SubjectKeyId to auto</b> </p> <p>When <codeph>SubjectKeyId</codeph> is |
|
54 set to <codeph>auto</codeph> or if the field is omitted, then the following |
|
55 algorithm is used for determining the value of the field: </p> <ul> |
|
56 <li id="GUID-33035419-FAEC-572A-BA63-C0E49C1C90A3"><p>If the store type is |
|
57 not SWI certificate store, the certificate type is not user, and an X.509 <codeph>SubjectKeyId</codeph> extension |
|
58 with length less than or equal to 20 bytes is present, then this extension |
|
59 is used as the value of the <codeph>SubjectKeyId</codeph> field. </p> </li> |
|
60 <li id="GUID-AE8A59EF-E064-5C12-B9E3-3D99DFCE7F78"><p>Otherwise, the value |
|
61 of the <codeph>SubjectKeyId</codeph> field is calculated based on the certificate’s |
|
62 public key characteristics using a Symbian-specific algorithm. </p> </li> |
|
63 </ul> <p>The <codeph>SubjectKeyId</codeph> field value is stored in the certificate |
|
64 metadata and can be used by applications when querying the certificate store |
|
65 using a filter. </p> <p><b>Setting IssuerKeyId set to auto</b> </p> <p>If |
|
66 the <codeph>IssuerKeyId</codeph> field is set to <codeph>auto</codeph> or |
|
67 if the field is omitted, the following algorithm is used for determining the |
|
68 value of the field: </p> <ul> |
|
69 <li id="GUID-BC5FBF12-E8E8-5AA2-AB0D-FE8D2ACE4220"><p>If the store type is |
|
70 not SWI certificate store, and an X.509 <codeph>AuthorityKeyId</codeph> extension |
|
71 with length less than or equal to 20 bytes is present, then this extension |
|
72 is used as the value of the <codeph>IssuerKeyId</codeph> field. An authority |
|
73 key identifier specifies the public key that is used to sign the certificate. </p> </li> |
|
74 <li id="GUID-143490B1-B30A-57E7-9FB5-C7BA40080966"><p>If a single certificate |
|
75 is present in the certificate store with the subject matching the issuer of |
|
76 the original certificate (for which the <codeph>IssuerKeyId</codeph> is to |
|
77 be set), the <codeph>IssuerKeyId</codeph> is set to the <codeph>SubjectKeyId</codeph> of |
|
78 the matching certificate. </p> <p> <b>Note:</b> </p> <p>When generating <codeph>IssuerKeyId</codeph> values |
|
79 for SWI store certificates, all certificates within the SWI certificate store |
|
80 are considered. When generating values for file certificate store, all certificates |
|
81 in both the SWI certificate store and the file certificate store are considered. </p> </li> |
|
82 <li id="GUID-2153579B-2651-5FF8-A5B6-75BEB59E7B25"><p>Otherwise, the <codeph>IssuerKeyId</codeph> is |
|
83 set to an empty octet string. </p> </li> |
|
84 </ul> <p>The <codeph>IssuerKeyId</codeph> field value is stored in the certificate |
|
85 metadata and can be used by applications when querying the certificate store |
|
86 using a filter. To filter certificates by <codeph>IssuerKeyId</codeph>, set |
|
87 the field to auto, otherwise set it to an empty octet string (for example, |
|
88 ’’). </p> <p> <b>Note:</b> In case of a certificate that is not of type X.509, |
|
89 if you do not set the IssuerKeyId or the SubjectKeyId values to auto or empty |
|
90 octet strings, you can set them to octet strings, as explained in the following |
|
91 sub-sections. </p> <p><b>Setting SubjectKeyId and IssuerKeyId to octet strings</b> </p> <p>Consider |
|
92 the following example of an octet string value to which you can set the <codeph>SubjectKeyId</codeph> field: </p> <codeblock id="GUID-A04C2F3D-E87B-5FDC-BFF3-E39C719761FD" xml:space="preserve">SubjectKeyId ’01:02:43’</codeblock> <p>The <codeph>SubjectKeyId</codeph> field |
|
93 is set to an octet string consisting of the numbers <codeph>0x01</codeph>, <codeph>0x02</codeph> and <codeph>0x03</codeph>. |
|
94 The string can be 0 to 20 bytes long. The length limit is imposed by the certificate |
|
95 store metadata structure, but the usual values are SHA1 hash of certificate |
|
96 fields and hence 20 bytes long. </p></section> |
|
97 </refbody><related-links> |
|
98 <link href="GUID-B1B3C5E6-9F38-5A55-A30E-4C7591B446CC.dita"><linktext>Certificate |
|
99 Store Human-Readable File Formats</linktext></link> |
|
100 </related-links></reference> |