Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 5. Requesting, enrolling and managing certificates

Certificates are requested and used by end users. Although certificate enrollment and renewal are operations that are not limited to administrators, understanding the enrollment and renewal processes can make it easier for administrators to manage and create appropriate certificate profiles, as described in Section 3.2, “Setting up certificate profiles”, and to use fitting authentication methods (described in Chapter 8, Authentication for enrolling certificates) for each certificate type.

This chapter discusses requesting, receiving, and renewing certificates for use outside Certificate System. For information on requesting and renewing Certificate System subsystem certificates, see Chapter 13, Managing subsystem certificates.

5.1. About enrolling and renewing certificates
Copy link

Enrollment is the process for requesting and receiving a certificate. The mechanics for the enrollment process are slightly different depending on the type of certificate, the method for generating its key pair, and the method for generating and approving the certificate itself. Whatever the specific method, certificate enrollment, at a high level, has the same basic steps:

  1. A certificate request (CSR) is generated.
  2. The certificate request is submitted to the CA.
  3. The request is verified by authenticating the entity which requested it and by confirming that the request meets the certificate profile rules which were used to submit it.
  4. The request is approved.
  5. The requesting party retrieves the new certificate.

When the certificate reaches the end of its validity period, it can be renewed.

5.2. Creating certificate signing requests (CSR)
Copy link

As explained in 2.4.1.1.2.2 Enrolling with CMC section in the Planning, Installation and Deployment Guide (Common Criteria Edition), the CMCRequest utility accepts Certificate Signing Requests (CSR) in PKCS #10 and CRMF format.

Red Hat Certificate System supports using the following utilities to create CSRs:

  • certutil: Supports creating PKCS #10 requests.
  • PKCS10Client: Supports creating PKCS #10 requests.
  • CRMFPopClient: Supports creating CRMF requests.

The following sections provide some examples on how to use these utilities with the feature-rich enrollment profile framework.

Note

Although server-side key generation appears to be provided on the browser EE portal, to allow for key generation on the CS server (where keys are then transferred securely back to the client) in order to overcome the inconvenience caused by the removal of keygen support by the latest browsers, this feature is not evaluated in the Common Criteria release.

5.2.1. Creating a CSR using certutil
Copy link

This section describes examples on how to use the certutil utility to create a CSR.

For further details about using certutil, see:

  • The certutil(1) man page
  • The output of the certutil --help command

The following procedure demonstrates how to use the certutil utility to create an Elliptic Curve (EC) key pair and CSR:

  1. Change to the certificate database directory of the user or entity for which the certificate is being requested, for example: 

    $ cd /user_or_entity_database_directory/

  2. Create the binary CSR and store it in the request.csr file: 

    $ certutil -d . -R -k ec -q nistp256 -s "CN=subject_name" -o request-bin.csr

    Enter the required NSS database password when prompted.

    For further details about the parameters, see the certutil(1) man page.

  3. Convert the created binary format CSR to PEM format: 

    $ BtoA request-bin.csr request.csr

  4. Optionally, verify that the CSR file is correct: 

    $ cat request.csr

		MIICbTCCAVUCAQAwKDEQMA4GA1UEChMHRXhhbXBsZTEUMBIGA1UEAxMLZXhhbXBs
		...

    This is a PKCS#10 PEM certificate request.

  5. For the next steps, see Section 5.3.1, “The CMC enrollment process”, but skip the step about creating the certificate request.

The following procedure demonstrates how to create a CSR with user-defined extensions using the certutil utility.

Note that the enrollment requests are constrained by the enrollment profiles defined by the CA. See Example B.3, “Multiple user supplied extensions in CSR”.

  1. Change to the certificate database directory of the user or entity for which the certificate is being requested, for example: 

    $ cd /user_or_entity_database_directory/

  2. Create the CSR with user-defined Key Usage extension as well as user-defined Extended Key Usage extension and store it in the request.csr file: 

    $ certutil -d . -R -k rsa -g 1024 -s "CN=subject_name" --keyUsage keyEncipherment,dataEncipherment,critical --extKeyUsage timeStamp,msTrustListSign,critical -a -o request.csr

    Enter the required NSS database password when prompted.

    For further details about the parameters, see the certutil(1) man page.

  3. Optionally, verify that the CSR file is correct: 

    $ cat request.csr

		Certificate request generated by Netscape certutil
		Phone: (not specified)

		Common Name: user 4-2-1-2
		Email: (not specified)
		Organization: (not specified)
		State: (not specified)
		Country: (not specified)

    This is a PKCS#10 PEM certificate request.

    Note

    Since the above certutil command contained the -a option for a text format CSR, be sure to remove header information before proceeding. If you omit -a, be sure to use the BtoA tool to convert from binary to text format, as seen above in section Section 5.2.1.1, “Using certutil to create a CSR with EC keys”. Since the above certutil command contained -a option for a text format CSR, be sure to remove header information before proceeding. If -a is omitted, be sure to use BtoA to convert from binary to text format, as seen above in section "5.2.1.1. Using certutil to create a CSR with EC keys".

For the next steps, see Section 5.3.1, “The CMC enrollment process”, but skip the step about creating the certificate request.

5.2.2. Creating a CSR using PKCS10Client
Copy link

This section provides examples on how to use the PKCS10Client utility to create a CSR.

For further details about using PKCS10Client, see:

  • The PKCS10Client(1) man page
  • The output of the PKCS10Client --help command

5.2.2.1. Using PKCS10Client to create a CSR
Copy link

The following procedure explains how to use the PKCS10Client utility to create an Elliptic Curve (EC) key pair and CSR:

  1. Change to the certificate database directory of the user or entity for which the certificate is being requested, for example: 

    $ cd /user_or_entity_database_directory/

  2. Create the CSR and store it in the example.csr file: 

    $ PKCS10Client -d . -p NSS_password -a ec -c nistp256 -o example.csr -n "CN=subject_name"

    For further details about the parameters, see the PKCS10Client(1) man page.

  3. Optionally, verify that the CSR is correct: 

    $ cat example.csr

		-----BEGIN CERTIFICATE REQUEST-----
		MIICzzCCAbcCAQAwgYkx
		...
		-----END CERTIFICATE REQUEST-----

