Source code
Revision control
Copy as Markdown
Other Tools
.. _mozilla_projects_nss_reference_nss_tools_:_certutil:
NSS tools : certutil
====================
.. container::
| Name
| certutil — Manage keys and certificate in both NSS databases and other NSS tokens
| Synopsis
| certutil [options] [[arguments]]
| Description
| The Certificate Database Tool, certutil, is a command-line utility
| that can create and modify certificate and key databases.
| It can specifically list, generate, modify, or delete certificates, create or
| change the password, generate new public and private key pairs,
| display the contents of the key database, or delete key pairs within the key database.
| Certificate issuance, part of the key and certificate management process, requires that
| keys and certificates be created in the key database. This document discusses certificate
| and key database management. For information on the security module database management,
| see the modutil manpage.
| Options and Arguments
| Running certutil always requires one and only one command option to
| specify the type of certificate operation. Each option may take arguments,
| anywhere from none to multiple arguments. The command option -H will list
| all the command options available and their relevant arguments.
| Command Options
| -A
| Add an existing certificate to a certificate database.
| The certificate database should already exist; if one is
| not present, this command option will initialize one by default.
| -B
| Run a series of commands from the specified batch file.
| This requires the -i argument.
| -C
| Create a new binary certificate file from a binary
| certificate request file. Use the -i argument to specify
| the certificate request file. If this argument is not
| used, certutil prompts for a filename.
| -D
| Delete a certificate from the certificate database.
| --rename
| Change the database nickname of a certificate.
|
| -E
| Add an email certificate to the certificate database.
| -F
| Delete a private key from a key database. Specify the
| key to delete with the -n argument. Specify the database
| from which to delete the key with the -d argument. Use
| the -k argument to specify explicitly whether to delete
| a DSA, RSA, or ECC key. If you don't use the -k
| argument, the option looks for an RSA key matching the
| specified nickname.
| When you delete keys, be sure to also remove any
| certificates associated with those keys from the
| certificate database, by using -D. Some smart cards (for
| example, the Litronic card) do not let you remove a
| public key you have generated. In such a case, only the
| private key is deleted from the key pair. You can
| display the public key with the command certutil -K -h
| tokenname.
| -G
| Generate a new public and private key pair within a key
| database. The key database should already exist; if one
| is not present, this option will initialize one by
| default. Some smart cards (for example, the Litronic
| card) can store only one key pair. If you create a new
| key pair for such a card, the previous pair is
| overwritten.
| -H
| Display a list of the options and arguments used by the
| Certificate Database Tool.
| -K
| List the key ID of keys in the key database. A key ID is
| the modulus of the RSA key or the publicValue of the DSA
| key. IDs are displayed in hexadecimal ("0x" is not
| shown).
| -L
| List all the certificates, or display information about
| a named certificate, in a certificate database. Use the
| -h tokenname argument to specify the certificate
| database on a particular hardware or software token.
| -M
| Modify a certificate's trust attributes using the values
| of the -t argument.
| -N
| Create new certificate and key databases.
| -O
| Print the certificate chain.
| -R
| Create a certificate request file that can be submitted
| to a Certificate Authority (CA) for processing into a
| finished certificate. Output defaults to standard out
| unless you use -o output-file argument. Use the -a
| argument to specify ASCII output.
| -S
| Create an individual certificate and add it to a
| certificate database.
| -T
| Reset the key database or token.
| -U
| List all available modules or print a single named
| module.
| -V
| Check the validity of a certificate and its attributes.
| -W
| Change the password to a key database.
| --merge
| Merge two databases into one.
| --upgrade-merge
| Upgrade an old database and merge it into a new
| database. This is used to migrate legacy NSS databases
| (cert8.db and key3.db) into the newer SQLite databases
| (cert9.db and key4.db).
| Arguments
| Arguments modify a command option and are usually lower case, numbers, or symbols.
| -a
| Use ASCII format or allow the use of ASCII format for
| input or output. This formatting follows RFC 1113. For
| certificate requests, ASCII output defaults to standard
| output unless redirected.
| -b validity-time
| Specify a time at which a certificate is required to be
| valid. Use when checking certificate validity with the
| -V option. The format of the validity-time argument is
| YYMMDDHHMMSS[+HHMM|-HHMM|Z], which allows offsets to be
| set relative to the validity end time. Specifying
| seconds (SS) is optional. When specifying an explicit
| time, use a Z at the end of the term, YYMMDDHHMMSSZ, to
| close it. When specifying an offset time, use
| YYMMDDHHMMSS+HHMM or YYMMDDHHMMSS-HHMM for adding or
| subtracting time, respectively.
| If this option is not used, the validity check defaults
| to the current system time.
| -c issuer
| Identify the certificate of the CA from which a new
| certificate will derive its authenticity. Use the exact
| nickname or alias of the CA certificate, or use the CA's
| email address. Bracket the issuer string with quotation
| marks if it contains spaces.
| -d [prefix]directory
| Specify the database directory containing the
| certificate and key database files.
| certutil supports two types of databases: the legacy
| security databases (cert8.db, key3.db, and secmod.db)
| and new SQLite databases (cert9.db, key4.db, and
| pkcs11.txt).
NSS recognizes the following prefixes:
· sql: requests the newer database
· dbm: requests the legacy database
| If no prefix is specified the default type is retrieved from NSS_DEFAULT_DB_TYPE. If
NSS_DEFAULT_DB_TYPE is not set
| then dbm: is the default.
| --dump-ext-val OID
| For single cert, print binary DER encoding of extension OID.
| -e
| Check a certificate's signature during the process of
| validating a certificate.
| --email email-address
| Specify the email address of a certificate to list. Used with the -L command option.
| --extGeneric OID:critical-flag:filename[,OID:critical-flag:filename]...
| Add one or multiple extensions that certutil cannot encode yet, by loading their
encodings from external files.
· OID (example): 1.2.3.4
· critical-flag: critical or not-critical
· filename: full path to a file containing an encoded extension
|
| -f password-file
| Specify a file that will automatically supply the
| password to include in a certificate or to access a
| certificate database. This is a plain-text file
| containing one password. Be sure to prevent unauthorized
| access to this file.
| -g keysize
| Set a key size to use when generating new public and
| private key pairs. The minimum is 512 bits and the
| maximum is 16384 bits. The default is 2048 bits. Any size
| between the minimum and maximum is allowed.
| -h tokenname
| Specify the name of a token to use or act on. Unless
| specified otherwise the default token is an internal
| slot.
| -i input_file
| Pass an input file to the command. Depending on the
| command option, an input file can be a specific
| certificate, a certificate request file, or a batch file
| of commands.
| -k rsa|dsa|ec|all
| Specify the type of a key. The valid options are RSA,
| DSA, ECC, or all. The default value is rsa. Specifying
| the type of key can avoid mistakes caused by duplicate
| nicknames.
| -k key-type-or-id
| Specify the type or specific ID of a key.
| The valid key type options are rsa, dsa, ec, or all. The default value is rsa.
Specifying the type of key can avoid
| mistakes caused by duplicate nicknames. Giving a key type generates a new key pair;
giving the ID of an existing key
| reuses that key pair (which is required to renew certificates).
| -l
| Display detailed information when validating a
| certificate with the -V option.
| -m serial-number
| Assign a unique serial number to a certificate being created. This operation should
be performed by a CA. If no
| serial number is provided a default serial number is made from the current time.
Serial numbers are limited to
| integers.
| -n nickname
| Specify the nickname of a certificate or key to list,
| create, add to a database, modify, or validate. Bracket
| the nickname string with quotation marks if it contains
| spaces.
| -o output-file
| Specify the output file name for new certificates or
| binary certificate requests. Bracket the output-file
| string with quotation marks if it contains spaces. If
| this argument is not used the output destination
| defaults to standard output.
| -P dbPrefix
| Specify the prefix used on the certificate and key
| database file. This argument is provided to support
| legacy servers. Most applications do not use a database prefix.
| -p phone
| Specify a contact telephone number to include in new
| certificates or certificate requests. Bracket this
| string with quotation marks if it contains spaces.
| -q pqgfile or curve-name
| Read an alternate PQG value from the specified file when generating DSA key pairs.
| If this argument is not used,certutil generates its own PQG value. PQG files are
created with a separate DSA utility.
Elliptic curve name is one of the ones from SUITE B: nistp256, nistp384, nistp521
| If NSS has been compiled with support curves outside of SUITE B: sect163k1,
nistk163, sect163r1, sect163r2, nistb163,
| sect193r1, sect193r2, sect233k1, nistk233, sect233r1, nistb233, sect239k1,
sect283k1, nistk283, sect283r1, nistb283,
| sect409k1, nistk409, sect409r1, nistb409, sect571k1, nistk571, sect571r1, nistb571,
secp160k1, secp160r1, secp160r2,
| secp192k1, secp192r1, nistp192, secp224k1, secp224r1, nistp224, secp256k1,
secp256r1, secp384r1, secp521r1,
| prime192v1, prime192v2, prime192v3, prime239v1, prime239v2, prime239v3, c2pnb163v1,
c2pnb163v2, c2pnb163v3,
| c2pnb176v1, c2tnb191v1, c2tnb191v2, c2tnb191v3, c2pnb208w1, c2tnb239v1, c2tnb239v2,
c2tnb239v3, c2pnb272w1,
| c2pnb304w1, c2tnb359w1, c2pnb368w1, c2tnb431r1, secp112r1, secp112r2, secp128r1,
secp128r2, sect113r1, sect113r2
| sect131r1, sect131r2
|
| -r
| Display a certificate's binary DER encoding when listing
| information about that certificate with the -L option.
| -s subject
| Identify a particular certificate owner for new
| certificates or certificate requests. Bracket this
| string with quotation marks if it contains spaces. The
| subject identification format follows RFC #1485.
| -t trustargs
| Specify the trust attributes to modify in an existing
| certificate or to apply to a certificate when creating
| it or adding it to a database. There are three available
| trust categories for each certificate, expressed in the
| order SSL, email, object signing for each trust setting.
| In each category position, use none, any, or all of the
| attribute codes:
| + p - Valid peer
| + P - Trusted peer (implies p)
| + c - Valid CA
| + T - Trusted CA to issue client certificates (implies
| c)
| + C - Trusted CA to issue server certificates (SSL only)
| (implies c)
| + u - Certificate can be used for authentication or
| signing
| + w - Send warning (use with other attributes to include
| a warning when the certificate is used in that
| context)
| The attribute codes for the categories are separated by
| commas, and the entire set of attributes enclosed by
| quotation marks. For example:
| -t "TC,C,T"
| Use the -L option to see a list of the current
| certificates and trust attributes in a certificate
| database.
| Note that the output of the -L option may include "u" flag, which means that there
is a private key associated with
| the certificate. It is a dynamic flag and you cannot set it with certutil.
| -u certusage
| Specify a usage context to apply when validating a
| certificate with the -V option.
| The contexts are the following:
· C (as an SSL client)
· V (as an SSL server)
· L (as an SSL CA)
· A (as Any CA)
· Y (Verify CA)
· S (as an email signer)
· R (as an email recipient)
· O (as an OCSP status responder)
· J (as an object signer)
|
| -v valid-months
| Set the number of months a new certificate will be
| valid. The validity period begins at the current system
| time unless an offset is added or subtracted with the -w
| option. If this argument is not used, the default
| validity period is three months. When this argument is
| used, the default three-month period is automatically
| added to any value given in the valid-month argument.
| For example, using this option to set a value of 3 would
| cause 3 to be added to the three-month default, creating
| a validity period of six months. You can use negative
| values to reduce the default period. For example,
| setting a value of -2 would subtract 2 from the default
| and create a validity period of one month.
| -w offset-months
| Set an offset from the current system time, in months,
| for the beginning of a certificate's validity period.
| Use when creating the certificate or adding it to a
| database. Express the offset in integers, using a minus
| sign (-) to indicate a negative offset. If this argument
| is not used, the validity period begins at the current
| system time. The length of the validity period is set
| with the -v argument.
| -X
| Force the key and certificate database to open in
| read-write mode. This is used with the -U and -L command
| options.
| -x
| Use certutil to generate the signature for a certificate
| being created or added to a database, rather than
| obtaining a signature from a separate CA.
| -y exp
| Set an alternate exponent value to use in generating a
| new RSA public key for the database, instead of the
| default value of 65537. The available alternate values
| are 3 and 17.
| -z noise-file
| Read a seed value from the specified file to generate a
| new private and public key pair. This argument makes it
| possible to use hardware-generated seed values or
| manually create a value from the keyboard. The minimum
| file size is 20 bytes.
| -0 SSO_password
| Set a site security officer password on a token.
| -1 \| --keyUsage keyword,keyword
| Set a Netscape Certificate Type Extension in the
| certificate. There are several available keywords:
| + digital signature
| + nonRepudiation
| + keyEncipherment
| + dataEncipherment
| + keyAgreement
| + certSigning
| + crlSigning
| + critical
| -2
| Add a basic constraint extension to a certificate that
| is being created or added to a database. This extension
| supports the certificate chain verification process.
| certutil prompts for the certificate constraint
| extension to select.
| X.509 certificate extensions are described in RFC 5280.
| -3
| Add an authority key ID extension to a certificate that
| is being created or added to a database. This extension
| supports the identification of a particular certificate,
| from among multiple certificates associated with one
| subject name, as the correct issuer of a certificate.
| The Certificate Database Tool will prompt you to select
| the authority key ID extension.
| X.509 certificate extensions are described in RFC 5280.
| -4
| Add a CRL distribution point extension to a certificate
| that is being created or added to a database. This
| extension identifies the URL of a certificate's
| associated certificate revocation list (CRL). certutil
| prompts for the URL.
| X.509 certificate extensions are described in RFC 5280.
| -5 \| --nsCertType keyword,keyword
| Add a Netscape certificate type extension to a
| certificate that is being created or added to the
| database. There are several available keywords:
| + sslClient
| + sslServer
| + smime
| + objectSigning
| + sslCA
| + smimeCA
| + objectSigningCA
| + critical
| X.509 certificate extensions are described in RFC 5280.
| -6 \| --extKeyUsage keyword,keyword
| Add an extended key usage extension to a certificate
| that is being created or added to the database. Several
| keywords are available:
| + serverAuth
| + clientAuth
| + codeSigning
| + emailProtection
| + timeStamp
| + ocspResponder
| + stepUp
| + critical
| X.509 certificate extensions are described in RFC 5280.
| -7 emailAddrs
| Add a comma-separated list of email addresses to the
| subject alternative name extension of a certificate or
| certificate request that is being created or added to
| the database. Subject alternative name extensions are
| described in Section 4.2.1.7 of RFC 3280.
| -8 dns-names
| Add a comma-separated list of DNS names to the subject
| alternative name extension of a certificate or
| certificate request that is being created or added to
| the database. Subject alternative name extensions are
| described in Section 4.2.1.7 of RFC 3280.
| --extAIA
| Add the Authority Information Access extension to the
| certificate. X.509 certificate extensions are described
| in RFC 5280.
| --extSIA
| Add the Subject Information Access extension to the
| certificate. X.509 certificate extensions are described
| in RFC 5280.
| --extCP
| Add the Certificate Policies extension to the
| certificate. X.509 certificate extensions are described
| in RFC 5280.
| --extPM
| Add the Policy Mappings extension to the certificate.
| X.509 certificate extensions are described in RFC 5280.
| --extPC
| Add the Policy Constraints extension to the certificate.
| X.509 certificate extensions are described in RFC 5280.
| --extIA
| Add the Inhibit Any Policy Access extension to the
| certificate. X.509 certificate extensions are described
| in RFC 5280.
| --extSKID
| Add the Subject Key ID extension to the certificate.
| X.509 certificate extensions are described in RFC 5280.
| --source-dir certdir
| Identify the certificate database directory to upgrade.
| --source-prefix certdir
| Give the prefix of the certificate and key databases to
| upgrade.
| --upgrade-id uniqueID
| Give the unique ID of the database to upgrade.
| --upgrade-token-name name
| Set the name of the token to use while it is being
| upgraded.
| -@ pwfile
| Give the name of a password file to use for the database
| being upgraded.
| Usage and Examples
| Most of the command options in the examples listed here have
| more arguments available. The arguments included in these
| examples are the most common ones or are used to illustrate a
| specific scenario. Use the -H option to show the complete list
| of arguments for each command option.
| Creating New Security Databases
| Certificates, keys, and security modules related to managing
| certificates are stored in three related databases:
| \* cert8.db or cert9.db
| \* key3.db or key4.db
| \* secmod.db or pkcs11.txt
| These databases must be created before certificates or keys can
| be generated.
| certutil -N -d [sql:]directory
| Creating a Certificate Request
| A certificate request contains most or all of the information
| that is used to generate the final certificate. This request is
| submitted separately to a certificate authority and is then
| approved by some mechanism (automatically or by human review).
| Once the request is approved, then the certificate is
| generated.
| $ certutil -R -k key-type-or-id [-q pqgfile|curve-name] -g key-size -s s
| ubject [-h tokenname] -d [sql:]directory [-p phone] [-o output-file] [-a
| ]
| The -R command options requires four arguments:
| \* -k to specify either the key type to generate or, when
| renewing a certificate, the existing key pair to use
| \* -g to set the keysize of the key to generate
| \* -s to set the subject name of the certificate
| \* -d to give the security database directory
| The new certificate request can be output in ASCII format (-a)
| or can be written to a specified file (-o).
| For example:
| $ certutil -R -k ec -q nistb409 -g 512 -s "CN=John Smith,O=Example Corp,
| L=Mountain View,ST=California,C=US" -d sql:/home/my/sharednssdb -p 650-5
| 55-0123 -a -o cert.cer
| Generating key. This may take a few moments...
| Certificate request generated by Netscape
| Phone: 650-555-0123
| Common Name: John Smith
| Email: (not ed)
| Organization: Example Corp
| State: California
| Country: US
| -----BEGIN NEW CERTIFICATE REQUEST-----
| MIIBIDCBywIBADBmMQswCQYDVQQGEwJVUzETMBEGA1UECBMKQ2FsaWZvcm5pYTEW
| MBQGA1UEBxMNTW91bnRhaW4gVmlldzEVMBMGA1UEChMMRXhhbXBsZSBDb3JwMRMw
| EQYDVQQDEwpKb2huIFNtaXRoMFwwDQYJKoZIhvcNAQEBBQADSwAwSAJBAMVUpDOZ
| KmHnOx7reP8Cc0Lk+fFWEuYIDX9W5K/BioQOKvEjXyQZhit9aThzBVMoSf1Y1S8J
| CzdUbCg1+IbnXaECAwEAAaAAMA0GCSqGSIb3DQEBBQUAA0EAryqZvpYrUtQ486Ny
| qmtyQNjIi1F8c1Z+TL4uFYlMg8z6LG/J/u1E5t1QqB5e9Q4+BhRbrQjRR1JZx3tB
| 1hP9Gg==
| -----END NEW CERTIFICATE REQUEST-----
| Creating a Certificate
| A valid certificate must be issued by a trusted CA. This can be
| done by specifying a CA certificate (-c) that is stored in the
| certificate database. If a CA key pair is not available, you
| can create a self-signed certificate using the -x argument with
| the -S command option.
| $ certutil -S -k rsa|dsa|ec -n certname -s subject [-c issuer \|-x] -t tr
| ustargs -d [sql:]directory [-m serial-number] [-v valid-months] [-w offs
| et-months] [-p phone] [-1] [-2] [-3] [-4] [-5 keyword] [-6 keyword] [-7
| emailAddress] [-8 dns-names] [--extAIA] [--extSIA] [--extCP] [--extPM] [
| --extPC] [--extIA] [--extSKID]
| The series of numbers and --ext\* options set certificate
| extensions that can be added to the certificate when it is
| generated by the CA.
| For example, this creates a self-signed certificate:
| $ certutil -S -s "CN=Example CA" -n my-ca-cert -x -t "C,C,C" -1 -2 -5 -m
| 3650
| From there, new certificates can reference the self-signed
| certificate:
| $ certutil -S -s "CN=My Server Cert" -n my-server-cert -c "my-ca-cert" -
| t "u,u,u" -1 -5 -6 -8 -m 730
| Generating a Certificate from a Certificate Request
| When a certificate request is created, a certificate can be
| generated by using the request and then referencing a
| certificate authority signing certificate (the issuer specified
| in the -c argument). The issuing certificate must be in the
| certificate database in the specified directory.
| certutil -C -c issuer -i cert-request-file -o output-file [-m serial-num
| ber] [-v valid-months] [-w offset-months] -d [sql:]directory [-1] [-2] [
| -3] [-4] [-5 keyword] [-6 keyword] [-7 emailAddress] [-8 dns-names]
| For example:
| $ certutil -C -c "my-ca-cert" -i /home/certs/cert.req -o cert.cer -m 010
| -v 12 -w 1 -d sql:/home/my/sharednssdb -1 nonRepudiation,dataEncipherme
| nt -5 sslClient -6 clientAuth -7 jsmith@example.com
| Generating Key Pairs
| Key pairs are generated automatically with a certificate
| request or certificate, but they can also be generated
| independently using the -G command option.
| certutil -G -d [sql:]directory \| -h tokenname -k key-type -g key-size [-
| y exponent-value] -q pqgfile|curve-name
| For example:
| $ certutil -G -h lunasa -k ec -g 256 -q sect193r2
| Listing Certificates
| The -L command option lists all of the certificates listed in
| the certificate database. The path to the directory (-d) is
| required.
| $ certutil -L -d sql:/home/my/sharednssdb
| Certificate Nickname Trust Attri
| butes
| SSL,S/MIME,
| JAR/XPI
| CA Administrator of Instance pki-ca1's Example Domain ID u,u,u
| TPS Administrator's Example Domain ID u,u,u
| Google Internet Authority ,,
| Certificate Authority - Example Domain CT,C,C
| Using additional arguments with -L can return and print the
| information for a single, specific certificate. For example,
| the -n argument passes the certificate name, while the -a
| argument prints the certificate in ASCII format:
| $ certutil -L -d sql:/home/my/sharednssdb -a -n "Certificate Authority -
| Example Domain"
| -----BEGIN CERTIFICATE-----
| MIIDmTCCAoGgAwIBAgIBATANBgkqhkiG9w0BAQUFADA5MRcwFQYDVQQKEw5FeGFt
| cGxlIERvbWFpbjEeMBwGA1UEAxMVQ2VydGlmaWNhdGUgQXV0aG9yaXR5MB4XDTEw
| MDQyOTIxNTY1OFoXDTEyMDQxODIxNTY1OFowOTEXMBUGA1UEChMORXhhbXBsZSBE
| b21haW4xHjAcBgNVBAMTFUNlcnRpZmljYXRlIEF1dGhvcml0eTCCASIwDQYJKoZI
| hvcNAQEBBQADggEPADCCAQoCggEBAO/bqUli2KwqXFKmMMG93KN1SANzNTXA/Vlf
| Tmrih3hQgjvR1ktIY9aG6cB7DSKWmtHp/+p4PUCMqL4ZrSGt901qxkePyZ2dYmM2
| RnelK+SEUIPiUtoZaDhNdiYsE/yuDE8vQWj0vHCVL0w72qFUcSQ/WZT7FCrnUIUI
| udeWnoPSUn70gLhcj/lvxl7K9BHyD4Sq5CzktwYtFWLiiwV+ZY/Fl6JgbGaQyQB2
| bP4iRMfloGqsxGuB1evWVDF1haGpFDSPgMnEPSLg3/3dXn+HDJbZ29EU8/xKzQEb
| 3V0AHKbu80zGllLEt2Zx/WDIrgJEN9yMfgKFpcmL+BvIRsmh0VsCAwEAAaOBqzCB
| qDAfBgNVHSMEGDAWgBQATgxHQyRUfKIZtdp55bZlFr+tFzAPBgNVHRMBAf8EBTAD
| AQH/MA4GA1UdDwEB/wQEAwIBxjAdBgNVHQ4EFgQUAE4MR0MkVHyiGbXaeeW2ZRa/
| rRcwRQYIKwYBBQUHAQEEOTA3MDUGCCsGAQUFBzABhilodHRwOi8vbG9jYWxob3N0
| LmxvY2FsZG9tYWluOjkxODAvY2Evb2NzcDANBgkqhkiG9w0BAQUFAAOCAQEAi8Gk
| L3XO43u7/TDOeEsWPmq+jZsDZ3GZ85Ajt3KROLWeKVZZZa2E2Hnsvf2uXbk5amKe
| lRxdSeRH9g85pv4KY7Z8xZ71NrI3+K3uwmnqkc6t0hhYb1mw/gx8OAAoluQx3biX
| JBDxjI73Cf7XUopplHBjjiwyGIJUO8BEZJ5L+TF4P38MJz1snLtzZpEAX5bl0U76
| bfu/tZFWBbE8YAWYtkCtMcalBPj6jn2WD3M01kGozW4mmbvsj1cRB9HnsGsqyHCu
| U0ujlL1H/RWcjn607+CTeKH9jLMUqCIqPJNOa+kq/6F7NhNRRiuzASIbZc30BZ5a
| nI7q5n1USM3eWQlVXw==
| -----END CERTIFICATE-----
| Listing Keys
| Keys are the original material used to encrypt certificate
| data. The keys generated for certificates are stored
| separately, in the key database.
| To list all keys in the database, use the -K command option and
| the (required) -d argument to give the path to the directory.
| $ certutil -K -d sql:/home/my/sharednssdb
| certutil: Checking token "NSS Certificate DB" in slot "NSS User Private
| Key and Certificate Services "
| < 0> rsa 455a6673bde9375c2887ec8bf8016b3f9f35861d Thawte Freemail
| Member's Thawte Consulting (Pty) Ltd. ID
| < 1> rsa 40defeeb522ade11090eacebaaf1196a172127df Example Domain
| Administrator Cert
| < 2> rsa 1d0b06f44f6c03842f7d4f4a1dc78b3bcd1b85a5 John Smith user
| cert
| There are ways to narrow the keys listed in the search results:
| \* To return a specific key, use the -n name argument with the
| name of the key.
| \* If there are multiple security devices loaded, then the -h
| tokenname argument can search a specific token or all
| tokens.
| \* If there are multiple key types available, then the -k
| key-type argument can search a specific type of key, like
| RSA, DSA, or ECC.
| Listing Security Modules
| The devices that can be used to store certificates -- both
| internal databases and external devices like smart cards -- are
| recognized and used by loading security modules. The -U command
| option lists all of the security modules listed in the
| secmod.db database. The path to the directory (-d) is required.
| $ certutil -U -d sql:/home/my/sharednssdb
| slot: NSS User Private Key and Certificate Services
| token: NSS Certificate DB
| slot: NSS Internal Cryptographic Services
| token: NSS Generic Crypto Services
| Adding Certificates to the Database
| Existing certificates or certificate requests can be added
| manually to the certificate database, even if they were
| generated elsewhere. This uses the -A command option.
| certutil -A -n certname -t trustargs -d [sql:]directory [-a] [-i input-f
| ile]
| For example:
| $ certutil -A -n "CN=My SSL Certificate" -t "u,u,u" -d sql:/home/my/shar
| ednssdb -i /home/example-certs/cert.cer
| A related command option, -E, is used specifically to add email
| certificates to the certificate database. The -E command has
| the same arguments as the -A command. The trust arguments for
| certificates have the format SSL,S/MIME,Code-signing, so the
| middle trust settings relate most to email certificates (though
| the others can be set). For example:
| $ certutil -E -n "CN=John Smith Email Cert" -t ",Pu," -d sql:/home/my/sh
| arednssdb -i /home/example-certs/email.cer
| Deleting Certificates to the Database
| Certificates can be deleted from a database using the -D
| option. The only required options are to give the security
| database directory and to identify the certificate nickname.
| certutil -D -d [sql:]directory -n "nickname"
| For example:
| $ certutil -D -d sql:/home/my/sharednssdb -n "my-ssl-cert"
| Validating Certificates
| A certificate contains an expiration date in itself, and
| expired certificates are easily rejected. However, certificates
| can also be revoked before they hit their expiration date.
| Checking whether a certificate has been revoked requires
| validating the certificate. Validation can also be used to
| ensure that the certificate is only used for the purposes it
| was initially issued for. Validation is carried out by the -V
| command option.
| certutil -V -n certificate-name [-b time] [-e] [-u cert-usage] -d [sql:]
| directory
| For example, to validate an email certificate:
| $ certutil -V -n "John Smith's Email Cert" -e -u S,R -d sql:/home/my/sha
| rednssdb
| Modifying Certificate Trust Settings
| The trust settings (which relate to the operations that a
| certificate is allowed to be used for) can be changed after a
| certificate is created or added to the database. This is
| especially useful for CA certificates, but it can be performed
| for any type of certificate.
| certutil -M -n certificate-name -t trust-args -d [sql:]directory
| For example:
| $ certutil -M -n "My CA Certificate" -d sql:/home/my/sharednssdb -t "CTu
| ,CTu,CTu"
| Printing the Certificate Chain
| Certificates can be issued in chains because every certificate
| authority itself has a certificate; when a CA issues a
| certificate, it essentially stamps that certificate with its
| own fingerprint. The -O prints the full chain of a certificate,
| going from the initial CA (the root CA) through ever
| intermediary CA to the actual certificate. For example, for an
| email certificate with two CAs in the chain:
| $ certutil -d sql:/home/my/sharednssdb -O -n "jsmith@example.com"
| "Builtin Object Token:Thawte Personal Freemail CA" [E=personal-freemail@
| thawte.com,CN=Thawte Personal Freemail CA,OU=Certification Services Divi
| sion,O=Thawte Consulting,L=Cape Town,ST=Western Cape,C=ZA]
| "Thawte Personal Freemail Issuing CA - Thawte Consulting" [CN=Thawte P
| ersonal Freemail Issuing CA,O=Thawte Consulting (Pty) Ltd.,C=ZA]
| "(null)" [E=jsmith@example.com,CN=Thawte Freemail Member]
| Resetting a Token
| The device which stores certificates -- both external hardware
| devices and internal software databases -- can be blanked and
| reused. This operation is performed on the device which stores
| the data, not directly on the security databases, so the
| location must be referenced through the token name (-h) as well
| as any directory path. If there is no external token used, the
| default value is internal.
| certutil -T -d [sql:]directory -h token-name -0 security-officer-passwor
| d
| Many networks have dedicated personnel who handle changes to
| security tokens (the security officer). This person must supply
| the password to access the specified token. For example:
| $ certutil -T -d sql:/home/my/sharednssdb -h nethsm -0 secret
| Upgrading or Merging the Security Databases
| Many networks or applications may be using older BerkeleyDB
| versions of the certificate database (cert8.db). Databases can
| be upgraded to the new SQLite version of the database
| (cert9.db) using the --upgrade-merge command option or existing
| databases can be merged with the new cert9.db databases using
| the ---merge command.
| The --upgrade-merge command must give information about the
| original database and then use the standard arguments (like -d)
| to give the information about the new databases. The command
| also requires information that the tool uses for the process to
| upgrade and write over the original database.
| certutil --upgrade-merge -d [sql:]directory [-P dbprefix] --source-dir d
| irectory --source-prefix dbprefix --upgrade-id id --upgrade-token-name n
| ame [-@ password-file]
| For example:
| $ certutil --upgrade-merge -d sql:/home/my/sharednssdb --source-dir /opt
| /my-app/alias/ --source-prefix serverapp- --upgrade-id 1 --upgrade-token
| -name internal
| The --merge command only requires information about the
| location of the original database; since it doesn't change the
| format of the database, it can write over information without
| performing interim step.
| certutil --merge -d [sql:]directory [-P dbprefix] --source-dir directory
| --source-prefix dbprefix [-@ password-file]
| For example:
| $ certutil --merge -d sql:/home/my/sharednssdb --source-dir /opt/my-app/
| alias/ --source-prefix serverapp-
| Running certutil Commands from a Batch File
| A series of commands can be run sequentially from a text file
| with the -B command option. The only argument for this
| specifies the input file.
| $ certutil -B -i /path/to/batch-file
| NSS Database Types
| NSS originally used BerkeleyDB databases to store security
| information. The last versions of these legacy databases are:
| \* cert8.db for certificates
| \* key3.db for keys
| \* secmod.db for PKCS #11 module information
| BerkeleyDB has performance limitations, though, which prevent
| it from being easily used by multiple applications
| simultaneously. NSS has some flexibility that allows
| applications to use their own, independent database engine
| while keeping a shared database and working around the access
| issues. Still, NSS requires more flexibility to provide a truly
| shared security database.
| In 2009, NSS introduced a new set of databases that are SQLite
| databases rather than BerkleyDB. These new databases provide
| more accessibility and performance:
| \* cert9.db for certificates
| \* key4.db for keys
| \* pkcs11.txt, which is listing of all of the PKCS #11 modules
| contained in a new subdirectory in the security databases
| directory
| Because the SQLite databases are designed to be shared, these
| are the shared database type. The shared database type is
| preferred; the legacy format is included for backward
| compatibility.
| By default, the tools (certutil, pk12util, modutil) assume that
| the given security databases follow the more common legacy
| type. Using the SQLite databases must be manually specified by
| using the sql: prefix with the given security directory. For
| example:
| $ certutil -L -d sql:/home/my/sharednssdb
| To set the shared database type as the default type for the
| tools, set the NSS_DEFAULT_DB_TYPE environment variable to sql:
| export NSS_DEFAULT_DB_TYPE="sql"
| This line can be set added to the ~/.bashrc file to make the
| change permanent.
| Most applications do not use the shared database by default,
| but they can be configured to use them. For example, this
| how-to article covers how to configure Firefox and Thunderbird
| to use the new shared NSS databases:
| For an engineering draft on the changes in the shared NSS
| databases, see the NSS project wiki:
| See Also
| pk12util (1)
| modutil (1)
| certutil has arguments or operations that use features defined
| in several IETF RFCs.
| The NSS wiki has information on the new database design and how
| to configure applications to use it.
| Additional Resources
| For information about NSS and other tools related to NSS (like
| JSS), check out the NSS project wiki at
|
`http://www.mozilla.org/projects/security/pki/nss/ <https://www.mozilla.org/projects/security/pki/nss/>`__.
The NSS site
| relates directly to NSS code changes and releases.
| Mailing lists:
| IRC: Freenode at #dogtag-pki
| Authors
| The NSS tools were written and maintained by developers with
| Netscape, Red Hat, Sun, Oracle, Mozilla, and Google.
| Authors: Elio Maldonado <emaldona@redhat.com>, Deon Lackey
| <dlackey@redhat.com>.
| LICENSE
| Licensed under the Mozilla Public License, v. 2.0. If a copy of the MPL was not
distributed with this file, You can
| NOTES