106 lines
4.4 KiB
Text
106 lines
4.4 KiB
Text
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>"
|