For the next steps, see Section 5.3.1, “The CMC enrollment process”.

The following procedure explains how to use the PKCS10Client utility to create an RSA key pair and CSR for SharedSecret-based CMC. Use it only with the CMC Shared Secret authentication method which is, by default, handled by the caFullCMCSharedTokenCert and caECFullCMCSharedTokenCert profiles.

  1. Change to the certificate database directory of the user or entity for which the certificate is being requested, for example: 

    $ cd /user_or_entity_database_directory/

  2. Create the CSR and store it in the example.csr file: 

    $ PKCS10Client -d . -p NSS_password -o example.csr -y true -n "CN=subject_name"

    The keypair private key ID generated in the output is saved to a file with the name format <CSR output file name>.keyId. This ID will be used later on when following the Shared Secret or Decrypted POP CMC enrollment procedure.

    For further details about the parameters, see the PKCS10Client(1) man page.

  3. Optionally, verify that the CSR is correct: 

    $ cat example.csr

		-----BEGIN CERTIFICATE REQUEST-----
		MIICzzCCAbcCAQAwgYkx
		...
		-----END CERTIFICATE REQUEST-----

For the next steps, skip to Section 5.3.2.2.2, “Authenticating for certificate enrollment using a shared secret”.

5.2.3. Creating a CSR using CRMFPopClient
Copy link

Certificate Request Message Format (CRMF) is a CSR format accepted in CMC that allows key archival information to be securely embedded in the request.

This section provides examples on how to use the CRMFPopClient utility to create a CSR.

For further details about using CRMFPopClient, run the CRMFPopClient –help command.

The following procedure explains how to use the CRMFPopClient utility to create an RSA key pair and a CSR with the key archival option:

  1. Change to the certificate database directory of the user or entity for which the certificate is being requested, for example: 

    $ cd /user_or_entity_database_directory/

  2. Retrieve the KRA transport certificate from the CA: 

    $ pki -p 8443 ca-cert-find --name "DRM Transport Certificate"

		---------------
		1 entries found
		---------------
			Serial Number: 0x7
			Subject DN: CN=DRM Transport Certificate,O=EXAMPLE
			Status: VALID
			Type: X.509 version 3
			Key Algorithm: PKCS #1 RSA with 2048-bit key
			Not Valid Before: Thu Oct 22 18:26:11 CEST 2015
			Not Valid After: Wed Oct 11 18:26:11 CEST 2017
			Issued On: Thu Oct 22 18:26:11 CEST 2015
			Issued By: caadmin
		----------------------------
		Number of entries returned 1

  3. Export the KRA transport certificate: 

    $ pki -p 8443 ca-cert-show 0x7 --output kra.transport

  4. Create the CSR and store it in the example.csr file: 

    $ CRMFPopClient -d . -p password -n "cn=subject_name" -q POP_SUCCESS -b kra.transport -w "AES KeyWrap/Wrapped" -v -o example.csr -oaep

Initializing security database: .
archival option enabled
Loading transport certificate
Parsing subject DN
RDN: CN=subject_name
Generating key pair: temporary: false
CryptoUtil: generateRSAKeyPair: calling kg.setKeyPairUsages
Keypair private key id: 27a7e30b48f268ddcc8681633d4014579416d6ca
Using key wrap algorithm: AES KeyWrap/Wrapped
Creating certificate request
CRMFPopClient: use_shared_secret true. Generating SubjectKeyIdentifier extension.
Creating signer
Creating POP
Creating CRMF request
Storing CRMF request into example.csr
Storing CRMF request key id into example.csr.keyId
    Note

    To create an Elliptic Curve (EC) key pair and CSR, pass the -a ec -t false options to the command. For further details about the parameters, see the CRMFPopClient –help cmmand.

  5. Optionally, verify that the CSR is correct: 

    $ cat example.csr

		-----BEGIN CERTIFICATE REQUEST-----
		MIICzzCCAbcCAQAwgYkx
		...
		-----END CERTIFICATE REQUEST-----

For the next steps, see Section 5.3.1, “The CMC enrollment process”.

The following procedure explains how to use the CRMFPopClient utility to create an RSA key pair and CSR for SharedSecret-based CMC. Use it only with the CMC Shared Secret authentication method which is, by default, handled by the caFullCMCSharedTokenCert and caECFullCMCSharedTokenCert profiles.

  1. Change to the certificate database directory of the user or entity for which the certificate is being requested, for example: 

    $ cd /user_or_entity_database_directory/

  2. Retrieve the KRA transport certificate: 

    $ pki -p 8443 ca-cert-find --name "DRM Transport Certificate"

		---------------
		1 entries found
		---------------
			Serial Number: 0x7
			Subject DN: CN=DRM Transport Certificate,O=EXAMPLE
			Status: VALID
			Type: X.509 version 3
			Key Algorithm: PKCS #1 RSA with 2048-bit key
			Not Valid Before: Thu Oct 22 18:26:11 CEST 2015
			Not Valid After: Wed Oct 11 18:26:11 CEST 2017
			Issued On: Thu Oct 22 18:26:11 CEST 2015
			Issued By: caadmin
		----------------------------
		Number of entries returned 1

  3. Export the KRA transport certificate: 

    $ pki -p 8443 ca-cert-export 0xc --output-file kra.transport

  4. Create the CSR and store it in the example.csr file: 

    $ CRMFPopClient -d . -p password -n "cn=subject_name" -q POP_SUCCESS -b kra.transport -w "AES KeyWrap/Wrapped" -y -v -o example.csr -oaep

