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:

- 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:\tcertman\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.