Red Hat Summit Red Hat SummitSupportoConsoleSviluppatoriInizia una provaContatti

Questo contenuto non è disponibile nella lingua selezionata.

5.3. Requesting and Receiving Certificates Using CMC

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:
  • The Configuration for CMC section in the Red Hat Certificate System Planning, Installation, and Deployment Guide (Common Criteria Edition).
  • The Enrolling with CMC section in the Red Hat Certificate System 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 the Enrolling with CMC section in the Red Hat Certificate System 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
Copia collegamento

Use the following general procedure to request and issue a certificate using CMC:
  1. Create a Certificate Signing Request (CSR) in one of the following formats:
    • PKCS #10 format
    • Certificate Request Message Format (CRMF) format:
    For details about creating CSRs in these formats, see Section 5.2, “Creating Certificate Signing Requests”.
  2. Import the admin certificate into the client NSS database. For example:
    • Execute the command below to extract the admin client certificate from the .p12 file: 
      $ openssl pkcs12 -in /root/.dogtag/instance/ca_admin_cert.p12 -clcerts -nodes -nokeys -out /root/.dogtag/instance/ca_admin_cert.crt
      Copy to Clipboard Toggle word wrap
    • Validate and import the admin client certificate according to guidance in ⁠Chapter 11, Managing Certificate/Key Crypto Token: 
      $ PKICertImport -d . -n "CA Admin - Client Certificate" -t ",," -a -i /root/.dogtag/instance/ca_admin_cert.crt -u C
      Copy to Clipboard Toggle word wrap

      Important

      Make sure all intermediate certificates and the root CA certificate have been imported before importing the CA Admin client certificate.
    • Import the private keys associated with the certificates. 
      $ pki -c password pkcs12-import --pkcs12-file /root/.dogtag/instance/ca_admin_cert.p12 --pkcs12-password-file /root/.dogtag/instance/ca/pkcs12_password.conf
      Copy to Clipboard Toggle word wrap
  3. Create a configuration file for a CMC request, such as /home/user_name/cmc-request.cfg, with the following content: 
    # NSS database directory where CA agent certificate is stored
dbdir=/home/user_name/.dogtag/nssdb/

# NSS database password
password=password

# Token name (default is internal)
tokenname=internal

# Nickname for signing certificate
nickname=subsystem_admin

# Request format: pkcs10 or crmf
format=pkcs10

# 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 space.
input=/home/user_name/file.csr

# Path for the CMC request
output=/home/user_name/cmc-request.bin
    Copy to Clipboard Toggle word wrap
    For further details, see the CMCRequest(1) man page.
  4. Create the CMC request: 
    $ CMCRequest /home/user_name/cmc-request.cfg
    Copy to Clipboard Toggle word wrap
    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 /home/user_name/cmc-submit.cfg, which you use in a later step to submit the CMC request to the CA. Add the following content to the created file: 
    # PKI server host name
host=server.example.com

# PKI 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/user_name/.dogtag/nssdb/

# NSS database password
password=password

# Token name (default: internal)
tokenname=internal

# Nickname of signing certificate
nickname=subsystem_admin

# Path for the CMC request
input=/home/user_name/cmc-request.bin

# Path for the CMC response
output=/home/user_name/cmc-response.bin
    Copy to Clipboard Toggle word wrap

    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
    Copy to Clipboard Toggle word wrap
    For example, for a CA signing certificate: 
    servlet=/ca/ee/ca/profileSubmitCMCFull?profileId=caCMCcaCert
    Copy to Clipboard Toggle word wrap

    Important

    When an agent submits the CMC request in the next step, the profile specified in this parameter must use the CMCAuth authentication plug-in. Whereas in user-initiated enrollments, the profile must use the CMCUserSignedAuth plug-in. For further details, see Section 8.1.2, “CMC Authentication Plug-ins”.
  7. Submit the CMC request to the CA: 
    $ HttpClient /home/user_name/cmc-submit.cfg
    Copy to Clipboard Toggle word wrap
  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
    Copy to Clipboard Toggle word wrap