Initializing security database: .
archival option enabled
Loading transport certificate
Parsing subject DN
RDN: CN=subject_name
Generating key pair: temporary: false
CryptoUtil: generateRSAKeyPair: calling kg.setKeyPairUsages
Keypair private key id: 6e786393637781a4ae281f5304290fcabda5a6b4
Using key wrap algorithm: AES KeyWrap/Wrapped
Creating certificate request
CRMFPopClient: use_shared_secret true. Generating SubjectKeyIdentifier extension.
Creating signer
Creating POP
Creating CRMF request
Storing CRMF request into example.csr
Storing CRMF request key id into example.csr.keyId
    Note

    To create an EC key pair and CSR, pass the -a ec -t false options to the command. For further details about the parameters, see the output of the CRMFPopClient --help command.

    The keypair private key ID generated in the output is saved to a file with the name format <CSR output file name>.keyId. This ID will be used later on when following the Shared Secret or DecryptedPOP CMC enrollment procedure.

  5. Optionally, verify that the CSR is correct: 

    $ cat example.csr
		-----BEGIN CERTIFICATE REQUEST-----
		MIICzzCCAbcCAQAwgYkx
		...
		-----END CERTIFICATE REQUEST-----

For the next steps, skip to Section 5.3.2.2.2, “Authenticating for certificate enrollment using a shared secret”.

This section describes the procedure to enroll a certificate using Certificate Management over CMS (CMC).

For general information about configuration and the workflow of enrolling certificates using CMC, see:

  • 9.6 Configuration for CMC in the Planning, Installation and Deployment Guide (Common Criteria Edition).
  • 2.4.1.1.2.2 Enrolling with CMC in the Planning, Installation and Deployment Guide (Common Criteria Edition).
  • CMCRequest(1) man page
  • CMCResponse(1) man page

CMC enrollment is possible in various ways to meet the requirements for different scenarios. Section 5.3.1, “The CMC enrollment process” supplements 2.4.1.1.2.2 Enrolling with CMC in the Planning, Installation and Deployment Guide (Common Criteria Edition) with more details. Additionally, the Section 5.3.2, “Practical CMC enrollment scenarios” section enables administrators to decide which mechanisms should be used in which scenario.

5.3.1. The CMC enrollment process
Copy link

The most commonly used CMC enrollment process is the agent-approved certificate enrollment:

  1. The user generates a CSR and sends the CSR to a CA agent
  2. Once a CSR is received, the CA agent (configured by "Setting up certificate and role for a pki agent" in the Planning, Installation and Deployment Guide (Common Criteria Edition)) creates a CMC request against the CSR, and sends the request to the CA via HttpClient
  3. Once the certificate is issued successfully, the CA agent then sends the certificate to back to the requesting user
  4. The user then imports the newly issued certificate into their nssdb where the CSR was originally generated

The rest of this section provides a more detailed procedure to issue a certificate using CMC:

The requesting user starts by creating a Certificate Signing Request (CSR) in one of the following formats:

  • PKCS #10 format
  • Certificate Request Message Format (CRMF) format

Next, the requesting user should send the CSR (e.g. /user_or_entity_database_directory/request.csr) to the user who holds the CA agent role.

Approving the CSR as a CA Agent

  1. As the CA agent, switch to the nssdb directory that contains the agent certificate: 

    # cd /home/agent_username/.dogtag/nssdb/

  2. Place the CSR in the directory: 

    # cp request.csr /home/agent_username/.dogtag/nssdb/

  3. After you have placed the CSR in the directory, create a configuration file for a CMC request, such as cmc-request.cfg, with the following content: 

    # NSS database directory where CA agent certificate is stored
dbdir=/home/agent_username/.dogtag/nssdb/

# NSS database password
password=password

# Token name (default is internal)
tokenname=internal

# Nickname for signing certificate
nickname=ca_agent

# Request format: pkcs10 or crmf
format=<type of CSR format>

# Total number of PKCS10/CRMF requests
numRequests=1

# Path to the PKCS10/CRMF request
# The content must be in Base-64 encoded format.
# Multiple files are supported. They must be separated by a space.
input=/home/agent_username/.dogtag/nssdb/request.csr

# Path for the CMC request
output=/home/agent_username/.dogtag/nssdb/cmc-request.bin

    For further details, see the CMCRequest(1) man page.

  4. Create the CMC request: 

    $ CMCRequest cmc-request.cfg

cert/key prefix =
path = /home/agent_username/.dogtag/nssdb
CryptoManger initialized
token internal logged in...
got signerCert: ca_agent
createPKIData: begins
k=0
createPKIData:  format: pkcs10
useSharedSecret is false...
signData: begins:
getPrivateKey: got signing cert
signData:  got signer privKey
createSignedData: begins
getSigningAlgFromPrivate: begins.
getSigningAlgFromPrivate: found signingKeyType=RSA
getSigningAlgFromPrivate: using SignatureAlgorithm: RSASignatureWithSHA256Digest
createSignedData: digest created for pkidata
createSignedData: digest algorithm =RSASignatureWithSHA256Digest
createSignedData: building cert chain
signData: signed request generated.
getCMCBlob: begins
getCMCBlob: generating signed data

The CMC enrollment request in base-64 encoded format:

. . . output omitted . . .


The CMC enrollment request in binary format is stored in /home/agent_username/.dogtag/nssdb/cmc-request.bin

    If the command succeeds, the CMCRequest utility stored the CMC request in the file specified in the output parameter in the request configuration file.

  5. Create a configuration file for HttpClient, such as cmc-submit.cfg, to use in a later step to submit the CMC request to the CA. Add the following content to the created file: 

    # CA server host name
host=server.example.com

# CA server port number
port=8443

# Use secure connection
secure=true

# Use client authentication
clientmode=true

# NSS database directory where the CA agent certificate is stored.
dbdir=/home/agent_username/.dogtag/nssdb/

# NSS database password
password=password

# Token name (default: internal)
tokenname=internal

# Nickname of signing certificate
nickname=ca_agent

# Path for the CMC request
input=/home/agent_username/.dogtag/nssdb/cmc-request.bin

# Path for the CMC response
output=/home/agent_username/.dogtag/nssdb/cmc-response.bin
    Important

    The nickname of the certificate specified in the nickname parameter must match the one previously used for the CMC request.

  6. Depending on what type of certificate you request, add the following parameter to the configuration file created in the previous step: 

    servlet=/ca/ee/ca/profileSubmitCMCFull?profileId=profile_name

    For example, for a CA signing certificate: 

    servlet=/ca/ee/ca/profileSubmitCMCFull?profileId=caCMCcaCert
    Important

    When an agent submits the CMC request in the next step, the profile specified in this parameter must use the CMCAuth authentication plugin. Whereas in user-initiated enrollments, the profile must use the CMCUserSignedAuth plugin. For further details, see the Section 8.3, “CMC authentication plugins”.

  7. Submit the CMC request to the CA: 

    $ HttpClient cmc-submit.cfg

