Red Hat Summit Red Hat SummitSuporteConsoleDesenvolvedoresComeçar um testeContato

Este conteúdo não está disponível no idioma selecionado.

Chapter 10. Managing certificate/key crypto token

This chapter contains instructions on how to manage certificate/key token database on the crypto tokens, specifically on how to import and verify certificates for various scenarios.

10.1. About certutil and PKICertImport
Copiar o link

The certutil command is provided by Netscape Security Services (NSS). certutil is used for validating and importing certificates. A basic overview of how we use certutil is presented below, however, PKICertImport is our wrapper script of choice for safely validating and importing certificates. Using certutil to do so requires multiple command invocations and correct usage is outside the scope of this documentation.

10.1.1. certutil basic usage
Copiar o link

certutil [command] [opt][options]

Each certutil invocation takes a command flag, usually denoted by a capital letter, and a series of options which control what the command does. If an option takes a value, that value is named between "<" and ">" symbols.

10.1.2. PKICertImport basic usage
Copiar o link

PKICertImport [opt][options]

Each PKICertImport invocation takes a series of options to validate and import a specified certificate. Unlike the broad use cases of certutil, PKICertImport is only focused on safely importing and validating certificates. See Section 10.1.4, “Common certutil and PKICertImport options” for more information about available options.

Note

PKICertImport prompts for the nssdb and/or HSM passwords multiple times throughout the course of its execution. This is expected as PKICertImport has to interact with the nssdb multiple times. To avoid having to input the nssdb password repetitively, specify a password file via -f <filename>. When done, be sure to delete the password file.

10.1.3. certutil common commands
Copiar o link

The following commands are specific to certutil and provide a brief overview of several common commands. PKICertImport is not compatible with nor require these command flags.

certutil -A

The -A command denotes "adding" a certificate. It requires a certificate to import (-i), a nickname (-n) for that certificate, and a series of trust flags (-t) for the certificate.

certutil -V

The -V command denotes "verifying" a certificate. It requires a certificate nickname to validate (-n) and a type of verification (-u) to perform.

certutil -D

The -D command denotes "deleting" a certificate. It requires a certificate nickname (-n) to remove.

Note that it ONLY removes the PUBLIC KEY portion of the certificate, and WILL NOT remove any private keys, if present.

certutil -M

The -M command denotes "modifying" a certificate. It requires a certificate nickname (-n) to modify, and a series of trust flags (-t) to give the certificate.

certutil -L

The -L command denotes "listing" a certificate or all certificates. If given the nickname option (-n), it will list detailed information about that certificate, else if omitted, it will list general information about all certificates present.

The result of certutil -L would show each certificate by its nickname along with its trust info. For example:

Expand
Table 10.1. Certificate nickname and trust info
Certificate NicknameTrust Attributes SSL, S/MIME, JAR/XPI

caSigningCert pki-ca1

CT, C, C

Note

The trust attributes displayed by certutil -L correspond to what is specified with the -t option.

The certutil -L does not modify the database, and can thus be executed safely as many times as desired.

10.1.4. Common certutil and PKICertImport options
Copiar o link

When following the steps below, ensure the values are relevant and correct for your specific deployment scenario. Many of these options are available to PKICertImport as well.

-n <nickname>

The -n <nickname> option specifies the nickname for a certificate. This can be any text and is only used as a reference to the certificate. It MUST be unique.

Update this value as appropriate for your configuration.

-d <directory>

The -d <directory> option specifies the path to the nssdb directory in use. We usually assume you are already in this directory and use "." to refer to the current directory.

Update this value as appropriate for your configuration.

-t <trust>

The -t <trust> option specifies the trust level for the certificate.

There are three main categories of trust:

  • trust for TLS
  • trust for email
  • trust for object signing

Each trust position can have one or more trust letters which specify the desired level of trust. The trust letters we use below are c, C, and T.

  • c states that this certificate should be a Certificate Authority (CA).
  • C states that this is a trusted certificate authority for signing server certificates (C implies lowercase c, hence you do not need to specify both).
  • T states that this certificate is a trusted authority for signing client certificates (T implies lowercase c, hence you do not need to specify both T and c).

