Dieser Inhalt ist in der von Ihnen ausgewählten Sprache nicht verfügbar.
5.6. Submitting Certificate requests 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.
- The Enrolling with CMC section in the Red Hat Certificate System Planning, Installation, and Deployment Guide.
- CMCRequest(1) man page
- CMCResponse(1) man page
CMC enrollment is possible in various ways to meet the requirements for different scenarios. Section 5.6.2, “The CMC Enrollment Process” supplements the Enrolling with CMC section in the Red Hat Certificate System Planning, Installation, and Deployment Guide with more details. Additionally, the Section 5.6.3, “Practical CMC Enrollment Scenarios” section enables administrators to decide which mechanisms should be used in which scenario.
5.6.1. Using CMC Enrollment Link kopierenLink in die Zwischenablage kopiert!
Link kopierenLink in die Zwischenablage kopiert!
CMC enrollment allows an enrollment client to use a CMCAuth plug-in for authentication, by which the certificate request is pre-signed with an agent certificate. The Certificate Manager automatically issues certificates when a valid request signed with the agent certificate is received.
Note
CMC enrollments are enabled by default. It should not be necessary to enable the CMC enrollment authentication plug-ins or profiles unless the configuration has been changed.
The CMCAuth authentication plug-in also provides CMC revocation for the client. CMC revocation allows the client to have the certificate request signed by the agent certificate, and then send such a request to the Certificate Manager. The Certificate Manager automatically revokes certificates when a valid request signed with the agent certificate is received. CMC revocation can be created with the
CMCRevoke
command line tool. For more information about CMCRevoke
, see Section 7.2, “Performing a CMC Revocation”.
A CMC request can be submitted through browser end-entities forms or using a tool such as
HttpClient
to post the request to the appropriate profile. The CMCRequest
tool generates a signed certificate request which can then be submitted using the HttpClient
tool or the browser end-entities forms to enroll and receive the certificate automatically and immediately.
The
CMCRequest
tool has a simple command syntax, with all the configuration given in the .cfg
input file:
CMCRequest /path/to/file.cfg
CMCRequest /path/to/file.cfg
A single CMC enrollment can also be created using the
CMCEnroll
tool, with the following syntax:
CMCEnroll -d /agent's/certificate/directory -h password -n cert_nickname -r certrequest.file -p certDB_passwd [-c "comment"]
CMCEnroll -d /agent's/certificate/directory -h password -n cert_nickname -r certrequest.file -p certDB_passwd [-c "comment"]
These tools are described in more detail in the
CMCEnroll(1)
man page.
Note
Surround values that include spaces in quotation marks.
5.6.1.1. Testing CMCEnroll Link kopierenLink in die Zwischenablage kopiert!
Link kopierenLink in die Zwischenablage kopiert!
- Create a certificate request using the
certutil
tool. - Copy the PKCS #10 ASCII output to a text file.
- Run the CMCEnroll utility.For example, if the input file called
request34.txt
, the agent certificate is stored in the browser databases, the certificate common name of the agent certificate isCertificateManagerAgentsCert
, and the password for the certificate database issecret
, the command is as follows:CMCEnroll -d ~jsmith/.mozilla/firefox/1234.jsmith -n "CertificateManagerAgentsCert" -r /export/requests/request34.txt -p secret
CMCEnroll -d ~jsmith/.mozilla/firefox/1234.jsmith -n "CertificateManagerAgentsCert" -r /export/requests/request34.txt -p secret
Copy to Clipboard Copied! Toggle word wrap Toggle overflow The output of this command is stored in a file with the same filename with.out
appended to the filename. - Submit the signed certificate through the end-entities page.
- Open the end-entities page.
https://server.example.com:8443/ca/ee/ca
https://server.example.com:8443/ca/ee/ca
Copy to Clipboard Copied! Toggle word wrap Toggle overflow - Select the CMC enrollment form from the list of certificate profiles.
- Paste the content of the output file into the Certificate Request text area of this form.
- Remove
-----BEGIN NEW CERTIFICATE REQUEST-----
and----END NEW CERTIFICATE REQUEST-----
from the pasted content. - Fill in the contact information, and submit the form.
- The certificate is immediately processed and returned.
- Use the agent page to search for the new certificate.
5.6.2. The CMC Enrollment Process Link kopierenLink in die Zwischenablage kopiert!
Link kopierenLink in die Zwischenablage kopiert!
Use the following general procedure to request and issue a certificate using CMC:
- 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”. - 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
$ openssl pkcs12 -in /root/.dogtag/instance/ca_admin_cert.p12 -clcerts -nodes -nokeys -out /root/.dogtag/instance/ca_admin_cert.crt
Copy to Clipboard Copied! Toggle word wrap Toggle overflow - Validate and import the admin client certificate according to guidance in Managing Certificate/Key Crypto Token section in the Red Hat Certificate System Planning, Installation, and Deployment Guide:
PKICertImport -d . -n "CA Admin - Client Certificate" -t ",," -a -i /root/.dogtag/instance/ca_admin_cert.crt -u C
$ PKICertImport -d . -n "CA Admin - Client Certificate" -t ",," -a -i /root/.dogtag/instance/ca_admin_cert.crt -u C
Copy to Clipboard Copied! Toggle word wrap Toggle overflow 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
$ 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 Copied! Toggle word wrap Toggle overflow
- Create a configuration file for a CMC request, such as
/home/user_name/cmc-request.cfg
, with the following content:Copy to Clipboard Copied! Toggle word wrap Toggle overflow For further details, see the CMCRequest(1) man page. - Create the CMC request:
CMCRequest /home/user_name/cmc-request.cfg
$ CMCRequest /home/user_name/cmc-request.cfg
Copy to Clipboard Copied! Toggle word wrap Toggle overflow If the command succeeds, theCMCRequest
utility stored the CMC request in the file specified in theoutput
parameter in the request configuration file. - 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:Copy to Clipboard Copied! Toggle word wrap Toggle overflow Important
The nickname of the certificate specified in thenickname
parameter must match the one previously used for the CMC request. - 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
servlet=/ca/ee/ca/profileSubmitCMCFull?profileId=profile_name
Copy to Clipboard Copied! Toggle word wrap Toggle overflow For example, for a CA signing certificate:servlet=/ca/ee/ca/profileSubmitCMCFull?profileId=caCMCcaCert
servlet=/ca/ee/ca/profileSubmitCMCFull?profileId=caCMCcaCert
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Important
When an agent submits the CMC request in the next step, the profile specified in this parameter must use theCMCAuth
authentication plug-in. Whereas in user-initiated enrollments, the profile must use theCMCUserSignedAuth
plug-in. For further details, see the Section 9.3, “CMC Authentication Plug-ins”. - Submit the CMC request to the CA:
HttpClient /home/user_name/cmc-submit.cfg
$ HttpClient /home/user_name/cmc-submit.cfg
Copy to Clipboard Copied! Toggle word wrap Toggle overflow - To convert the CMC response to a PKCS #7 certificate chain, pass the CMC response file to the
-i
parameter of theCMCResponse
utility. For example:CMCResponse -i /home/user_name/cmc-response.bin -o /home/user_name/cert_chain.crt
$ CMCResponse -i /home/user_name/cmc-response.bin -o /home/user_name/cert_chain.crt
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
5.6.3. Practical CMC Enrollment Scenarios Link kopierenLink in die Zwischenablage kopiert!
Link kopierenLink in die Zwischenablage kopiert!
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.6.2, “The CMC Enrollment Process”.
5.6.3.1. Obtaining System and Server Certificates Link kopierenLink in die Zwischenablage kopiert!
Link kopierenLink in die Zwischenablage kopiert!
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.6.2, “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 9.3, “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 theCMCRequest
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 forHttpClient
. HttpClient
servlet
Parameter- The
servlet
in the configuration file passed to theHttpClient
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
servlet=/ca/ee/ca/profileSubmitCMCFull?profileId=caCMCcaCert
Copy to Clipboard Copied! Toggle word wrap Toggle overflow - For a KRA transport certificate:
servlet=/ca/ee/ca/profileSubmitCMCFull?profileId=caCMCkraTransportCert
servlet=/ca/ee/ca/profileSubmitCMCFull?profileId=caCMCkraTransportCert
Copy to Clipboard Copied! Toggle word wrap Toggle overflow - For a OCSP signing certificate:
servlet=/ca/ee/ca/profileSubmitCMCFull?profileId=caCMCocspCert
servlet=/ca/ee/ca/profileSubmitCMCFull?profileId=caCMCocspCert
Copy to Clipboard Copied! Toggle word wrap Toggle overflow - For a audit signing certificate:
servlet=/ca/ee/ca/profileSubmitCMCFull?profileId=caCMCauditSigningCert
servlet=/ca/ee/ca/profileSubmitCMCFull?profileId=caCMCauditSigningCert
Copy to Clipboard Copied! Toggle word wrap Toggle overflow - For a subsystem certificate:
- For RSA certificates:
servlet=/ca/ee/ca/profileSubmitCMCFull?profileId=caCMCsubsystemCert
servlet=/ca/ee/ca/profileSubmitCMCFull?profileId=caCMCsubsystemCert
Copy to Clipboard Copied! Toggle word wrap Toggle overflow - For ECC certificates:
servlet=/ca/ee/ca/profileSubmitCMCFull?profileId=caCMCECCsubsystemCert
servlet=/ca/ee/ca/profileSubmitCMCFull?profileId=caCMCECCsubsystemCert
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
- For a TLS server certificate:
- For RSA certificates:
servlet=/ca/ee/ca/profileSubmitCMCFull?profileId=caCMCserverCert
servlet=/ca/ee/ca/profileSubmitCMCFull?profileId=caCMCserverCert
Copy to Clipboard Copied! Toggle word wrap Toggle overflow - For ECC certificates:
servlet=/ca/ee/ca/profileSubmitCMCFull?profileId=caCMCECCserverCert
servlet=/ca/ee/ca/profileSubmitCMCFull?profileId=caCMCECCserverCert
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
- For an admin certificate:
servlet=/ca/ee/ca/profileSubmitCMCFull?profileId=caFullCMCUserCert
servlet=/ca/ee/ca/profileSubmitCMCFull?profileId=caFullCMCUserCert
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
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.6.3.2. Obtaining the First Signing Certificate for a User Link kopierenLink in die Zwischenablage kopiert!
Link kopierenLink in die Zwischenablage kopiert!
There are two ways to approve a user's first signing certificate:
- An agent signs the CMC request. See Section 5.6.3.2.1, “Signing a CMC Request with an Agent Certificate”.
- Certificate enrollment is authenticated by using a Shared Secret. See Section 5.6.3.2.2, “Authenticating for Certificate Enrollment Using a Shared Secret”.
5.6.3.2.1. Signing a CMC Request with an Agent Certificate Link kopierenLink in die Zwischenablage kopiert!
Link kopierenLink in die Zwischenablage kopiert!
The process for signing a CMC request with an agent certificate is the same as for system and server certificates described in Section 5.6.3.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.6.3.3. Obtaining an Encryption-only Certificate for a User Link kopierenLink in die Zwischenablage kopiert!
Link kopierenLink in die Zwischenablage kopiert!
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.6.3.2, “Obtaining the First Signing Certificate for a User”.
As a user:
- 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.
- Generate the CSR in PKCS #10 or the CRMF format.
Note
Use the CRMF format, if key archival is required. - 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 theDecryptedPOP
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 CApopLinkWitnessV2.keyGenAlg
if required by the CApopLinkWitnessV2.macAlg
if required by the CArequest.privKeyId
For details, see the CMCRequest(1) man page.The response contains:- A CMC encrypted POP control
- The
CMCStatusInfoV2
control with thePOP 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
For details, see the CMCRequest(1) man page.
5.6.3.3.1. Example on Obtaining an Encryption-only certificate with Key Archival Link kopierenLink in die Zwischenablage kopiert!
Link kopierenLink in die Zwischenablage kopiert!
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.1.3.1, “Using CRMFPopClient
to Create a CSR with Key Archival” and Section 5.2.1.3.2, “Using CRMFPopClient
to Create a CSR for SharedSecret-based CMC”.
- Search for the KRA transport certificate. For example:
pki cert-find --name KRA_transport_certificate_subject_CN
$ pki cert-find --name KRA_transport_certificate_subject_CN
Copy to Clipboard Copied! Toggle word wrap Toggle overflow - 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
$ pki cert-show 12345 --output /home/user_name/kra.cert
Copy to Clipboard Copied! Toggle word wrap Toggle overflow - Use the
CRMFPopClient
utility to:- Create a CSR with key archival:
- Change to the certificate database directory of the user or entity for which the certificate is being requested, for example:
cd /home/user_name/
$ cd /home/user_name/
Copy to Clipboard Copied! Toggle word wrap Toggle overflow - 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
$ 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 Copied! Toggle word wrap Toggle overflow Note the ID of the private key displayed by the command. The ID is required in a later step as value in therequest.privKeyId
parameter in the configuration file for the second trip.
- Create a configuration file for the
CRMRequest
utility, such as/home/user_name/cmc.cfg
with the following content:Copy to Clipboard Copied! Toggle word wrap Toggle overflow - Create the CMC request:
CMCRequest /home/user_name/cmc.cfg
$ CMCRequest /home/user_name/cmc.cfg
Copy to Clipboard Copied! Toggle word wrap Toggle overflow If the command succeeds, theCMCRequest
utility stored the CMC request in the file specified in theoutput
parameter in the request configuration file. - 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:Copy to Clipboard Copied! Toggle word wrap Toggle overflow - Submit the CMC request to the CA:
HttpClient /home/user_name/cmc-submit.cfg
$ HttpClient /home/user_name/cmc-submit.cfg
Copy to Clipboard Copied! Toggle word wrap Toggle overflow If the command succeeds, theHTTPClient
utility stored the CMC response in the file specified in theoutput
parameter in the configuration file. - 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
$ CMCResponse -d /home/user_name/.dogtag/nssdb/ -i /home/user_name/cmc-response_round_1.bin
Copy to Clipboard Copied! Toggle word wrap Toggle overflow If the first trip was successful,CMCResponse
displays output similar to the following:Copy to Clipboard Copied! Toggle word wrap Toggle overflow - 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:Copy to Clipboard Copied! Toggle word wrap Toggle overflow - Create the
DecryptPOP
CMC request:CMCRequest /home/user_name/cmc.DecryptedPOP.cfg
$ CMCRequest /home/user_name/cmc.DecryptedPOP.cfg
Copy to Clipboard Copied! Toggle word wrap Toggle overflow If the command succeeds, theCMCRequest
utility stored the CMC request in the file specified in thedecryptedPopRequestFile
parameter in the request configuration file. - 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 theDecryptedPOP
CMC request to the CA. Add the following content to the created file:Copy to Clipboard Copied! Toggle word wrap Toggle overflow - Submit the
DecryptedPOP
CMC request to the CA:HttpClient /home/user_name/decrypted_POP_cmc-submit.cfg
$ HttpClient /home/user_name/decrypted_POP_cmc-submit.cfg
Copy to Clipboard Copied! Toggle word wrap Toggle overflow If the command succeeds, theHTTPClient
utility stored the CMC response in the file specified in theoutput
parameter in the configuration file. - To convert the CMC response to a PKCS #7 certificate chain, pass the CMC response file to the
-i
parameter of theCMCResponse
utility. For example:CMCResponse -i /home/user_name/cmc-response_round_2.bin -o /home/user_name/certs.p7
$ CMCResponse -i /home/user_name/cmc-response_round_2.bin -o /home/user_name/certs.p7
Copy to Clipboard Copied! Toggle word wrap Toggle overflow 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:Copy to Clipboard Copied! Toggle word wrap Toggle overflow