Title:        Building Certificate Store
Owner:        Gleb Dolgich
Contributors: Xavier Leclercq, Gleb Dolgich
Copyright (C) 2003 Symbian Limited. All rights reserved.
================================================================================

Purpose
-------

This document describes how to build CACerts.dat (certificate store) and
certclients.dat (certificate client applications) files. These files are stored
on a device in c:\system\data\ directory. They are necessary for Software
Install and SSL/TLS.

Certificates and trusters
-------------------------

Every certificate stored in CACerts.dat has a set of UIDs associated with it,
each UID marking the certificate as good for a particular purpose (application).
Currently the following applications/UIDs are defined:

- SW Install (268452523, or 0x100042AB)--certificate is suitable for software
  install (SIS files);
- SW Install OCSP Signing (268478646, or 0x1000A8B6)--certificate is suitable
  for OCSP checking (SIS files);
- MIDlet Installation (270506792, or 0x101F9B28)--certificate is good for Java
  MIDlet installation, which includes OCSP checking;
- Server Authentication (268441661, or 0x1000183D)--certificate is suitable for
  SSL/TLS server authentication.

These UIDs are stored in certclients.dat file. Once certclients.dat is in
c:\system\data on the device, the Certificates Control Panel applet allows
manual assignment of applications to each certificate.

Files needed
------------

The following files are needed to build a certificate store:

- T_CERTSTORE.EXE test harness, which is located in security/certman/tcertstore;
  build it from security/certman/group;
- bldcertstore.txt: test script located in security/certman/tcertstore/scripts;
  you can modify it depending on which certificates/applications you want
  included in the store. This script is exported into device's
  c:\tcertstore\scripts.

The following certificates are used for running tests:

- Symbiana.der "Identity ACS Root"--Symbian application signing certificate that
  is provided for reference only and is not used by tests
- Symbianb.der "Testing ACS Root"--Symbian application signing test certificate
  that is provided for reference only and is not used by tests
- cacert.crt "TestCA"--SSL server CA certificate (self-signed)
- thawtetest.crt "Thawte Root"--SW Install certificate
- TOCSP-Root5-RSA.cer--SW Install and MIDlet Installation
- TOCSP-Signing5-RSA.cer--OCSP Signing

These certificates are copied into c:\tappinst\certs\ directory on the device.

Building the store
------------------

To build a certificate store, perform the following steps:

1. Build the T_CERTSTORE test harness and export test files for appinst and
   certman.

2. Go to the appropriate build directory (udeb or urel) and run the following
   command:
   
   t_certstore c:\tcertstore\scripts\bldcertstore.txt c:\bldcertstore.log
   
   This will build c:\system\data\cacerts.dat and c:\system\data\certclients.dat
   with test certificates. If you need to add your own certificates, modify the
   bldcertstore.txt script accordingly.  The ‘console’ option is necessary to ensure 
   the tool can operate independently of the UI environment.