1 files changed, 62 insertions, 1 deletions
diff --git a/lib/ckfw/builtins/README b/lib/ckfw/builtins/README
index fc0393c38..11f5c2c9a 100644
--- a/lib/ckfw/builtins/README
+++ b/lib/ckfw/builtins/README
@@ -22,7 +22,8 @@ variants), SHLIB_PATH (32-bit HP-UX), LIBPATH (AIX), or PATH (Windows).
 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
+    % 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.
 
@@ -43,3 +44,63 @@ II. Removing a Builtin Root CA Certificate
 
 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>"