This README file explains how to add a builtin root CA certificate to NSS
or remove a builtin root CA certificate from NSS.

The builtin root CA certificates in NSS are stored in the nssckbi PKCS #11
module. The sources to the nssckbi module are in this directory.

I. Adding a Builtin Root CA Certificate

You need to use the addbuiltin command-line tool to add a root CA certificate
to the nssckbi module. In the procedure described below, we assume that the
new root CA certificate is distributed in DER format in the file newroot.der.

1. Add the directory where the addbuiltin executable resides to your PATH
environment variable. Then, add the directory where the NSPR and NSS shared
libraries (DLLs) reside to the platform-specific environment variable that
specifies your shared library search path: LD_LIBRARY_PATH (most Unix
variants), SHLIB_PATH (32-bit HP-UX), LIBPATH (AIX), or PATH (Windows).

2. Copy newroot.der to this directory.

3. In this directory, run addbuiltin to add the new root certificate. The
argument to the -n option should be replaced by the nickname of the root
certificate.

    % addbuiltin -n "Nickname of the Root Certificate" -t C,C,C < newroot.der \
    >> certdata.txt

4. Edit nssckbi.h to bump the version of the module.

5. Run gmake in this directory to build the nssckbi module.

6. After you verify that the new nssckbi module is correct, check in
certdata.txt and nssckbi.h.

II. Removing a Builtin Root CA Certificate

1. Change directory to this directory.

2. Edit certdata.txt and remove the root CA certificate.

3. Edit nssckbi.h to bump the version of the module.

4. Run gmake in this directory to build the nssckbi module.

5. After you verify that the new nssckbi module is correct, check in
certdata.txt and nssckbi.h.

III. Scheduling a Distrust date for Server/TLS or Email certificates issued
by a CA

For each Builtin Root CA Certificate we have the Trust Bits to know what kind
of certificates issued by this CA are trusted: Server/TLS, E-mail or S/MIME.
Sometimes a CA discontinues support for a particular kind of certificate,
but will still issue other kinds. For instance, they might cease support for
email certificates but continue to provide server certificates. In this
scenario, we have to disable the Trust Bit for this kind of certificate when
the last issued certificate expires.
Between the last expired certificate date and the change and propagation of
this respective Trust Bit, could have a undesired gap.

So, in these situations we can set a Distrust Date for this Builtin Root CA
Certificate. Clients should check the distrust date in certificates to avoid
trusting a CA for service they have ceased to support.

A distrust date is a timestamp in unix epoch, encoded in DER format and saved
in certdata.txt. These fields are defined at the "Certificate" entries of
certdata.txt, in a MULTILINE_OCTAL format. By default, for readability purpose,
these fields are set as a boolean CK_FALSE and will be ignored when read.

1. Create the timestamp for the desired distrust date. An easy and practical way
to do this is using the date command.
    % date -d "2019-07-01 00:00:00 UTC" +%s
    The result should be something like: 1561939200

2. Then, run the addbuiltin -d to verify the timestamp and do the right
conversions.
   The -d option takes the timestamp as an argument, which is interpreted as
   seconds since unix epoch. The addbuiltin command will show the result in the
   stdout, as it should be inserted in certdata.txt.
   % addbuiltin -d 1561939200
   The result should be something like this:

   The timestamp represents this date: Mon Jul 01 00:00:00 2019
   Locate the entry of the desired certificate in certdata.txt
   Erase the CKA_NSS_[SERVER|EMAIL]_DISTRUST_AFTER CK_BBOOL CK_FALSE
   And override with the following respective entry:

   # For Server Distrust After: Mon Jul 01 00:00:00 2019
   CKA_NSS_SERVER_DISTRUST_AFTER MULTILINE_OCTAL
   \061\071\060\067\060\061\060\060\060\060\060\060\132
   END
   # For Email Distrust After: Mon Jul 01 00:00:00 2019
   CKA_NSS_EMAIL_DISTRUST_AFTER MULTILINE_OCTAL
   \061\071\060\067\060\061\060\060\060\060\060\060\132
   END

3. Edit the certdata.txt, overriding the desired entry for the desired CA, as
the instructions generated by the previous command.

4. If necessary, increment the version counter
NSS_BUILTINS_LIBRARY_VERSION_MINOR in nssckbi.h.

5. Build the nssckbi module.

6. A good way to test is with certutil:
    % certutil -L -d $DBDIR -n "Builtin Object Token:<nickname>"