5.3.2. Practical CMC Enrollment Scenarios
Copia collegamento

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
Copia collegamento

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.1.2, “CMC Authentication Plug-ins” 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 TLS Client Nickname
Use the same certificate for signing in the CMCRequest utility's configuration file as for TLS client 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
    Copy to Clipboard Toggle word wrap
  • For a KRA transport certificate: 
    servlet=/ca/ee/ca/profileSubmitCMCFull?profileId=caCMCkraTransportCert
    Copy to Clipboard Toggle word wrap
  • For a OCSP signing certificate: 
    servlet=/ca/ee/ca/profileSubmitCMCFull?profileId=caCMCocspCert
    Copy to Clipboard Toggle word wrap
  • For a audit signing certificate: 
    servlet=/ca/ee/ca/profileSubmitCMCFull?profileId=caCMCauditSigningCert
    Copy to Clipboard Toggle word wrap
  • For a subsystem certificate:
    • For RSA certificates: 
      servlet=/ca/ee/ca/profileSubmitCMCFull?profileId=caCMCsubsystemCert
      Copy to Clipboard Toggle word wrap
    • For ECC certificates: 
      servlet=/ca/ee/ca/profileSubmitCMCFull?profileId=caCMCECCsubsystemCert
      Copy to Clipboard Toggle word wrap
  • For a TLS server certificate:
    • For RSA certificates: 
      servlet=/ca/ee/ca/profileSubmitCMCFull?profileId=caCMCserverCert
      Copy to Clipboard Toggle word wrap
    • For ECC certificates: 
      servlet=/ca/ee/ca/profileSubmitCMCFull?profileId=caCMCECCserverCert
      Copy to Clipboard Toggle word wrap
  • For an admin certificate: 
    servlet=/ca/ee/ca/profileSubmitCMCFull?profileId=caFullCMCUserCert
    Copy to Clipboard Toggle word wrap
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 PopLinkWittnessV2 feature must be disabled because the identification is checked by the agent.

5.3.2.2. Obtaining the First Signing Certificate for a User
Copia collegamento

There are two ways to approve a user's first signing certificate:
5.3.2.2.1. Signing a CMC Request with an Agent Certificate
Copia collegamento
The process for signing a CMC request with an agent certificate is the same as for system and server certificates described in Section 5.3.2.1, “Obtaining System and Server Certificates”. The only difference is that the user creates the CSR and sends it to a CA agent for approval.
5.3.2.2.2. Authenticating for Certificate Enrollment Using a Shared Secret
Copia collegamento
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.1.3.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 Section 8.1.3.2.1, “Adding a CMC Shared Secret to a User Entry for Certificate Enrollment” and the Enabling the CMC Shared Secret Feature section in the Red Hat Certificate System Planning, Installation, and Deployment Guide (Common Criteria Edition).
  3. Use the following parameters in the configuration file passed to the CMCRequest utility:
    • identification.enable
    • 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

5.3.2.3. Obtaining an Encryption-only Certificate for a User
Copia collegamento

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.
    1. 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
    2. 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
      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.
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”.
  1. Search for the KRA transport certificate. For example: 
    $ pki cert-find --name KRA_transport_certificate_subject_CN
    Copy to Clipboard Toggle word wrap
  2. 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 /home/user_name/kra.cert file: 
    $ pki cert-show 12345 --output /home/user_name/kra.cert
    Copy to Clipboard Toggle word wrap
  3. Use the CRMFPopClient utility to:
    • Create a CSR with key archival:
      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/
        Copy to Clipboard Toggle word wrap
      2. Use the CRMFPopClient utility to create a CRMF request, where the RSA private key is wrapped by the KRA transport certificate. For example, to store the request in the /home/user_name/crmf.req file: 
        $ CRMFPopClient -d . -p token_password -n subject_DN -q POP_NONE \
     -b /home/user_name/kra.cert -w "AES/CBC/PKCS5Padding" \
     -v -o /home/user_name/crmf.req
        Copy to Clipboard Toggle word wrap
        Note the ID of the private key displayed by the command. The ID is required in a later step as value in the request.privKeyId parameter in the configuration file for the second trip.
  4. Create a configuration file for the CRMRequest utility, such as /home/user_name/cmc.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/crmf.req

#output: full path for the CMC request in binary format
output=/home/user_name/cmc.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 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, either pkcs10 or crmf
format=crmf
    Copy to Clipboard Toggle word wrap
  5. Create the CMC request: 
    $ CMCRequest /home/user_name/cmc.cfg
    Copy to Clipboard Toggle word wrap
    If the command succeeds, the CMCRequest utility stored the CMC request in the file specified in the output parameter in the request configuration file.
  6. Create a configuration file for HttpClient, such as /home/user_name/cmc-submit.cfg, which you 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: 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/cmc.req

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

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

