Certificate store manipulation with Certtool

Symbian OS provides a certificate store, certstore for short, which is a repository of root and user certificates which can be retrieved and used to accomplish a variety of tasks. The certstore is initially empty. Certtool is a a user-friendly epoc shell program for inserting certificates and manipulating their settings.

This document explains how to manipulate the certstore using certtool. It is of interest to anyone that needs to build, manipulate and maintain a certstore for Symbian OS.

You can use certtool to do the following:

• list the content of a certificate store

• insert and remove certificates

• manipulate Application trust settings, e.g. make a certain certificate trusted for use with TLS/SSL, software install, etc.

• provide support for multiple certstore implementations

The certtool source code can be found in the security sub-system in the following directory: .../filetokens/test/certtool. The certtool must be used from an epoc shell. You can start it using eshell.exe.

We shall go through the various tool usages. Typing certtool results in a list of supported commands. To access more information about a specific command, the list command for example, we can type:

> certtool – h list

The following is a summary of commands available to use with certool.

Full command	Shortened command	Description
-liststores	-ls	Lists the available certstore implementations.
-list	-l	Lists the content of the certstore.
-import	-i	Imports certificates in the certstore.
-remove	-r	Removes a certificate from the certstore.
-addapps	-a	Adds applications to those a certificate is trusted for.
-setapps	-s	Sets the applications for which a certificate is trusted, e.g. software install, TLS, etc.
-removeapps	n/a	Removes applications from those a certificate is trusted for.

Note that long commands, for example liststores, list, addapps, setapps and removeapps are not case-sensitive but short commands, for example -ls, -l, -a,-s and -rk are case sensitive.

To read commands from an “inputfile” and give the output in “outputfile”, use the following command:

> Certool <inputfile> <outputfile>

The file name should be mentioned with the path. If the tool cannot open the “inputfile” or cannot create the output file, it will turn to interactive mode and display the general help command. The input file can contain multiple commands but each command should be separated by a new line character.

If the commands are given incorrectly or in the wrong sequence, for example certtool -store -l or certtool -i -l, the tool displays the default general help command.

In interactive mode, any command called with the -p option, displays screen full of details and waits for key input. In non-interactive mode, the option is ommitted.

In the following sections we shall describe each supported command in detail.

The Symbian certificate store architecture allows devices to have multiple, coexisting certstore implementations. All implementations are accessed through an abstraction layer: the “unified certstore”.

The certtool fully supports multiple certstore implementations with the option –store which can be used to specify a particular certstore implementation which a command must use. To see a list of all available certstore implementations, you use the command –liststores or -ls for short. For example:

> certtool – ls

This results in output similar to the following:

Total Number of Stores: 2
Total Number of Writable Stores: 1
Total Number of Read only Stores: 1
[0] Store Label: Software certificate store
Version: 1.00      Serial Number: 0    Manufacturer: Symbian Ltd. Store Type: ReadWrite
[1] Store Label: SWI cert store
Version: 1.00      Serial Number: N/A      Manufacturer: Symbian Software Ltd. Store Type: Read only

We have an entry for each certstore implementation. The numbers in brackets represent the certstore index which we will use to refer to a specific certstore implementation in the –store option. We then have a label, a human readable description of the implementation. Some meta-data follows: the version, serial number, manufacturer and store type of a given implementation.

With this knowledge we can use the – store option to specify the certstore implementation a command must use. For instance if we want to list the content of the 2nd certstore implementation:

> certtool – store 1 – list

The list command is used to display the content of the certificate store. It can be used to display the overall content of all certstore implementations, to display the content of a specific certstore implementation, or to display details about a specific certificate if we know its label.

Listing the content of all certstore implementations

To see all the certificates available on the device we can use the command:

> certtool -list

The output, depending on the actual certificates present on the device will look similar to:

Store Label: Software certificate store
Root5CA is a X509 format which is a Root (CA) type 

Store Label: Software certificate store
SymbianTestDSACA is a X509 format which is a Root (CA) type 

Store Label: Software certificate store
SymbianTestRSACA is a X509 format which is a Root (CA) type

Listing the content of a specific certstore implementation

If we are interested only in the content of a specific certstore implementation, we can restrict the list command to that implementation using the – store option. Suppose we are interested in the content of the certstore implementation with index 0 (see the section Working with multiple certstore implementations for details on how to list the available certstore implementations) we can issue the command:

> certtool – store 0 – list

Depending on the content of the certstore implementation with index 0 we will get output similar to:

Symbian OS CertStore Manipulation Tool
Copyright (c) 2004 Symbian Software Ltd.  All rights reserved.
Label: TOCSP-Root5-RSA         Format: X509     Owner Type: Root (CA)
Issuer Name: TOCSP-Root5-RSA      Subject Name: TOCSP-Root5-RSA
Valid From: 13:52:28 Thu 26th Apr 2001 Valid Until: 13:52:28 Sun 25th Apr 2004
Trusted for Applications: SWInstall MidletInstall

If we try to specify a non-existing certstore implementation an error will occur:

Symbian OS CertStore Manipulation Tool
Copyright (c) 2004 Symbian Software Ltd.  All rights reserved.
The specified certstore implementation does not exist.
Error during list!
Error code KErrArgument.

Providing certstore list based on owner type

It is possible to display a list of certificates according to an owner type. To do so, you use the following command:

> certtool -owner ca -list

The output, depending on the actual certificates present on the device will look similar to:

Store Label: Software certificate store
Version: 1.00      Serial Number: 0    Manufacturer: Symbian Ltd. Store Type: Read only
    Label: Root5CA     Format: X509  Owner Type: Root (CA)
    Issuer Name: Root5-RSA        Subject Name: Root5-RSA
    Valid From  16:34:42 Wed  3rd Mar 2004  Valid Until 16:34:42 Sat  1st Mar 2014
    Trusted for Applications: SWInstall  

Store Label: Software certificate store
Version: 1.00      Serial Number: 0    Manufacturer: Symbian Ltd. Store Type: Read only
    Label: SymbianTestDSACA        Format: X509   Owner Type: Root (CA)
    Issuer Name: Symbian Test - DSA        Subject Name: Symbian Test - DSA
    Valid From  14:37:11 Sun  18th Apr 2004 Valid Until 14:37:11 Mon  21st Sep 2020
    Trusted for Applications: SWInstall  SWInstallOCSP  

Store Label: Software certificate store
Version: 1.00      Serial Number: 0    Manufacturer: Symbian Ltd. Store Type: Read only
    Label: SymbianTestRSACA        Format: X509   Owner Type: Root (CA)
    Issuer Name: Symbian Test - RSA        Subject Name: Symbian Test - RSA
    Valid From  14:36:14 Sun  18th Apr 2004 Valid Until 14:36:14 Mon  21st Sep 2020
    Trusted for Applications: SWInstall  SWInstallOCSP

Displaying information about a certificate

It is possible to display information about a specific certificate of which we know the label. This is useful, for instance, when the certstore contains a significant amount of certificates and we are only interested in a particular one. Suppose we want to display information about a certificate with label “…” we can issue the command:

> certtool – list “Limited Liability”

Remember that labels are case sensitive. We should get an output similar to:

Symbian OS CertStore Manipulation Tool
Copyright (c) 2004 Symbian Software Ltd.  All rights reserved.
Label: Limited Liability      Format: WTLS    Owner Type: Root (CA) 
Issuer Name: Limited Liability   Subject Name: Limited Liability
Valid From: 15:13:18 Tue 29th Feb 2000 Valid Until: 15:43:18 Sat 29th Feb 2020
Trusted for Applications: 

If no certificate in the certstore corresponds to the given label an error will occur:

Symbian OS CertStore Manipulation Tool
Copyright (c) 2004 Symbian Software Ltd.  All rights reserved.
Cannot find the specified certificate.

Providing detailed output of a certificate

It is possible to display detailed information about a specific certificate of which we know the label. To do so you use the command:

> certtool – list -d

The output, depending on the actual certificates present on the device will look similar to:

Store Label: Software certificate store
Version: 1.00      Serial Number: 0    Manufacturer: Symbian Ltd. Store Type: Read only
    Label: Root5CA     Format: X509  Owner Type: Root (CA)
    Issuer Name: Root5-RSA        Subject Name: Root5-RSA
    Valid From  16:34:42 Wed  3rd Mar 2004  Valid Until 16:34:42 Sat  1st Mar 2014
    Trusted for Applications: SWInstall  