Total number of bytes read = 6271
after SSLSocket created, thread token is NSS FIPS 140-2 User Private Key
client cert is not null
handshake happened
writing to socket

Response Headers begin
HTTP/1.1 200
Content-Type: application/pkcs7-mime
Content-Length: 4227
Date: Fri, 19 Jan 2024 20:57:26 GMT
Connection: close
end

. . . Output omitted . . .

The response in binary format is stored in home/agent_username/.dogtag/nssdb/cmc-response.bin

  8. To convert the CMC response to a PKCS #7 certificate chain, pass the CMC response file to the -i parameter of the CMCResponse utility. For example: 

    $ CMCResponse -i /home/user_name/cmc-response.bin -o /home/user_name/cert_chain.crt
    Important

    Running CMCResponse with the "-v" option returns the PEM of each certificate in the chain as Cert:0, Cert:1 etc. Below all the PEMs, the output also displays each certificate in the chain in pretty print format. Since the certificates are not displayed in a fixed order, in order to determine their position in the chain, you must examine the "Subject:" under each "Certificate". The corresponding PEM is displayed in the same position above.

  9. Once the certificate is issued successfully, the CA agent then sends the certificate back to the requesting user. The user can then import the certificate into their nssdb. For example: 

    # pki -d /user_or_entity_database_directory/ -c <password> client-cert-import "user_name certificate" --cert cert_chain.crt

5.3.2. Practical CMC enrollment scenarios
Copy link

This section describes frequent practical usage scenarios and their workflows to enable CA administrators to decide which CMC method to use in which situation.

For a general process of enrolling a certificate using CMC, see Section 5.3.1, “The CMC enrollment process”.

5.3.2.1. Obtaining system and server certificates
Copy link

If a service, such as LDAP or a web server, requires a TLS server certificate, the administrator of this server creates a CSR based on the documentation of the service and sends it to the CA’s agent for approval. Use the procedure described in Section 5.3.1, “The CMC enrollment process” for this process. Additionally, consider the following requirements:

Enrollment Profiles
The agent must either use one of the existing CMC profiles listed in Section 8.3, “CMC authentication plugins”, or, alternatively, create a custom profile that uses the CMCAuth authentication mechanism.
CMC Signing Certificate

For system certificates, the CA agent must generate and sign the CMC request. For this, set the nickname parameter in the CMCRequest configuration file to the nickname of the CA agent.

Note

The CA agent must have access to its own private key.

HttpClient nickname parameter
Use the same certificate for signing in the CMCRequest utility’s configuration file as for TLS mutual authentication in the configuration file for HttpClient.
HttpClient servlet parameter

The servlet in the configuration file passed to the HttpClient utility refers to the CMC servlet and the enrollment profile which handles the request.

Depending on what type of certificate you request, add one of the following entries to the configuration file created in the previous step:

  • For a CA signing certificate: 

    servlet=/ca/ee/ca/profileSubmitCMCFull?profileId=caCMCcaCert

  • For a KRA transport certificate: 

    servlet=/ca/ee/ca/profileSubmitCMCFull?profileId=caCMCkraTransportCert

  • For an OCSP signing certificate: 

    servlet=/ca/ee/ca/profileSubmitCMCFull?profileId=caCMCocspCert

  • For an audit signing certificate: 

    servlet=/ca/ee/ca/profileSubmitCMCFull?profileId=caCMCauditSigningCert

  • For a subsystem certificate:

    • For RSA certificates: 

      servlet=/ca/ee/ca/profileSubmitCMCFull?profileId=caCMCsubsystemCert

    • For ECC certificates: 

      servlet=/ca/ee/ca/profileSubmitCMCFull?profileId=caCMCECCsubsystemCert

  • For a TLS server certificate:

    • For RSA certificates: 

      servlet=/ca/ee/ca/profileSubmitCMCFull?profileId=caCMCserverCert

    • For ECC certificates: 

      servlet=/ca/ee/ca/profileSubmitCMCFull?profileId=caCMCECCserverCert

  • For an admin certificate: 

    servlet=/ca/ee/ca/profileSubmitCMCFull?profileId=caFullCMCUserCert

Further details:

  • When an agent pre-signs a CSR, the Proof of Identification is considered established because the agent examines the CSR for identification. No additional CMC-specific identification proof is required.
  • PKCS #10 files already provide Proof of Possession information and no additional Proof of Possession (POP) is required.
  • In agent pre-approved requests, the PopLinkWitnessV2 feature must be disabled because the identification is checked by the agent.

There are two ways to approve a user’s first signing certificate:

The process for signing a CMC request with an agent certificate is the same as for obtaining system and server certificates, which can be found in Section 5.3.1, “The CMC enrollment process”.

The CMC SharedToken method is designed to allow non-agent users to securely enroll for their own user certificates without the involvement of a CA agent. When a user wants to obtain the first signing certificate and the agent cannot approve the request as described in Section 5.3.2.2.1, “Signing a CMC Request with an agent certificate”, you can use a Shared Token. With this token, the user can obtain the first signing certificate. This certificate can then be used to sign other certificates of the user.