To specify the trust flags for each position, join the letters with commas. For example, the option -t CT,C,c means that the certificate is trusted for signing client and server TLS certificates, signing server email certificates (S/MIME), and is a valid CA for object signing (though untrusted).

  • This ensures that, if this certificate signs another certificate, which in turn is used for object signing, it will be deemed invalid.

No trust (or the lack of trust) can be specified by using -t ,,.

To see the trust levels of all certificates in the database, run:

  • certutil -L -d
  • Each certificate’s nickname will be listed and the trust flags will be specified at the end of the line.

See the notes about HSMs in the -h option.

Note that more trust levels are specified in the certutil man page. To reference this documentation, please run the man certutil command on a system with certutil properly installed.

-h <HSM>

The -h <HSM> option specifies the name of the HSM to perform operations on.

-h option is incompatible with the -t option, as HSMs cannot store trust. Only an nssdb can store trust, so using the certutil -A command or the certutil -M command in conjunction with -h <HSM> will fail. Instead, specify the desired trust level on a separate certutil -M command without the -h option.

Update this value as appropriate for your configuration.

-e

The -e option specifies that the validity of the signature is checked as well, when used in conjunction with the certutil -V command. PKICertImport always performs the certificate signature validation and does not understand the -e option.

-a

The -a option specifies that the key in question is in PEM (ASCII) format.

-i <certificate>

The -i <certificate> option specifies the path to the certificate. This is only used in the certutil -A command to specify the path to the certificate to import.

Update this value as appropriate for your configuration.

-u <usage>

The -u <usage> option specifies that usage of the certificate to verify when used in conjunction with the certutil -V command.

There are several usage letters referenced in the following sections.

  • -u C stands for verify a client TLS certificate. Note that this mostly accepts any certificate, but will check expiration date and signature.
  • -u V stands for verify a server TLS certificate. Note that this will reject CA certificates and will check expiration date and signature.
  • -u L stands for verify a CA TLS certificate. Note that this will validate trust flags (to see if c is present) and will check key usage to ensure that the key is a CA key. This also checks expiration and signatures.
  • -u O stands for verify a OCSP status responder certificate. Note that this checks expiry and signatures.
  • -u J stands for verify an object signing certificate. Note that this checks expiry and signatures.

If the wrong usage option is specified or the trust flags on the certificate are wrong (such as a missing c flag for an CA TLS certificate), certutil -V will give incorrect results.

Note

More usage options are specified in the certutil man page. To reference this documentation, run the man certutil command on a system with certutil properly installed.

10.2. Importing a root certificate
Copiar o link

Ensure that your web service is taken offline (stopped, disabled, etc.) while performing these steps and ensure no concurrent access to the nssdb by other processes (such as a browser). Doing so may corrupt the nssdb or result in improper usage of these certificates.

When needing to import a new root certificate, ensure you acquire this certificate in a secure manner as it will be able to sign a number of certificates. We assume you already have it in a file named ca_root.crt. Please substitute the correct name and path to this file as appropriate for your scenario.

For more information about the certutil and PKICertImport options used below, see Section 10.1, “About certutil and PKICertImport”.

Procedure

  1. First, change directories into the nssdb: 

    # cd /path/to/nssdb
    Copy to Clipboard Toggle word wrap

  2. To import the root certificate: 

    # PKICertImport -d . -n "CA Root" -t "CT,C,C" -a -i ca_root.crt -u L
    Copy to Clipboard Toggle word wrap

    This command validates and imports the root certificate into your nssdb. The validation succeeds when no error message is printed and the return code is 0. To check the return code, execute echo $? immediately after executing the previous command above. In most cases, a visual error message is printed. The certificate usually fails to validate because it is expired or because it is not a CA certificate. Therefore, make sure your certificate file is correct and up-to-date. Contact the issuer and ensure that all intermediate and root certificates are present on your system.