Store Label: Software certificate store
Version: 1.00      Serial Number: 0    Manufacturer: Symbian Ltd. Store Type: Read only
    Label: SymbianTestDSACA        Format: X509   Owner Type: Root (CA)
    Issuer Name: Symbian Test - DSA        Subject Name: Symbian Test - DSA
    Valid From  14:37:11 Sun  18th Apr 2004 Valid Until 14:37:11 Mon  21st Sep 2020
    Trusted for Applications: SWInstall  SWInstallOCSP  

The Symbian certstore allows two types of certificates to be imported: root certificates and user certificates.

Please note that certificates must be in DER format to be imported. Also, the absolute path to the certificate file must be given regardless of the current directory in the shell, e.g. suppose you are in the directory c:\temp which contains mycert.der. To import the certificate you must issue the command:

> certtool – import c:\temp\mycert.der

A certificate has always a label associated to it. A label can be specified during the import operation with the – label option, if this option is not present the full path to the certificate file is taken as label. Labels must be unique within a specific certstore implementation if a label is not unique an error occurs, for instance if the certstore contains a certificate with label abc:

> certtool – list abc

Symbian OS CertStore Manipulation Tool
Copyright (c) 2004 Symbian Software Ltd.  All rights reserved.
Label: abc         Format: WTLS     Owner Type: Root (CA)
Issuer Name: Limited Liability       Subject Name: Limited Liability
Valid From: 15:13:18 Tue 29th Feb 2000 Valid Until: 15:43:18 Sat 29th Feb 2020
Trusted for Applications: 

If we try to import a certificate with the same label an error will occur:

c:\>certtool –label abc –import c:\tcertstore\ent-wtls2.cer
Symbian OS CertStore Manipulation Tool
Copyright (c) 2004 Symbian Software Ltd.  All rights reserved.
The given label is invalid, or already present in the certstore.
Label: abc         Format: WTLS     Owner Type: Root (CA)
Issuer Name: Limited Liability       Subject Name: Limited Liability
Valid From: 15:13:18 Tue 29th Feb 2000 Valid Until: 15:43:18 Sat 29th Feb 2020
Trusted for Applications: 

However, this happens because we are trying to insert the certificate in a certstore implementation where the same label exists already. Remember that is we do not specify the certstore implementation to use in a command we use the first (index 0) by default. It is certainly possible to insert the certificate with label abc in the certstore implementation with index 1, e.g.

> certtool – label abc – store 1 – import c:\tcertstore\ent-wtls2.cer

Symbian OS CertStore Manipulation Tool
Copyright (c) 2004 Symbian Software Ltd.  All rights reserved.
Certificate imported successfully.
Label: abc         Format: WTLS     Owner Type: Root (CA)
Issuer Name: Limited Liability       Subject Name: Limited Liability
Valid From: 15:13:18 Tue 29th Feb 2000 Valid Until: 15:43:18 Sat 29th Feb 2020
Trusted for Applications: 

Importing root certificates

Root certificates typically belong to a certificate authority (CA) and a number of them are typically present on a final product. Root certificates are used to verify the authenticity of signed content. Root certificates are self-signed, and often termed top-level certificates.

All the examples in the previous sections referred to root certificates.

A certificate is imported as a CA root certificate if and only if the corresponding private key cannot be found in the keystore.

Importing user certificates

User certificates belong to the phone owner. Using user certificate the phone owner can authenticate itself, e.g. during SSL/TLS it can perform client authentication. To import a user certificate we need both the certificate itself and its corresponding private key which must be stored in the Symbian OS keystore.

If the private key corresponding to a given certificate is already present in the Symbian OS keystore (perhaps inserted using the Symbian OS keytool) the certificate will be automatically imported as a user certificate.

Assume that the private DSA key corresponding to the certificate stored in dsa_cert1.der is present in the Symbian OS keystore. The following command imports the certificate as a user certificate:

> certtool – label abc – import c:\tcertstore\data\dsa_cert1.der

Symbian OS CertStore Manipulation Tool
Copyright (c) 2004 Symbian Software Ltd.  All rights reserved.
Certificate imported successfully.
Label: abc         Format: X509     Owner Type: User
Issuer Name: 10.32.193.163        Subject Name: Internet Widgits Pty Ltd
Valid From: 16:06:43 Mon 15th Dec 2003 Valid Until: 16:03:43 Wed 14th Jan 2004
Trusted for Applications: 