In this scenario, use the Shared Secret mechanism to obtain the first signing certificate of the user. Use the following information together with Section 5.3.1, “The CMC enrollment process”:

  1. Create a Shared Token either as the user or CA administrator. For details, see Section 8.4.1, “Creating a Shared Secret token”.

    Note that: If the user created the token, the user must send the token to the CA administrator. If the CA administrator created the token, the administrator must share the password used to generate the token with the user. Use a secure way to transmit the password.

  2. As the CA administrator, add the Shared Token to the user entry in LDAP. For details, see 9.6.3 Adding a CMC Shared Secret to a user entry for certificate enrollment and the Enabling the CMC Shared Secret Feature in the Planning, Installation and Deployment Guide (Common Criteria Edition).

  3. Use the following parameters in the configuration file passed to the CMCRequest utility:

    • identification.enable
    • identification
    • witness.sharedSecret
    • identityProofV2.enable
    • identityProofV2.hashAlg
    • identityProofV2.macAlg
    • request.useSharedSecret
    • request.privKeyId

  4. If required by the CA, additionally use the following parameters in the configuration file passed to the CMCRequest utility:

    • popLinkWitnessV2.enable
    • popLinkWitnessV2.keyGenAlg

    • popLinkWitnessV2.macAlg

      Note

      For more information on whether popLinkWitness is required by the CA, see the value for the configuration parameter in 9.6.2 "Enabling the PopLinkWitnessV2 feature" in the Planning, Installation and Deployment Guide (Common Criteria Edition).

  5. See the below example of how the parameters are used in a CMC enrollment configuration file. For example, create the shrTok_example_request.cfg in the requesting user’s nssdb: 

    ### numRequests: Total number of PKCS10 requests or CRMF requests.
numRequests=1

### input: full path for the PKCS10 request or CRMF request,
### The content must be in Base-64 encoded format.
### Multiple files are supported. They must be separated by a space.
input=/home/user_name/.dogtag/nssdb/request.csr

### output: full path for the CMC request in binary format
output=/home/user_name/.dogtag/nssdb/cmc-request.bin

### tokenname: name of the token where agent signing cert can be found (default is internal)
tokenname=internal
request.useSharedSecret=true

### nickname: nickname for the agent certificate which will be used to sign the CMC full request. This is not needed for shared secret enrollments.
#nickname=

### dbdir: directory for cert8.db, key3.db and secmod.db
dbdir=/home/user_name/.dogtag/nssdb/

### password: password for cert8.db which stores the agent certificate
password=password

### format: request format, pkcs10 if request is created using PKCS10Client, or crmf if request created using CRMFPopClient
format=<pkcs10 or crmf>

### identityProofV2.enable: if true, then the request will contain this control. Otherwise, false.
### Note that if both identityProof and identityProofV2 are enabled,
### identityProofV2 takes precedence; Only one of them can be active at a time
### Supported hashAlg are:
### SHA-256, SHA-384, and SHA-512
### Supported macAlg are:
### SHA-256-HMAC, SHA-384-HMAC, and SHA-512-HMAC
identityProofV2.enable=true
identityProofV2.hashAlg=SHA-512
identityProofV2.macAlg=SHA-256-HMAC

### identityProofV2.sharedSecret: Shared Secret
### The shared secret passphrase assigned when creating shared token with CMCSharedToken command
witness.sharedSecret=<shared secret>

popLinkWitnessV2.enable=true
popLinkWitnessV2.keyGenAlg=SHA-256
popLinkWitnessV2.macAlg=SHA-256-HMAC

request.privKeyId=<output from PKCS10Client | CRMFPopClient xxx.priv>

### identification works with identityProofV2
identification.enable=true
identification=<The UID of the requesting user in LDAP>
    Note

    You can find a more complete example of CMC enrollment with a shared secret in the "Test the CMC Shared Token" in the Planning, Installation and Deployment Guide (Common Criteria Edition).

This section describes the workflow for obtaining an encryption-only certificate which is signed with an existing user signing certificate:

Note

If a user owns multiple certificates for different usages, where one is signing, the user must obtain the signing certificate first. Once the user owns a signing certificate, it can be used for Proof Of Origin without requiring to set up and rely on the CMC Shared Secret mechanism.

For details about obtaining a user’s first signing certificate, see Section 5.3.2.2, “Obtaining the first signing certificate for a user”.

As a user:

  1. Use the cryptographic token stored in a Network Security Services (NSS) database or on a smart card that contains the user’s signing certificate and keys.

  2. Generate the CSR in PKCS #10 or the CRMF format.

    Note

    Use the CRMF format, if key archival is required.

  3. Generate the CMC request.

    Since this is an encryption-only certificate, the private key is not able to sign. Therefore, Proof Of Possession (POP) is not included. For this reason, the enrollment requires two steps: If the initial request is successful, results in a CMC status with the EncryptedPOP control. The user then uses the response and generates a CMC request that contains the DecryptedPOP control and submits it in the second step.

    • For the first step, in addition to the default parameters, the user must set the following parameters in the configuration file passed to the CMCRequest utility:

      • identification.enable
      • witness.sharedSecret
      • identityProofV2.enable
      • identityProofV2.hashAlg
      • identityProofV2.macAlg
      • popLinkWitnessV2.enable if required by the CA
      • popLinkWitnessV2.keyGenAlg if required by the CA
      • popLinkWitnessV2.macAlg if required by the CA

      • request.privKeyId

        For details, see the CMCRequest(1) man page.

        The response contains:

      • A CMC encrypted POP control
      • The CMCStatusInfoV2 control with the POP required error
      • The request ID

    • For the second step, in addition to the default parameters, the user must set the following parameters in the configuration file passed to the CMCRequest utility:

      • decryptedPop.enable
      • encryptedPopResponseFile
      • decryptedPopRequestFile
      • request.privKeyId
      • oaep=true

    For details, see the CMCRequest(1) man page.

To perform an enrollment with key archival, generate a CMC request that contains the user’s encrypted private key in the CRMF request. The following procedure assumes that the user already owns a signing certificate. The nickname of this signing certificate is set in the configuration files in the procedure.

Note

The following procedure describes the two-trip issuance used with encryption-only keys, which cannot be used for signing. If you use a key which can sign certificates, pass the -q POP_SUCCESS option instead of -q POP_NONE to the CRMFPopClient utility for a single-trip issuance.

The procedure for obtaining an encryption-only certificate requires generating a CRMF request using CRMPopClient with the POP_NONE option only. For instructions about using CRMFPopClient with POP_SUCCESS, see Section 5.2.3.1, “Using CRMFPopClient to create a CSR with key archival” and Section 5.2.3.2, “Using CRMFPopClient to create a CSR for SharedSecret-based CMC”.

