NSS Database

Creating Database

To create NSS database without a password:

$ mkdir -p nssdb
$ certutil -N -d nssdb --empty-password

To create NSS database with a password:

$ mkdir -p nssdb
$ echo Secret.123 > password.internal
$ certutil -N -d nssdb -f password.internal

To change NSS database password:

$ certutil -W -d nssdb -f oldpassword.txt -@newpassword.txt

Modules

See NSS Modules.

Listing Certificates

Listing all certificates

$ certutil -L -d nssdb -h all

Listing certificates in internal token

$ certutil -L -d nssdb

Listing certificates in HSM

$ certutil -L -d nssdb -h HSM -f password.HSM
HSM:testcert                                                 CTu,Cu,Cu

Displaying Certificate Info

This command will display the details of a certificate in internal token:

$ certutil -L -d nssdb -n testcert

This command will display the details of a certificate in HSM:

$ certutil -L -d nssdb -h HSM -f password.HSM -n HSM:testcert

Exporting Certificate

To export a certificate in PEM format:

$ certutil -L -d nssdb -n testcert -a > testcert.crt

To export a certificate in DER format:

$ certutil -L -d nssdb -n testcert -r > testcert.crt

Decoding Certificate

$ certutil -L -d nssdb -n testcert -r | dumpasn1

Importing Certificate

To add a certificate into the internal token:

$ certutil -A -d nssdb -n testcert -i testcert.pem -t "CT,C,C"

To add a certificate into both the internal token and the HSM:

$ certutil -A -d nssdb -h HSM -f password.HSM -n testcert -i testcert.pem -t "CT,C,C"

To add a certificate only to the HSM:

$ certutil -A -d nssdb -h HSM -f password.HSM -P HSM -n testcert -i testcert.pem -t "CT,C,C"

Do NOT execute the following command, it will mess up the database:

$ certutil -A -d nssdb -h HSM -f password.HSM -n HSM:testcert -i testcert.pem -t "CT,C,C"