If the private key is not already present in the keystore, the same command would import the certificate as a CA certificate.

How do we insert a private key in the Symbian OS keystore? We can use the Symbian OS keytool. Alternatively, if we only want to do that to insert a user certificate, we can point to a DER encoded PKCS8 file containing the key using the -private option. After importing the key the certtool will make the owner of the key as "WriteDeviceData", So that keytool (perhaps any process having that capability) will able to manipulate the key, performing actions such as remove or setuser.

Assume the DSA private key corresponding to the certificate stored in dsa_cert1.der is not present in the keystore. Assume the DSA private key we need is stored in pkcs8 DER encoded format in the file pkcs8dsa1.001.

> certtool – label abc – private c:\tcertstore\data\pkcs8dsa1.001 – import c:\tcertstore\data\dsa_cert1.der

Symbian OS CertStore Manipulation Tool
Copyright (c) 2004 Symbian Software Ltd.  All rights reserved.
Certificate imported successfully.
Label: abc         Format: X509     Owner Type: User
Issuer Name: 10.32.193.163        Subject Name: Internet Widgits Pty Ltd
Valid From: 16:06:43 Mon 15th Dec 2003 Valid Until: 16:03:43 Wed 14th Jan 2004
Trusted for Applications: 

Note: either secdlg or tsecdlg need to be in \epoc32\release\winscw\udeb. However, if both of them are there, it will cause a panic.

In addition the corresponding DSA key has been inserted in the keystore with the same label as the certificate:

> keytool – d – list abc

Symbian OS KeyStore Manipulation Tool
Copyright (c) 2004 Symbian Software Ltd.  All rights reserved.
    Algorithm: DSA Size: 512 bits
    Usage: PKCS15 Sign   Code: 0x4
    User: No Users registered.
    Access flags: Extractable
    ID: c0 fa d9 …
    Label: abc
    Native: Yes
    Start date: not set  End data: not set

Certificates can be removed from the certstore using the remove command. We specify the certificate we want to remove by using its label. We can use the store option to refer to a specific certstore implementation. For instance we can issue the command (labels are case sensitive):

> certtool – remove “Thawte Root”

You can remove keys from keystore. This option will work only if the key being removed was added to keystore using the command -private from certtool. To do this, you use the -rka option, as in the example below:

> certtool -r abcd -rka

In this example, the key is removed as well as the certificate.

We can trust a certificate for a certain task or application. Currently there are four applications defined:

• Software installation (SWInstall)

• Signature verification of OCSP response (SWInstallOCSP)

• Midlet installation (MidletInstall)

• TLS/SSL authentication (TLS/SSL)

The SWInstall application allows us to use a given certificate to verify the signature of the signed sis files we wish to install. A certificate with SWInstallOCSP applicability can be used to verify the signature of OCSP responses.

The installation of midlets is treated separately and we have a specific application for it: MidletInstall. Certificate with this application can be used to verify signed midlets.

Certificate can be used to perform TLS and SSL authentication. We trust a certificate to do that with the TLS/SSL application.

The certtool offers three commands to manipulate the applications of a given certificate: setapps, addapps and removeapps. We shall describe each of these commands in details in the following sections.

For this to work, certclients.dat should exist in c:\private\101f72a6\ with the required application.

The setapps command

The setapps command can be used to set the applications a specific certificate can be used for. For instance let us update the applications of the TestCA certificate. Initially it is trusted for SWInstall:

> certtool – list TestCA

Symbian OS CertStore Manipulation Tool
Copyright (c) 2004 Symbian Software Ltd.  All rights reserved.
Label: TestCA          Format: X509    Owner Type: Root (CA)
Issuer Name: TestCA       Subject Name: TestCA
Valid From: 16:36:00 Tue 11th Aug 2003 Valid Until: 16:36:00 Tue 10th Aug 2004
Trusted for Applications: SWInstall

We can change the applications using the setapps command. Let us set the applications to SSL/TLS and MidletInstall:

> certtool – setapps – apps SSL/TLS MidletInstall TestCA

Symbian OS CertStore Manipulation Tool
Copyright (c) 2004 Symbian Software Ltd.  All rights reserved.
Certificate applications set successfully
Label: TestCA          Format: X509    Owner Type: Root (CA)
Issuer Name: TestCA       Subject Name: TestCA
Valid From: 16:36:00 Tue 11th Aug 2003 Valid Until: 16:36:00 Tue 10th Aug 2004
Trusted for Applications: SSL/TLS MidletInstall