#dbdir: directory for cert8.db, key3.db and secmod.db
#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 cert8.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
    Copy to Clipboard Toggle word wrap
  7. Submit the CMC request to the CA: 
    $ HttpClient /home/user_name/cmc-submit.cfg
    Copy to Clipboard Toggle word wrap
    If the command succeeds, the HTTPClient utility stored the CMC response in the file specified in the output parameter in the configuration file.
  8. 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/cmc-response_round_1.bin
    Copy to Clipboard Toggle word wrap
    If the first trip was successful, CMCResponse displays output similar to the following: 
    Certificates:
    Certificate:
        Data:
            Version:  v3
            Serial Number: 0x1
            Signature Algorithm: SHA256withRSA - 1.2.840.113549.1.1.11
            Issuer: CN=CA Signing Certificate,OU=pki-tomcat,O=unknown00262DFC6A5E Security Domain
            Validity:
                Not Before: Wednesday, May 17, 2017 6:06:50 PM PDT America/Los_Angeles
                Not  After: Sunday, May 17, 2037 6:06:50 PM PDT America/Los_Angeles
            Subject: CN=CA Signing Certificate,OU=pki-tomcat,O=unknown00262DFC6A5E Security Domain
...
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
    Copy to Clipboard Toggle word wrap
  9. For the second trip, create a configuration file for DecryptedPOP, such as /home/user_name/cmc_DecryptedPOP.cfg, which you use in a later step. Add the following content to the created file: 
    #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 2nd trip
input=/home/user_name/crmf.req

#output: full path for the CMC request in binary format
#this field is actually unused in 2nd trip
output=/home/user_name/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 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, either pkcs10 or crmf
format=crmf

decryptedPop.enable=true
encryptedPopResponseFile=/home/user_name/cmc-response_round_1.bin
request.privKeyId=-25aa0a8aad395ebac7e6a19c364f0dcb5350cfef
decryptedPopRequestFile=/home/user_name/cmc.DecryptedPOP.req
    Copy to Clipboard Toggle word wrap
  10. Create the DecryptPOP CMC request: 
    $ CMCRequest /home/user_name/cmc.DecryptedPOP.cfg
    Copy to Clipboard Toggle word wrap
    If the command succeeds, the CMCRequest utility stored the CMC request in the file specified in the decryptedPopRequestFile parameter in the request configuration file.
  11. Create a configuration file for HttpClient, such as /home/user_name/decrypted_POP_cmc-submit.cfg, which you 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: 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/cmc.DecryptedPOP.req

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

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

#dbdir: directory for cert8.db, key3.db and secmod.db
#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 cert8.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=singing_certificate

#servlet: servlet name
servlet=/ca/ee/ca/profileSubmitUserSignedCMCFull?profileId=caFullCMCUserCert
    Copy to Clipboard Toggle word wrap
  12. Submit the DecryptedPOP CMC request to the CA: 
    $ HttpClient /home/user_name/decrypted_POP_cmc-submit.cfg
    Copy to Clipboard Toggle word wrap
    If the command succeeds, the HTTPClient utility stored the CMC response in the file specified in the output parameter in the configuration file.
  13. 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_round_2.bin -o /home/user_name/certs.p7
    Copy to Clipboard Toggle word wrap
    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: 0x2D
            Signature Algorithm: SHA256withRSA - 1.2.840.113549.1.1.11
            Issuer: CN=CA Signing Certificate,OU=pki-tomcat,O=unknown00262DFC6A5E Security Domain
            Validity:
                Not Before: Thursday, June 15, 2017 3:43:45 PM PDT America/Los_Angeles
                Not  After: Tuesday, December 12, 2017 3:43:45 PM PST America/Los_Angeles
            Subject: CN=user_name,UID=example,OU=keyArchivalExample
...
Number of controls is 1
Control #0: CMCStatusInfo
   OID: {1 3 6 1 5 5 7 7 1}
   BodyList: 1
   Status: SUCCESS
    Copy to Clipboard Toggle word wrap
Torna in cima
Red Hat logoGithubredditYoutubeTwitter

Formazione

Prova, acquista e vendi

Community

Informazioni sulla documentazione di Red Hat

Aiutiamo gli utenti Red Hat a innovarsi e raggiungere i propri obiettivi con i nostri prodotti e servizi grazie a contenuti di cui possono fidarsi. Esplora i nostri ultimi aggiornamenti.

Rendiamo l’open source più inclusivo

Red Hat si impegna a sostituire il linguaggio problematico nel codice, nella documentazione e nelle proprietà web. Per maggiori dettagli, visita il Blog di Red Hat.

Informazioni su Red Hat

Forniamo soluzioni consolidate che rendono più semplice per le aziende lavorare su piattaforme e ambienti diversi, dal datacenter centrale all'edge della rete.

Theme

© 2025 Red Hat