README (4540B)
1 This README file explains how to add a builtin root CA certificate to NSS 2 or remove a builtin root CA certificate from NSS. 3 4 The builtin root CA certificates in NSS are stored in the nssckbi PKCS #11 5 module. The sources to the nssckbi module are in this directory. 6 7 I. Adding a Builtin Root CA Certificate 8 9 You need to use the addbuiltin command-line tool to add a root CA certificate 10 to the nssckbi module. In the procedure described below, we assume that the 11 new root CA certificate is distributed in DER format in the file newroot.der. 12 13 1. Add the directory where the addbuiltin executable resides to your PATH 14 environment variable. Then, add the directory where the NSPR and NSS shared 15 libraries (DLLs) reside to the platform-specific environment variable that 16 specifies your shared library search path: LD_LIBRARY_PATH (most Unix 17 variants), SHLIB_PATH (32-bit HP-UX), LIBPATH (AIX), or PATH (Windows). 18 19 2. Copy newroot.der to this directory. 20 21 3. In this directory, run addbuiltin to add the new root certificate. The 22 argument to the -n option should be replaced by the nickname of the root 23 certificate. 24 25 % addbuiltin -n "Nickname of the Root Certificate" -t C,C,C < newroot.der \ 26 >> certdata.txt 27 28 4. Edit nssckbi.h to bump the version of the module. 29 30 5. Run gmake in this directory to build the nssckbi module. 31 32 6. After you verify that the new nssckbi module is correct, check in 33 certdata.txt and nssckbi.h. 34 35 II. Removing a Builtin Root CA Certificate 36 37 1. Change directory to this directory. 38 39 2. Edit certdata.txt and remove the root CA certificate. 40 41 3. Edit nssckbi.h to bump the version of the module. 42 43 4. Run gmake in this directory to build the nssckbi module. 44 45 5. After you verify that the new nssckbi module is correct, check in 46 certdata.txt and nssckbi.h. 47 48 III. Scheduling a Distrust date for Server/TLS or Email certificates issued 49 by a CA 50 51 For each Builtin Root CA Certificate we have the Trust Bits to know what kind 52 of certificates issued by this CA are trusted: Server/TLS, E-mail or S/MIME. 53 Sometimes a CA discontinues support for a particular kind of certificate, 54 but will still issue other kinds. For instance, they might cease support for 55 email certificates but continue to provide server certificates. In this 56 scenario, we have to disable the Trust Bit for this kind of certificate when 57 the last issued certificate expires. 58 Between the last expired certificate date and the change and propagation of 59 this respective Trust Bit, could have a undesired gap. 60 61 So, in these situations we can set a Distrust Date for this Builtin Root CA 62 Certificate. Clients should check the distrust date in certificates to avoid 63 trusting a CA for service they have ceased to support. 64 65 A distrust date is a timestamp in unix epoch, encoded in DER format and saved 66 in certdata.txt. These fields are defined at the "Certificate" entries of 67 certdata.txt, in a MULTILINE_OCTAL format. By default, for readability purpose, 68 these fields are set as a boolean CK_FALSE and will be ignored when read. 69 70 1. Create the timestamp for the desired distrust date. An easy and practical way 71 to do this is using the date command. 72 % date -d "2019-07-01 00:00:00 UTC" +%s 73 The result should be something like: 1561939200 74 75 2. Then, run the addbuiltin -d to verify the timestamp and do the right 76 conversions. 77 The -d option takes the timestamp as an argument, which is interpreted as 78 seconds since unix epoch. The addbuiltin command will show the result in the 79 stdout, as it should be inserted in certdata.txt. 80 % addbuiltin -d 1561939200 81 The result should be something like this: 82 83 The timestamp represents this date: Mon Jul 01 00:00:00 2019 84 Locate the entry of the desired certificate in certdata.txt 85 Erase the CKA_NSS_[SERVER|EMAIL]_DISTRUST_AFTER CK_BBOOL CK_FALSE 86 And override with the following respective entry: 87 88 # For Server Distrust After: Mon Jul 01 00:00:00 2019 89 CKA_NSS_SERVER_DISTRUST_AFTER MULTILINE_OCTAL 90 \061\071\060\067\060\061\060\060\060\060\060\060\132 91 END 92 # For Email Distrust After: Mon Jul 01 00:00:00 2019 93 CKA_NSS_EMAIL_DISTRUST_AFTER MULTILINE_OCTAL 94 \061\071\060\067\060\061\060\060\060\060\060\060\132 95 END 96 97 3. Edit the certdata.txt, overriding the desired entry for the desired CA, as 98 the instructions generated by the previous command. 99 100 4. If necessary, increment the version counter 101 NSS_BUILTINS_LIBRARY_VERSION_MINOR in nssckbi.h. 102 103 5. Build the nssckbi module. 104 105 6. A good way to test is with certutil: 106 % certutil -L -d $DBDIR -n "Builtin Object Token:<nickname>"