702 lines
No EOL
40 KiB
ReStructuredText
702 lines
No EOL
40 KiB
ReStructuredText
.. _mozilla_projects_nss_tools_certutil:
|
|
|
|
certutil
|
|
========
|
|
|
|
.. container::
|
|
|
|
| Name
|
|
| certutil — Manage keys and certificate in the NSS database.
|
|
| Synopsis
|
|
| certutil [options] `arguments <arguments>`__
|
|
| Description
|
|
| The Certificate Database Tool, certutil, is a command-line utility that
|
|
| can create and modify certificate and key database files. It can also
|
|
| list, generate, modify, or delete certificates within the database, 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.
|
|
| The key and certificate management process generally begins with creating
|
|
| keys in the key database, then generating and managing certificates in the
|
|
| certificate database. This document discusses certificate and key database
|
|
| management. For information security module database management, see the
|
|
| modutil manpages.
|
|
| Options and Arguments
|
|
| Running certutil always requires one (and only one) option to specify the
|
|
| type of certificate operation. Each option may take arguments, anywhere
|
|
| from none to multiple arguments. Run the command option and -H to see the
|
|
| arguments available for each command option.
|
|
| Options
|
|
| Options specify an action and are uppercase.
|
|
| -A
|
|
| Add an existing certificate to a certificate database. The
|
|
| certificate database should already exist; if one is not present,
|
|
| this 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.
|
|
| -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 a source database into the target database. This is used to
|
|
| merge legacy NSS databases (cert8.db and key3.db) into the newer
|
|
| SQLite databases (cert9.db and key4.db).
|
|
| --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
|
|
| Option arguments modify an action and are lowercase.
|
|
| -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 [sql:]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). If the prefix sql:
|
|
| is not used, then the tool assumes that the given databases are in
|
|
| the old format.
|
|
| -e
|
|
| Check a certificate's signature during the process of validating a
|
|
| certificate.
|
|
| -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 8192 bits. The
|
|
| default is 1024 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 (specifically,
|
|
| internal slot 2). This slot can also be explicitly named with the
|
|
| string "internal". An internal slots is a virtual slot maintained
|
|
| in software, rather than a hardware device. Internal slot 2 is
|
|
| used by key and certificate services. Internal slot 1 is used by
|
|
| cryptographic services.
|
|
| -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. 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. The default serial number
|
|
| is 0 (zero). 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 option is provided as a special case. Changing the names of
|
|
| the certificate and key databases is not recommended.
|
|
| -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
|
|
| 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.
|
|
| -q curve-name
|
|
| Set the elliptic curve name to use when generating ECC key pairs.
|
|
| A complete list of ECC curves is given in the help (-H).
|
|
| -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:
|
|
| o p - Valid peer
|
|
| o P - Trusted peer (implies p)
|
|
| o c - Valid CA
|
|
| o T - Trusted CA to issue client certificates (implies c)
|
|
| o C - Trusted CA to issue server certificates (SSL only)
|
|
| (implies c)
|
|
| o u - Certificate can be used for authentication or signing
|
|
| o 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 "TCu,Cu,Tuw"
|
|
| Use the -L option to see a list of the current certificates and
|
|
| trust attributes in a certificate database.
|
|
| -u certusage
|
|
| Specify a usage context to apply when validating a certificate
|
|
| with the -V option.
|
|
| The contexts are the following:
|
|
| o C (as an SSL client)
|
|
| o V (as an SSL server)
|
|
| o S (as an email signer)
|
|
| o R (as an email recipient)
|
|
| o O (as an OCSP status responder)
|
|
| o 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:
|
|
| o digital signature
|
|
| o nonRepudiation
|
|
| o keyEncipherment
|
|
| o dataEncipherment
|
|
| o keyAgreement
|
|
| o certSigning
|
|
| o crlSigning
|
|
| o 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:
|
|
| o sslClient
|
|
| o sslServer
|
|
| o smime
|
|
| o objectSigning
|
|
| o sslCA
|
|
| o smimeCA
|
|
| o objectSigningCA
|
|
| o 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:
|
|
| o serverAuth
|
|
| o clientAuth
|
|
| o codeSigning
|
|
| o emailProtection
|
|
| o timeStamp
|
|
| o ocspResponder
|
|
| o stepUp
|
|
| o 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:
|
|
| o cert8.db or cert9.db
|
|
| o key3.db or key4.db
|
|
| o 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 subject [-h tokenname]
|
|
-d [sql:]directory [-p phone] [-o output-file] [-a]
|
|
| The -R command options requires four arguments:
|
|
| o -k to specify either the key type to generate or, when renewing a
|
|
| certificate, the existing key pair to use
|
|
| o -g to set the keysize of the key to generate
|
|
| o -s to set the subject name of the certificate
|
|
| o -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-555-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 trustargs -d
|
|
[sql:]directory [-m serial-number] [-v valid-months] [-w offset-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-number] [-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,dataEncipherment -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 Attributes
|
|
| 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:
|
|
| o To return a specific key, use the -n name argument with the name of
|
|
| the key.
|
|
| o If there are multiple security devices loaded, then the -h tokenname
|
|
| argument can search a specific token or all tokens.
|
|
| o 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-file]
|
|
| For example:
|
|
| $ certutil -A -n "CN=My SSL Certificate" -t "u,u,u" -d sql:/home/my/sharednssdb -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/sharednssdb -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/sharednssdb
|
|
| 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 Division,O=Thawte Consulting,L=Cape
|
|
Town,ST=Western Cape,C=ZA]
|
|
| "Thawte Personal Freemail Issuing CA - Thawte Consulting" [CN=Thawte Personal 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-password
|
|
| 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 directory
|
|
--source-prefix dbprefix --upgrade-id id --upgrade-token-name name [-@ 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:
|
|
| o cert8.db for certificates
|
|
| o key3.db for keys
|
|
| o 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:
|
|
| o cert9.db for certificates
|
|
| o key4.db for keys
|
|
| o 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:
|
|
| o https://wiki.mozilla.org/NSS_Shared_DB_Howto
|
|
| For an engineering draft on the changes in the shared NSS databases, see
|
|
| the NSS project wiki:
|
|
| o https://wiki.mozilla.org/NSS_Shared_DB
|
|
| See Also
|
|
| pk12util (1)
|
|
| modutil (1)
|
|
| certutil has arguments or operations that use features defined in several
|
|
| IETF RFCs.
|
|
| o `http://tools.ietf.org/html/rfc5280 <https://datatracker.ietf.org/doc/html/rfc5280>`__
|
|
| o `http://tools.ietf.org/html/rfc1113 <https://datatracker.ietf.org/doc/html/rfc1113>`__
|
|
| o `http://tools.ietf.org/html/rfc1485 <https://datatracker.ietf.org/doc/html/rfc1485>`__
|
|
| The NSS wiki has information on the new database design and how to
|
|
| configure applications to use it.
|
|
| o https://wiki.mozilla.org/NSS_Shared_DB_Howto
|
|
| o https://wiki.mozilla.org/NSS_Shared_DB
|
|
| Additional Resources
|
|
| For information about NSS and other tools related to NSS (like JSS), check
|
|
| out the NSS project wiki at
|
|
|
|
|
[1]\ `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: https://lists.mozilla.org/listinfo/dev-tech-crypto
|
|
| IRC: Freenode at #dogtag-pki
|
|
| Authors
|
|
| The NSS tools were written and maintained by developers with Netscape, Red
|
|
| Hat, and Sun.
|
|
| Authors: Elio Maldonado <emaldona@redhat.com>, Deon Lackey
|
|
| <dlackey@redhat.com>.
|
|
| Copyright
|
|
| (c) 2010, Red Hat, Inc. Licensed under the GNU Public License version 2.
|
|
| References
|
|
| Visible links
|
|
| 1.
|
|
`http://www.mozilla.org/projects/security/pki/nss/ <https://www.mozilla.org/projects/security/pki/nss/>`__ |