<?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 reference
  PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd">
<reference id="GUID-C119A79A-D705-50B3-B174-70F517947BBD" xml:lang="en"><title>How
certapp Processes Input File Information</title><abstract><p>This section provides information on the guidelines that the <codeph>certapp</codeph> tool
follows to process various entities in the input files used to create certificate
store files. </p><note> Input text files can be 7-bit text or UTF-8. If a
file is UTF-8, it can optionally start with a UTF-8 Byte Order Marker. This
is the marker that Windows uses when saving files as UTF-8.</note></abstract><prolog><metadata><keywords/></metadata></prolog><refbody>
<section><title>White spaces</title> <p>The <codeph>certapp</codeph> tool
ignores white space (space, tab, carriage return and line feed characters)
in input files. Instead, the line-ending convention of the platform on which
the tool runs is followed. </p> </section>
<refsyn><title>Double-quoted strings</title> <p>The <codeph>certapp</codeph> tool
treats a series of bytes within double quote characters (in the input files)
as a single token. </p> <p>A double quote character can be included in a double-quoted
string by preceding it with a back slash, as shown in the following example: </p> <p>This
is how you include \” in a double-quoted string. </p> <p>A backslash character
can be included in a double quoted string by preceding it with another back
slash, as shown in the following example: </p> <p>This is how you include
\\ in a double-quoted string. </p> <p>The double quote syntax can be used
to set any text field value, such as the certificate label, to any UTF-8 value,
including quote characters, spaces, UTF-8 escape sequences and so on. </p> <p><note>UTF-8
values are defined such that a UTF-8 escape sequence never contains a back
slash character.</note> </p> </refsyn>
<section><title>Enumerated types</title> <p>All enumerated values can be specified
as numeric values, though using text values is strongly recommended. </p> </section>
<refsyn><title>Numeric values</title> <p>Any numeric value can be entered
in decimal as a raw number or in hexadecimal by prefixing the number with
0x. </p> </refsyn>
<section><title>Capability sets</title> <p>For a certificate, a capability
set is a list of capabilities allowed in applications that have the certificate
as their trust anchor. Capability set values can be specified as numeric bit
offsets (starting from 0), though using text values is strongly recommended,
as shown in the following example: </p> <codeblock id="GUID-DAB82140-EDF4-51D8-A483-CD41852C9B19" xml:space="preserve">CapabilitySet {ProtServ DiskAdmin NetworkControl 
AllFiles SwEvent NetworkServices LocalServices}</codeblock> </section>
<section><title>Subject and issuer key identifiers</title> <p>It is recommended
that you set the <codeph>SubjectKeyId</codeph> field to an <codeph>auto</codeph> value
in the input file for creating the certificate store file. In addition, set
the <codeph>IssuerKeyId</codeph> field either to <codeph>auto</codeph> or
to an empty octet string. </p> <p>When the <codeph>SubjectKeyId</codeph> and
the <codeph>IssuerKeyId</codeph> fields are set to <codeph>auto</codeph> or
if you omit setting values for these fields in the input file, the certapp
tool performs its own processing to determine their values. The following
sub-sections provide the details. </p> <p><b>Setting SubjectKeyId to auto</b> </p> <p>When <codeph>SubjectKeyId</codeph> is
set to <codeph>auto</codeph> or if the field is omitted, then the following
algorithm is used for determining the value of the field: </p> <ul>
<li id="GUID-33035419-FAEC-572A-BA63-C0E49C1C90A3"><p>If the store type is
not SWI certificate store, the certificate type is not user, and an X.509 <codeph>SubjectKeyId</codeph> extension
with length less than or equal to 20 bytes is present, then this extension
is used as the value of the <codeph>SubjectKeyId</codeph> field. </p> </li>
<li id="GUID-AE8A59EF-E064-5C12-B9E3-3D99DFCE7F78"><p>Otherwise, the value
of the <codeph>SubjectKeyId</codeph> field is calculated based on the certificate’s
public key characteristics using a Symbian-specific algorithm. </p> </li>
</ul> <p>The <codeph>SubjectKeyId</codeph> field value is stored in the certificate
metadata and can be used by applications when querying the certificate store
using a filter. </p> <p><b>Setting IssuerKeyId set to auto</b> </p> <p>If
the <codeph>IssuerKeyId</codeph> field is set to <codeph>auto</codeph> or
if the field is omitted, the following algorithm is used for determining the
value of the field: </p> <ul>
<li id="GUID-BC5FBF12-E8E8-5AA2-AB0D-FE8D2ACE4220"><p>If the store type is
not SWI certificate store, and an X.509 <codeph>AuthorityKeyId</codeph> extension
with length less than or equal to 20 bytes is present, then this extension
is used as the value of the <codeph>IssuerKeyId</codeph> field. An authority
key identifier specifies the public key that is used to sign the certificate. </p> </li>
<li id="GUID-143490B1-B30A-57E7-9FB5-C7BA40080966"><p>If a single certificate
is present in the certificate store with the subject matching the issuer of
the original certificate (for which the <codeph>IssuerKeyId</codeph> is to
be set), the <codeph>IssuerKeyId</codeph> is set to the <codeph>SubjectKeyId</codeph> of
the matching certificate. </p> <p> <b>Note:</b>  </p> <p>When generating <codeph>IssuerKeyId</codeph> values
for SWI store certificates, all certificates within the SWI certificate store
are considered. When generating values for file certificate store, all certificates
in both the SWI certificate store and the file certificate store are considered. </p> </li>
<li id="GUID-2153579B-2651-5FF8-A5B6-75BEB59E7B25"><p>Otherwise, the <codeph>IssuerKeyId</codeph> is
set to an empty octet string. </p> </li>
</ul> <p>The <codeph>IssuerKeyId</codeph> field value is stored in the certificate
metadata and can be used by applications when querying the certificate store
using a filter. To filter certificates by <codeph>IssuerKeyId</codeph>, set
the field to auto, otherwise set it to an empty octet string (for example,
’’). </p> <p> <b>Note:</b> In case of a certificate that is not of type X.509,
if you do not set the IssuerKeyId or the SubjectKeyId values to auto or empty
octet strings, you can set them to octet strings, as explained in the following
sub-sections. </p> <p><b>Setting SubjectKeyId and IssuerKeyId to octet strings</b> </p> <p>Consider
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
is set to an octet string consisting of the numbers <codeph>0x01</codeph>, <codeph>0x02</codeph> and <codeph>0x03</codeph>.
The string can be 0 to 20 bytes long. The length limit is imposed by the certificate
store metadata structure, but the usual values are SHA1 hash of certificate
fields and hence 20 bytes long. </p></section>
</refbody><related-links>
<link href="GUID-B1B3C5E6-9F38-5A55-A30E-4C7591B446CC.dita"><linktext>Certificate
Store Human-Readable File Formats</linktext></link>
</related-links></reference>