Generating a CSR

  1. Change to the certificate database directory of the user or entity for which the certificate is being requested, for example: 

    $ cd /home/user_name/.dogtag/nssdb/

  2. Search for the KRA transport certificate. For example: 

    $ pki -p 8443 ca-cert-find --name "DRM Transport Certificate"

  3. Use the serial number of the KRA transport certificate, which you retrieved in the previous step, to store the certificate in a file. For example, to store the certificate with the 12345 serial number in the kra.transport file: 

    $ pki -p 8443 ca-cert-export 12345 --output kra.transport

  4. Use the CRMFPopClient utility to create a CRMF request with POP_NONE, where the RSA private key is wrapped by the KRA transport certificate. For example, to generate and store the request in the /home/user_name/.dogtag/nssdb/crmf.req file: 

    $ CRMFPopClient -d . -p token_password -n "cn=subject_name" -q POP_NONE -b kra.transport -w "AES KeyWrap/Wrapped" -v -o crmf.req -oaep

Initializing security database: .
archival option enabled
Loading transport certificate
Parsing subject DN
RDN: CN=subject_name
Generating key pair: temporary: false
CryptoUtil: generateRSAKeyPair: calling kg.setKeyPairUsages
Keypair private key id: 2500b867acad0064bdba3fde9762a3ff1487fcfa
Using key wrap algorithm: AES KeyWrap/Wrapped
Creating certificate request
Creating CRMF request
Storing CRMF request into crmf.req
Storing CRMF request key id into crmf.req.keyId

CMCRequest first trip (EncryptedPop)

  1. Create a configuration file for the CMCRequest utility, such as cmc-crmf-request.cfg with the following content: 

    #numRequests: Total number of PKCS10 requests or CRMF requests.
numRequests=1

#input: full path for the PKCS10 request or CRMF request,
#the content must be in Base-64 encoded format
input=/home/user_name/.dogtag/nssdb/crmf.req

#output: full path for the CMC request in binary format
output=/home/user_name/.dogtag/nssdb/cmc-round_1.req

#tokenname: name of token where agent signing cert can be found
#(default is internal)
tokenname=internal

#nickname: nickname for user certificate which will be used
#to sign the CMC full request.
nickname=signing_certificate

#dbdir: directory for cert9.db, key4.db and pkcs11.txt
dbdir=/home/user_name/.dogtag/nssdb/

#password: password for cert9.db which stores the agent certificate
password=password

#format: request format, either pkcs10 or crmf
format=crmf

decryptedPop.enable=false
request.selfSign=false

  2. Create the CMC request: 

    $ CMCRequest cmc-crmf-request.cfg

cert/key prefix =
path = /home/user_name/certs_db
CryptoManger initialized
token internal logged in...
got signerCert: signing_certificate
createPKIData: begins
k=0
createPKIData:  format: crmf
useSharedSecret is false...
signData: begins:
getPrivateKey: got signing cert
signData:  got signer privKey
createSignedData: begins
getSigningAlgFromPrivate: begins.
getSigningAlgFromPrivate: found signingKeyType=EC
getSigningAlgFromPrivate: using SignatureAlgorithm: ECSignatureWithSHA256Digest
createSignedData: digest created for pkidata
createSignedData: digest algorithm =ECSignatureWithSHA256Digest
createSignedData: building cert chain
signData: signed request generated.
getCMCBlob: begins
getCMCBlob: generating signed data

The CMC enrollment request in base-64 encoded format:

. . . output omitted . . .


The CMC enrollment request in binary format is stored in /home/user_name/.dogtag/nssdb/cmc-round_1.req

    If the command succeeds, the CMCRequest utility stored the CMC request in the file specified in the output parameter in the request configuration file.

  3. Create a configuration file for HttpClient, such as cmc-submit.cfg, to use in a later step to submit the CMC request to the CA. Add the following content to the created file: 

    #host: host name for the http server
host=server.example.com

#port: CA port number
port=8443

#secure: true for secure connection, false for nonsecure connection
secure=true

#input: full path for the enrollment request, the content must be in
#binary format
input=/home/user_name/.dogtag/nssdb/cmc-round_1.req

#output: full path for the response in binary format
output=/home/user_name/.dogtag/nssdb/cmc-response_round_1.bin

#tokenname: name of token where TLS mutual authentication cert can be found
#(default is internal)
#This parameter will be ignored if secure=false
tokenname=internal

#dbdir: directory for cert9.db, key4.db and pkcs11.txt
#This parameter will be ignored if secure=false
dbdir=/home/user_name/.dogtag/nssdb/

#clientmode: true for client authentication, false for no client authentication
#This parameter will be ignored if secure=false
clientmode=true

#password: password for cert9.db
#This parameter will be ignored if secure=false and clientauth=false
password=password

#nickname: nickname for client certificate
#This parameter will be ignored if clientmode=false
nickname=signing_certificate

#servlet: servlet name
servlet=/ca/ee/ca/profileSubmitUserSignedCMCFull?profileId=caFullCMCUserSignedCert

  4. Submit the CMC request to the CA: 

    $ HttpClient cmc-submit.cfg

Total number of bytes read = 5578
after SSLSocket created, thread token is NSS FIPS 140-2 User Private Key
client cert is not null
handshake happened
writing to socket

Response Headers begin
HTTP/1.1 200
Content-Type: application/pkcs7-mime
Content-Length: 3317
Date: Thu, 25 Jan 2024 21:58:32 GMT
Connection: close
End

Total number of bytes read = 3317

. . . output omitted . . .

The response in binary format is stored in /home/user_name/.dogtag/nssdb/cmc-response_round_1.bin

    If the command succeeds, the HTTPClient utility stored the CMC response in the file specified in the output parameter in the configuration file.

  5. Verify the response by passing the response file to the CMCResponse utility. For example: 

    $ CMCResponse -d /home/user_name/.dogtag/nssdb/ -i /home/user_name/.dogtag/nssdb/cmc-response_round_1.bin

    If the first trip was successful, CMCResponse displays an output similar to the following: 

    Certificates:
    Certificate:
        Data:
            Version:  v3
            Serial Number: 0x425C240
            Signature Algorithm: SHA256withRSA - 1.2.840.113549.1.1.11
            Issuer: CN=CA Signing Certificate,OU=rhcs10-RSA-RootCA,O=Example-rhcs10-RSA-RootCA
            Validity:
                Not Before: Thursday, September 28, 2023 4:06:41 PM EDT America/New_York
                Not  After: Monday, September 28, 2043 4:06:41 PM EDT America/New_York
            Subject: CN=CA Signing Certificate,OU=rhcs10-RSA-RootCA,O=Example-rhcs10-RSA-RootCA
