1 files changed, 106 insertions, 0 deletions
diff --git a/security/nss/lib/ckfw/builtins/README b/security/nss/lib/ckfw/builtins/README
new file mode 100644
index 0000000000..11f5c2c9a7
--- /dev/null
+++ b/security/nss/lib/ckfw/builtins/README
@@ -0,0 +1,106 @@
+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>"