10.3. Importing an intermediate certificate chain
Copiar o link

Ensure that your web service is offline (stopped, disabled, etc.) while performing these steps and ensure no concurrent access to the nssdb by other processes (such as a browser). Doing so may corrupt the nssdb or result in improper usage of these certificates.

If you have not imported and trusted the root certificate, see Section 10.2, “Importing a root certificate”.

When given a series of intermediate certificates between your root and end server or client certificates, we need to import and validate the signed certificate chain in order from closest to furthest from the root CA certificate. We assume the Intermediate CAs are in files named ca_sub_<num>.crt (for example ca_sub_1.crt, ca_sub_2.crt, and so on). Substitute names and paths for your certificates as appropriate to your deployment.

Note

In the unlikely scenario that you are instead given a single file named fullchain.crt, fullchain.pem, or similar and it contains multiple certificates, split it into the above format by copying each block (between and including the ----BEGIN CERTIFICATE----- and an -----END CERTIFICATE----- markers) to its own file. The first ones should be named ca_sub_<num>.crt and the last will be your server cert named service.crt. Server certificates are discussed in later sections.

First, we will import and validate any intermediate CAs in order of closest to furthest from the root CA certificate. If you don’t have any, you can skip to the next section.

For more information about the certutil and PKICertImport options used below, see Section 10.1, “About certutil and PKICertImport”.

Procedure

  1. Before beginning, please change directories into the nssdb: 

    # cd /path/to/nssdb
    Copy to Clipboard Toggle word wrap

  2. For every intermediate certificate in the chain, run the following command: 

    # PKICertImport -d . -n "CA Sub $num" -t "CT,C,C" -a -i ca_sub_$num.crt -u L
    Copy to Clipboard Toggle word wrap

    This command validates and imports the Intermediate CA certificate into your nssdb. The validation succeeds when no error message is printed and the return code is 0. To check the return code, execute echo $? immediately after executing the previous command above. In most cases, a visual error message is printed. If the validation does not succeed, contact the issuer and ensure that all intermediate and root certificates are present on your system.

10.4. Hardware Security Module
Copiar o link

This section provides information on how to detect, view and import certificates into a hardware cryptographic module (HSM).

10.4.1. Detecting Tokens
Copiar o link

Once you have installed Certificate System, to see if a token can be detected, use the TokenInfo utility, pointing to the alias directory for the subsystem instance. This tool is available after you install the Certificate System packages.

  • For example: 

    # TokenInfo /var/lib/pki/rhcs10-ECC-SubCA/alias

Database Path: .
Found external module 'NSS Internal PKCS #11 Module'
Found external module 'nfast'
Found external module 'p11-kit-proxy'
Found external token 'accelerator'
Found external token 'NHSM-CONN-XC'
    Copy to Clipboard Toggle word wrap

    This utility returns all tokens that can be detected by the Certificate System, not only tokens that are installed in the Certificate System.

10.4.2. Viewing tokens
Copiar o link

Once you have installed Certificate System, to view the list of the tokens, use the modutil utility.

  1. Change to the instance alias directory. For example: 

    # cd /var/lib/pki/pki-tomcat/alias
    Copy to Clipboard Toggle word wrap

  2. Show the information about the installed PKCS #11 modules installed as well as information on the corresponding tokens using the modutil tool. 

    # modutil -dbdir . -nocertdb -list
    Copy to Clipboard Toggle word wrap

10.4.3. Importing certificates onto the HSM
Copiar o link

The following procedure describes how to import a certificate into an HSM after gaining a newly issued certificate (such as when a TLS server certificate is newly issued or renewed) whose keys were generated on the same HSM token as the process of creating a CSR.

Note

Normally, for a Certificate System server, pkispawn takes care of all system certificate creations and imports during installation. However, this procedure can still be useful when for instance you need to replace one of your system certificates.

Here we give examples to four types of certificates to import onto a HSM:

  • server certificate
  • client certificate
  • object signing certificate:
  • OCSP response signing certificate

Before beginning, please change directories into the nssdb: 