The TestCA certificate is now trusted for midlet installation and server authentication with SSL and TLS. If the specified applications are not recognized an error will occur:

Symbian OS CertStore Manipulation Tool
Copyright (c) 2004 Symbian Software Ltd.  All rights reserved.
No valid applications specified, try one of: 
[SWInstall, SWInstallOCSP, MidletInstall, SSL/TLS]

Remember that applications are case sensitive.

We can also set the applications using UIDs, for example:

> certtool – setapps – uids 0x100042AB abc

The addapps command

Suppose that later on we decide to add again SWInstall to the applications TestCA is trusted for. We can certainly use the setapps command to accomplish our goal but we would need to specify all the applications, e.g.:

> certtool – setapps – apps SSL/TLS MidletInstall SWInstall TestCA

The addapps command gives us a shortcut. It allows us to just specify an application which will be added to the existing ones:

> certtool – addapps – apps SWInstall TestCA

This will save us some typing.

We can also add the applications using UIDs, for example:

> certtool – addapps -uids 0x101F9B28 abc

The removeapps command

The removeapps command is essentially dual to addapps. It allows us to remove apps from those a certificate is trusted for, e.g.

> certtool – removeapps – apps SWInstall TestCA

We can also remove the applications using UIDs, for example:

> certtool -removeapps – apps MidletInstall abc

Remember that applications and labels are case sensitive.

In this section we see how the certtool can be used to create a default certstore to be used in a new device. For instance, a licensee would want to create a default certstore to be shipped with every device. The default certstore will most likely contain some default root certificates, e.g. Verisign, Thawte, etc.

User certificates might be added as well, for instance a licensee might add an user certificate to allow a particular device to authenticate itself during a SSL/TLS connection. In this manner the server will be sure it is talking with a certain device model.

The internal representation of a certificate store

The contents of a certificate store are preserved in two files, CAcerts.dat and certclients.dat. An actual device would store the default files in rom, from there the files will be copied to ram when the certstore is first used. The original rom files are copied to ram only if the files are not there already.

The paths where the files are stored in ROM are:

• z:\System\Data\CACerts.dat

• z:\System\Data\certclients.dat

The paths where the files are stored in RAM are:

• c:\System\Data\CACerts.dat

• c:\System\Data\certclients.dat

The full paths for the emulator in ROM are:

• \epoc32\release\(platform)\(build)\z\ System\Data\CACerts.dat

• \epoc32\release\(platform)\( build)\z\ System\Data\certclients.dat

The full paths for the emulator in RAM are:

• \epoc32\(platform)\c\ System\Data\CACerts.dat

• \epoc32\(platform)\c\ System\Data\certclients.dat

where (platform) stands for wins, winscw, armi, etc. and (build) for either udeb or urel.

If the files are not present in RAM, when the certstore is first used the files are copied from rom. If the files are not present at all, new empty ones will be created, this event should not occur in production devices.

Generating a default certificate store

We can generate a default certificate store (the two files, CACerts.dat and certclients.dat) using the certtool and the emulator. We can then take the resulting CACerts.dat and certclients.dat files and insert them in the final rom.

Suppose we want to have a certificate store containing two certificates VeriSignClass1PrimaryCA.cer and thawteserverca.cer. The first step is to copy them to the emulator c drive, let us assume we copy them in \epoc32\(platform)\c.

We can use the certtool to import the two certificates, to do so we start the epoc shell: eshell.exe \epoc32\release\(platform)\(build)\eshell.exe.

From the shell we import the certificates:

> certtool – label “Verisign Class 1” – import c:\VeriSignClass1PrimaryCA.cer

> certtool – label “Thawte Server CA” – import c:\ thawteserverca.cer

The next step is to set the applicability of the certificates. Assume we want the “Verisign Class 1” certificate to be trusted for software installation, midlet installation, SSL/TLS and OCSP, while the “Thawte Server CA” must be trusted for midlet and software installation only. We can use the certtool in the following manner:

> certtool -setapps – apps SWInstall MidletInstall SSL/TLS SWInstallOCSP “Verisign Class 1”

> certtool -setapps – apps SWInstall MidletInstall “Thawte Server CA”