...
Number of controls is 3
Control #0: CMC encrypted POP
	 OID: {1 3 6 1 5 5 7 7 9}
		 encryptedPOP decoded
Control #1: CMCStatusInfoV2
	 OID: {1 3 6 1 5 5 7 7 25}
	 BodyList: 1
	 OtherInfo type: FAIL
		 failInfo=POP required
Control #2: CMC ResponseInfo
	 requestID: 15
CMC Full Response.
ERROR: CMC status for [1]: pop required

CMCRequest second trip (DecryptedPop)

  1. For the second trip, create a configuration file for DecryptedPOP, such as /home/user_name/.dogtag/nssdb/cmc_DecryptedPOP.cfg, which you use in a later step. 

    #numRequests: Total number of PKCS10 requests or CRMF requests.
numRequests=1

#input: full path for the PKCS10 request or CRMF request,
#the content must be in Base-64 encoded format
#this field is actually unused in the 2nd trip
input=/home/user_name/.dogtag/nssdb/crmf.req

#output: full path for the CMC request in binary format
#this field is actually unused in 2nd trip
output=/home/user_name/.dogtag/nssdb/cmc2.req

#tokenname: name of token where agent signing cert can be found
#(default is internal)
tokenname=internal

#nickname: nickname for agent certificate which will be used
#to sign the CMC full request.
nickname=signing_certificate

#dbdir: directory for cert9.db, key4.db and pkcs11.txt
dbdir=/home/user_name/.dogtag/nssdb/

#password: password for cert9.db which stores the agent
#certificate
password=password

#format: request format, either pkcs10 or crmf
format=crmf

decryptedPop.enable=true
request.selfSign=false
oaep=true
encryptedPopResponseFile=/home/user_name/.dogtag/nssdb/cmc-response_round_1.bin

request.privKeyId=-25aa0a8aad395ebac7e6a19c364f0dcb5350cfef
decryptedPopRequestFile=/home/user_name/.dogtag/nssdb/cmc.DecryptedPOP.req
    Note

    For the request.privKeyId= parameter value, enter the private key ID that was saved into the keyId file after running CRMFPopClient, e.g. crmf.req.keyId.

  2. Create the DecryptPOP CMC request: 

    $ CMCRequest /home/user_name/cmc.DecryptedPOP.cfg

cert/key prefix =
path = /home/user_name/.dogtag/nssdb
CryptoManger initialized
token internal logged in...
got signerCert: signing_certificate
got request privKeyId: -5db9e71d7f6fbf8cca8dba3f933aa1beea69fb5f
got private key
processEncryptedPopResponse:  begins.
processEncryptedPopResponse:  previous response read.
processEncryptedPopResponse: Number of controls is 3
processEncryptedPopResponse: Control #0: CMC encrypted POP
processEncryptedPopResponse:    OID: {1 3 6 1 5 5 7 7 9}
processEncryptedPopResponse:      encryptedPOP decoded successfully
processEncryptedPopResponse: Control #1: CMCStatusInfoV2
processEncryptedPopResponse:    OID: {1 3 6 1 5 5 7 7 25}
processEncryptedPopResponse:    BodyList: 1
processEncryptedPopResponse:    OtherInfo type: FAIL
processEncryptedPopResponse:      failInfo=POP required
processEncryptedPopResponse:    what we expected, as decryptedPOP.enable is true;
processEncryptedPopResponse: Control #2: CMC ResponseInfo
processEncryptedPopResponse:    requestID: 256
processEncryptedPopResponse: ends
constructDecryptedPopRequest: begins
constructDecryptedPopRequest:  previous response parsed.
constructDecryptedPopRequest: symKey unwrapped.
constructDecryptedPopRequest: challenge decrypted.
constructDecryptedPopRequest: Yay! witness verified
constructDecryptedPopRequest: calculating POP Proof Value
constructDecryptedPopRequest: popProofValue length = 32
constructDecryptedPopRequest: constructing DecryptedPOP...
constructDecryptedPopRequest: DecryptedPOP constructed successfully
constructDecryptedPopRequest: adding decryptedPop control
constructDecryptedPopRequest: decryptedPop control added
constructDecryptedPopRequest: regInfo control added
constructDecryptedPopRequest:  completes.
useSharedSecret is false...
signData: begins:
getPrivateKey: got signing cert
signData:  got signer privKey
createSignedData: begins
getSigningAlgFromPrivate: begins.
getSigningAlgFromPrivate: found signingKeyType=EC
getSigningAlgFromPrivate: using SignatureAlgorithm: ECSignatureWithSHA256Digest
createSignedData: digest created for pkidata
createSignedData: digest algorithm =ECSignatureWithSHA256Digest
createSignedData: building cert chain
signData: signed request generated.
getCMCBlob: begins
getCMCBlob: generating signed data

The CMC enrollment request in base-64 encoded format:

. . . output omitted . .


The CMC enrollment request in binary format is stored in /home/user_name/.dogtag/nssdb/cmc.DecryptedPOP.req

    If the command succeeds, the CMCRequest utility stored the CMC request in the file specified in the decryptedPopRequestFile parameter in the request configuration file.

  3. Create a configuration file for HttpClient, such as decrypted_POP_cmc-submit.cfg, to use in a later step to submit the DecryptedPOP CMC request to the CA. Add the following content to the created file: 

    #host: host name for the http server
host=server.example.com

#port: CA port number
port=8443

#secure: true for secure connection, false for nonsecure connection
secure=true

#input: full path for the enrollment request, the content must be in binary format
input=/home/user_name/.dogtag/nssdb/cmc.DecryptedPOP.req

#output: full path for the response in binary format
output=/home/user_name/.dogtag/nssdb/cmc-response_round_2.bin