# cd /path/to/nssdb
Copy to Clipboard Toggle word wrap

For example: 

# cd /var/lib/pki/pki-ca/alias
Copy to Clipboard Toggle word wrap

Ensure that your web service is taken offline (stopped, disabled, etc.) while performing these steps and ensure no concurrent access to the nssdb by other processes (such as a browser). Doing so may corrupt the nssdb or result in improper usage of these certificates.

If you have not imported and trusted the root certificate, see Section 10.2, “Importing a root certificate”. If you have not imported and validated the intermediate certificates, see Section 10.3, “Importing an intermediate certificate chain”.

Note that which set of instructions you follow will depend on the usage for the certificate in question.

  • For TLS server certs for all PKI substems, follow the server certificate steps.
  • For any subsystem’s audit signing cert, follow the steps below for validating an object Signing certificate.
  • For the CA subsystem’s signing cert, follow the steps above for importing and validating an intermediate certificate chain, but do so only with the caSigningCert.
  • For the CA subsystem’s OCSP signing cert, follow the steps below for validating an OCSP certificate.
  • For all other system certs of the PKI subsystems, follow the Client Certificate steps.

For more information about the certutil and PKICertImport options used below, see Section 10.1, “About certutil and PKICertImport”.

NOTE

On a system set in FIPS mode, PKICertImport will return a superfluous error message, which you can ignore (BZ#1393668): 

certutil: could not change trust on certificate: SEC_ERROR_TOKEN_NOT_LOGGED_IN: The operation failed because the PKCS#11 token is not logged in.
e: certutil returned non-zero value: 255
e: Unable to import certificate to NSS DB: ..
Copy to Clipboard Toggle word wrap

To import a server certificate:

  • PKICertImport -d . -h HSM -f password_file -n "host.name.example.com" -t ",," -a -i service.crt -u V

    This command validates and imports the server certificate onto the HSM. The validation succeeds when no error message is printed and the return code is 0. To check the return code, execute echo $? immediately after executing the previous command above. In most cases, a visual error message is printed. The certificate usually fails to validate due to expiry of a parent certificate or a missing CA trust chain (such as a missing intermediate certificate or a missing CA Root). If the validation does not succeed, contact the issuer and ensure that all intermediate and root certificates are present on your system.

To import a client certificate:

  • PKICertImport -d . -h HSM -f password_file -n "client name" -t ",," -a -i client.crt -u C

    This command validates and imports the client certificate onto the HSM. The validation succeeds when no error message is printed and the return code is 0. To check the return code, execute echo $? immediately after executing the previous command above. In most cases, a visual error message is printed. If the validation does not succeed, contact the issuer and ensure that all intermediate and root certificates are present on your system.

To import an object signing certificate:

  • PKICertImport -d . -h HSM -f password_file -n "certificate name" -t ",,P" -a -i objectsigning.crt -u J

    This command validates and imports the object signing certificate onto the HSM. The validation succeeds when no error message is printed and the return code is 0. To check the return code, execute echo $? immediately after executing the previous command above. In most cases, a visual error message is printed. If the validation does not succeed, contact the issuer and ensure that all intermediate and root certificates are present on your system.

To import an OCSP response signing certificate:

  • PKICertImport -d . -h HSM -f password_file -n "certificate name" -t ",," -a -i ocsp.crt -u O

    This command validates and imports the OCSP responder certificate onto the HSM. The validation succeeds when no error message is printed and the return code is 0. To check the return code, execute echo $? immediately after executing the previous command above. In most cases, a visual error message is printed. If the validation does not succeed, contact the issuer and ensure that all intermediate and root certificates are present on your system.

10.5. Importing a certificate into an NSS database
Copiar o link

Ensure that your web service is taken offline (stopped, disabled, etc.) while performing these steps and ensure no concurrent access to the NSS database by other processes (such as a browser). Doing so may corrupt the NSS database or result in improper usage of these certificates.

Note that which set of instructions you follow will depend on the usage for the certificate in question.

  • For any subsystem’s auditSigningCert, please follow the steps below for validating an object Signing certificate.
  • For the CA subsystem’s caSigningCert, please follow the steps above for importing and validating an intermediate certificate chain, but do so only with the caSigningCert.
  • For the CA subsystem’s ocspSigningCert, please follow the steps below for validating an OCSP certificate.
  • For user’s client or S/MIME certificate, follow the Client Certificate steps.

For more information about the certutil and PKICertImport options used below, see Section 10.1, “About certutil and PKICertImport”.

10.5.1. Importing a client certificate into the NSS database
Copiar o link

To import a client certificate into the NSS database:

  1. Change into the NSS database directory. For example: 

    # cd /path/to/nssdb/
    Copy to Clipboard Toggle word wrap
  2. Import and trust the root certificate, if it is not already imported and trusted. For details, see Section 10.2, “Importing a root certificate”.
  3. Import and validate the intermediate certificates, if not already imported and validated. For details, see Section 10.3, “Importing an intermediate certificate chain”.

  4. Validate and import the client certificate: 

    # PKICertImport -d . -n "client name" -t ",," -a -i client.crt -u C
    Copy to Clipboard Toggle word wrap

    The validation succeeds when no error message is printed and the return code is 0. To check the return code, execute echo $? immediately after executing the previous command above. In most cases, a visual error message is printed. If the validation does not succeed, contact the issuer and ensure that all intermediate and root certificates are present on your system.

10.5.2. Importing an object signing certificate
Copiar o link

To import an object signing certificate:

  1. Change into the NSS database directory. For example: 

    # cd /path/to/nssdb/
    Copy to Clipboard Toggle word wrap
  2. Import and trust the root certificate, if it is not already imported and trusted. For details, see Section 10.2, “Importing a root certificate”.
  3. Import and validate the intermediate certificates, if not already imported and validated. For details, see Section 10.3, “Importing an intermediate certificate chain”.

  4. Validate and import the object signing certificate: 

    # PKICertImport -d . -n "certificate name" -t ",,P" -a -i objectsigning.crt -u J
    Copy to Clipboard Toggle word wrap

    The validation succeeds when no error message is printed and the return code is 0. To check the return code, execute echo $? immediately after executing the previous command above. In most cases, a visual error message is printed. If the validation does not succeed, contact the issuer and ensure that all intermediate and root certificates are present on your system.

10.5.3. Importing an OCSP responder
Copiar o link

To import an OCSP responder:

  1. Change into the NSS database directory. For example: 

    # cd /path/to/nssdb/
    Copy to Clipboard Toggle word wrap
  2. Import and trust the root certificate, if it is not already imported and trusted. For details, see Section 10.2, “Importing a root certificate”.
  3. Import and validate the intermediate certificates, if not already imported and validated. For details, see Section 10.3, “Importing an intermediate certificate chain”.

  4. Validate and import the OCSP responder certificate: 

    # PKICertImport -d . -n "certificate name" -t ",," -a -i ocsp.crt -u O
    Copy to Clipboard Toggle word wrap

    The validation succeeds when no error message is printed and the return code is 0. To check the return code, execute echo $? immediately after executing the previous command above. In most cases, a visual error message is printed. If the validation does not succeed, contact the issuer and ensure that all intermediate and root certificates are present on your system.

Voltar ao topo
Red Hat logoGithubredditYoutubeTwitter

Aprender

Experimente, compre e venda

Comunidades

Sobre a documentação da Red Hat

Ajudamos os usuários da Red Hat a inovar e atingir seus objetivos com nossos produtos e serviços com conteúdo em que podem confiar. Explore nossas atualizações recentes.

Tornando o open source mais inclusivo

A Red Hat está comprometida em substituir a linguagem problemática em nosso código, documentação e propriedades da web. Para mais detalhes veja o Blog da Red Hat.

Sobre a Red Hat

Fornecemos soluções robustas que facilitam o trabalho das empresas em plataformas e ambientes, desde o data center principal até a borda da rede.

Theme

© 2025 Red Hat