From 36d22d82aa202bb199967e9512281e9a53db42c9 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 7 Apr 2024 21:33:14 +0200 Subject: Adding upstream version 115.7.0esr. Signed-off-by: Daniel Baumann --- security/nss/lib/ckfw/builtins/README | 106 ++++++++++++++++++++++++++++++++++ 1 file changed, 106 insertions(+) create mode 100644 security/nss/lib/ckfw/builtins/README (limited to 'security/nss/lib/ckfw/builtins/README') 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:" -- cgit v1.2.3