#tokenname: name of token where TLS mutual authentication cert can be found (default is internal)
#This parameter will be ignored if secure=false
tokenname=internal

#dbdir: directory for cert9.db, key4.db and pkcs11.txt
#This parameter will be ignored if secure=false
dbdir=/home/user_name/.dogtag/nssdb/

#clientmode: true for client authentication, false for no client authentication
#This parameter will be ignored if secure=false
clientmode=true

#password: password for cert9.db
#This parameter will be ignored if secure=false and clientauth=false
password=password

#nickname: nickname for client certificate
#This parameter will be ignored if clientmode=false
nickname=signing_certificate

#servlet: servlet name
servlet=/ca/ee/ca/profileSubmitCMCFull?profileId=caFullCMCUserSignedCert

  4. Submit the DecryptedPOP CMC request to the CA: 

    $ HttpClient decrypted_POP_cmc-submit.cfg

Total number of bytes read = 5676
after SSLSocket created, thread token is NSS FIPS 140-2 User Private Key
client cert is not null
handshake happened
writing to socket

Response Headers begin
HTTP/1.1 200
Content-Type: application/pkcs7-mime
Content-Length: 4210
Date: Fri, 26 Jan 2024 00:41:57 GMT
Connection: close
end

Total number of bytes read = 4210

. . . output omitted . . .


The response in binary format is stored in /home/user_name/.dogtag/nssdb/cmc-response_round_2.bin

    If the command succeeds, the HTTPClient utility stored the CMC response in the file specified in the output parameter in the configuration file.

  5. To convert the CMC response to a PKCS #7 certificate chain, pass the CMC response file to the -i parameter of the CMCResponse utility. For example: 

    $ CMCResponse -i cmc-response_round_2.bin -o encryption_only_certs.p7

    Alternatively, to display the individual certificates in PEM format, pass the -v to the utility.

    If the second trip was successful, CMCResponse displays output similar to the following: 

    Certificates:
    Certificate:
        Data:
            Version:  v3
            Serial Number: 0x35EEA2A
            Signature Algorithm: SHA256withRSA - 1.2.840.113549.1.1.11
            Issuer: CN=CA Signing Certificate,OU=rhcs10-RSA-SubCA,O=Example-rhcs10-RSA-RootCA
            Validity:
                Not Before: Thursday, January 25, 2024 5:09:51 PM EST America/New_York
                Not  After: Tuesday, July 23, 2024 5:09:51 PM EDT America/New_York
            Subject: CN=user_name,UID=example,OU=keyArchivalExample

. . .

Number of controls is 1
Control #0: CMCStatusInfoV2
   OID: {1 3 6 1 5 5 7 7 25}
   BodyList: 1
   Status: SUCCESS
CMC Full Response.

PKCS#7 now stored in file: encryption_only_certs.p7

  6. Once the certificate is issued successfully, the user can then import the certificate into their own /home/user_name/.dogtag/nssdb/ database. For example: 

    # pki -d /home/user_name/.dogtag/nssdb/ -c <password> client-cert-import "user_name certificate" --cert encryption_only_certs.p7

5.4. Renewing certificates
Copy link

This section explains how to use the different types of certificate renewal described in Section 3.4.1, “The renewal process”. You can use the methods described in this section to renew a certificate both with and without agent approval. To renew a certificate as a user without agent approval, use profiles that require the CMCUserSignedAuth authentication plugin, and to renew with agent approval, use profiles that require the CMCAuth authentication plugin. For further details about these plugins and in which profiles they are enabled by default, see Section 8.3, “CMC authentication plugins”.

Renewal Using the Same Key

Section 5.3.1, “The CMC enrollment process” describes how to request and issue a certificate using CMC. When a user submits the same CMC request created during this process again with the same enrollment profile, Certificate System renews the certificate with the same key.

Note

For renewing a certificate as the user using the same key, the enrollment profile must contain the uniqueKeyConstraint entry with the params.allowSameKeyRenewal parameter set to True as described in Section 3.4.1, “The renewal process”.

Renewal Using a New Key

To renew a certificate using a new key, follow the procedure described in Section 5.3.1, “The CMC enrollment process”. The process for renewal is the same as for a new enrollment. When you sign the request with the same signing certificate, the newly issued certificate contains the same subjectDN attribute as the signing certificate.

5.5. Linking between an issued certificate and CSR
Copy link

This section details how a CA agent can trace an issued certificate to the original submitted CSR, and from a CSR to an issued certificate.

Tracing from CSR to issued certificate

  • If a certificate request has been approved successfully, a CA agent can do the following to search for the request and see the CSR matching the certificate:

    1. Access https://host_name:port/ca/agent/ca.
    2. Click Search for Requests.
    3. Select and fill in Request ID Range (for example 12 for Lowest Request ID and 12 for Highest Request ID).
    4. Select Request Type and choose enrollment type.
    5. Select Request Status and choose completed status
    6. Make sure everything else is unselected.
    7. Click Submit.
    8. Click on the request number. You see the certificate in clear text at this point.

    9. To display the CSR and certificate linking, right-click and select This Frame and View Frame Source.

      1. Search for inputList.inputName="Certificate Request";. The request is the inputList.inputVal below that.
      2. Search for outputList.outputSyntax="pretty_print";. The certificate is the outputList.outputVal below that.

Tracing from issued certificate to CSR:

  1. Access https://host_name:port/ca/agent/ca.
  2. Click Find.
  3. Click Details.
  4. You see the certificate in clear text, along with a Request ID link. Click on the link to open the Request page.

  5. To display the certificate and CSR linking:

    1. Search for inputList.inputName="Certificate Request";. The request is the inputList.inputVal below that.
    2. Search for outputList.outputSyntax="pretty_print";. The certificate is the outputList.outputVal below that.
Note

You can also use the CLI to find the certificate request for a certificate in the CA database, for example: 

$ pki-server ca-cert-request-find --cert-file <cert file>

Where the certificate file has the following requirements:

  • The certificate must be base-64 encoded.
  • Each line must be at most 64 bytes long and terminated with CRLF.
  • There is no BEGIN/END CERTIFICATE header/footer.
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2026 Red HatBack to top