| 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>" |