In FIPS mode, the certificate has to be added separately into internal token and HSM (see bug #1393668):

$ certutil -A -d nssdb -h HSM -f password.HSM -n testcert -i testcert.pem -t ""
$ certutil -A -d nssdb -f password.internal -n testcert -i testcert.pem -t "CT,C,C"

Exporting Certificate Chain

Export each certificate in the certificate chain (see Exporting Certificate), then create a PKCS #7 file:

$ openssl crl2pkcs7 -nocrl -certfile ca1.crt -certfile ca2.crt ... -out cert_chain.p7b

Verify with the following command:

$ openssl pkcs7 -print_certs -in cert_chain.p7b

Importing Certificate Chain

Each certificate in the certificate chain can be imported individually:

$ certutil -A -d nssdb -a -i -n testcert -i testcert.pem -t CT,C,C

Alternatively, the entire certificate chain can be imported as a PKCS #7 file:

$ openssl pkcs7 -print_certs -in /tmp/cert_chain.p7b -out /tmp/cert_chain.pem
$ openssl pkcs12 -export -nokeys -in /tmp/cert_chain.pem -out /tmp/cert_chain.p12 -passout file:password.txt
$ pk12util -d nssdb -k password.txt -i /tmp/cert_chain.p12 -w password.txt
$ certutil -M -d nssdb -n <nickname> -t CT,C,C

Exporting into PKCS #12 File

To export a single certificate:

$ pk12util -d nssdb -k password.internal -n nickname -o output.p12 -w output.password

To export the all keys and certificates in the database:

$ PKCS12Export -d nssdb -p password.internal -o output.p12 -w output.password

Importing from PKCS #12 File

$ pk12util -d nssdb -k password.internal -i input.p12 -w input.password

Exporting from PKCS #12 File

Export Cert from a pkcs#12 (.p12) file:

$ openssl pkcs12 -in path.p12 -out newfile.crt.pem -clcerts -nokeys

Export encrypted RSA key from a pkics#12 (.p12) file:

$ openssl pkcs12 -in path.p12 -out newfile.key.pem -nocerts -nodes

Convert encrypted RSA key to unencrypted (pkcs#1):

$ openssl rsa -in newfile.key.pem -out newfile.key.pkcs1

Convert unencrypted RSA private key (pkcs#1) to pkcs#8 key:

$ openssl pkcs8 -topk8 -inform PEM -outform PEM -nocrypt -in newfile.key.pkcs1 -out newfile.key

Verify the exported cert and key match

openssl pkey -in privateKey.key -pubout -outform pem | sha256sum
openssl x509 -in certificate.crt -pubkey -noout -outform pem | sha256sum 

The output from both commands must match.

Modifying a Certificate

Modifying trust flags in internal token

To modifying a certificate's trust attribute in internal token:

$ certutil -M -d nssdb -n testcert -t "CT,C,C"

Modifying trust flags in HSM

To modifying a certificate's trust attribute in HSM:

$ certutil -M -d nssdb -h HSM -f password.HSM -n HSM:testcert -t "CT,C,C"

This command modifies the trust attributes both in internal token and HSM. This command ignores the -f parameter, so the password must be entered manually

Renaming a certificate

To rename a certificate:

• export the certificate into a file
• delete the certificate from NSS database
• reimport the certificate with a new nickname

See also NSS Bug 448738.

Validating Certificate Chain

To validate a certificate in internal token:

$ certutil -O -d nssdb -n testcert

To validate a certificate in HSM:

$ certutil -O -d nssdb -h HSM -f password.txt -n HSM:testcert

Deleting Certificate

Deleting a certificate in internal token

This command deletes a certificate in the internal token:

$ certutil -D -d nssdb -n testcert

Deleting a certificate in HSM

If the certificate is also in HSM, the certificate will not be deleted from HSM, but the trust attribute will change to "u,u,u".

This command deletes a certificate in HSM:

$ certutil -D -d nssdb -h HSM -f password.HSM -n HSM:testcert

This command deletes the certificate in HSM. This command ignores the -f parameter, so the password must be entered manually.

In any case, if the certificate has a key in the token, the key will be orphaned.

These commands do not work:

$ certutil -D -d nssdb -P HSM -n testcert
$ certutil -D -d nssdb -h HSM -f password.HSM -P HSM -n testcert

Listing Keys

Listing keys in internal token

$ certutil -K -d nssdb -f password.internal

Listing keys in HSM

$ certutil -K -d nssdb -h HSM -f password.HSM

Deleting a Key

Deleting a key in internal token

To delete a certificate and its key in internal token:

$ certutil -F -d nssdb -f password.internal -n testcert

To delete a key in internal token:

$ certutil -F -d nssdb -f password.internal -k <key ID>

Deleting a key in HSM

To delete a certificate and its key in HSM:

$ pki -d nssdb --token HSM -C password.HSM client-cert-del HSM:testcert

The certutil command does not work:

$ certutil -F -d nssdb -h HSM -f password.HSM -n HSM:testcert
Incorrect password/PIN entered.
certutil: could not authenticate to token NSS Certificate DB.: SEC_ERROR_BAD_PASSWORD: The security password entered is incorrect.

Cloning Database

To clone an NSS database, export all certificates:

$ certutil -L -d nssdb -h HSM -n testcert -a > testcert.pem

Create the new database with the HSM modules if applicable:

$ mkdir clone
$ certutil -N -d nssdb

Then reimport all certificates:

$ certutil -A -d nssdb -h HSM -f password.HSM -n testcert -i testcert.pem -t "CT,C,C"

Generating Key Pair

Generate a key pair with the following command:

$ openssl rand -out noise.bin 2048
$ certutil -G -d nssdb -h internal -f password.internal -z nssdb/noise.bin


Generating key.  This may take a few moments...

Generating Certificate Request

Creating Noise File

$ openssl rand -out noise.bin 2048

Creating CSR File

Generate a CSR with the following command:

$ certutil -R \
 -d nssdb \
 -h internal \
 -f password.internal \
 -s "UID=testuser,O=EXAMPLE" \
 -z noise.bin \
 -o testuser.csr.der
$ BtoA testuser.csr.der testuser.csr.pem
$ echo "-----BEGIN NEW CERTIFICATE REQUEST-----" > testuser.csr
$ cat testuser.csr.pem >> testuser.csr
$ echo "-----END NEW CERTIFICATE REQUEST-----" >> testuser.csr
$ rm testuser.csr.der
$ rm testuser.csr.pem

Creating Certificates

See also:

• Creating Self-Signed CA Signing Certificate with NSS
• Creating Self-Signed SSL Server Certificate with NSS

References

• NSS
• OpenSSL
• HSM
• PKCS7
• PKCS11
• PKCS12
• RHDS 8.1 Administration Guide - Using certutil
• Generating a Signing Cert using certutil
• RFC 5280 - Authority Key Identifier
• RFC 5280 - Subject Key Identifier
• What damage could be done if a malicious certificate had an identical “Subject Key Identifier”?
• Extract cert and private key from pkcs12 file
• Verify cert and key pair