Administration Guide (Common Criteria Edition)
Updated for Red Hat Certificate System 9.4 Common Criteria Certification
Edition 9.4-1
Abstract
Chapter 1. Overview of Red Hat Certificate System Subsystems
Note
Note
1.1. Uses for Certificates
1.2. A Review of Certificate System Subsystems
1.3. A Look at Managing Certificates (Non-TMS)
- Managing Certificates
- Using a Single Certificate Manager
- Planning for Lost Keys: Key Archival and Recovery
- Balancing Certificate Request Processing
- Balancing Client OCSP Requests
1.4. A Look at the Token Management System (TMS)
Note
- Working with Smart Cards (TMS)
- Using Smart Cards
1.5. Red Hat Certificate System services
Part I. Red Hat Certificate System User Interfaces
Chapter 2. User Interfaces
2.1. User Interfaces Overview
- The PKI command-line interface and other command-line utilities
- The PKI Console graphical interface
- The Certificate System web interface.
~/.dogtag/nssdb/
directory. Section 2.5.1.1, “pki CLI Initialization” provides detailed steps for initializing the NSS database with the administrator's certificate and key. Some examples of using the PKI command-line utility are described in Section 2.5.1.2, “Using "pki" CLI”. Additional examples are shown through the rest of the guide.
PKCS10Client
”.
pkiconsole
Initialization” describes how to initialize it. Section 2.3.2, “Using pkiconsole
for CA, OCSP, KRA, and TKS Subsystems” gives an overview of using the console interface. Later sections, such as Section 3.2.2, “Managing Certificate Enrollment Profiles Using the Java-based Administration Console” go into greater detail for specific operations.
Note
2.2. Client NSS Database Initialization
- Prepare an NSS database for the client. This can be a new database or an existing one.
- Import the CA certificate chain and trust them.
- Have a certificate and corresponding key. They can be generated in the NSS database or imported from somewhere else, such as from a PKCS #12 file.
2.3. Graphical Interface
pkiconsole
is a graphical interface that is designed for users with the Administrator role privilege to manage the subsystem itself. This includes adding users, configuring logs, managing profiles and plug-ins, and the internal database, among many other functions. This utility communicates with the Certificate System server via TLS using client-authentication and can be used to manage the server remotely.
2.3.1. pkiconsole
Initialization
pkiconsole
interface for the first time, specify a new password and use the following command:
$ pki -c password -d ~/.redhat-idm-console client-init
~/.redhat-idm-console/
directory.
.p12
file:
$ openssl pkcs12 -in file -clcerts -nodes -nokeys -out file.crt
$ PKICertImport -d ~/.redhat-idm-console -n "nickname" -t ",," -a -i file.crt -u C
Important
$ pki -c password -d ~/.redhat-idm-console pkcs12-import --pkcs12-file file --pkcs12-password pkcs12-password
$ certutil -V -u C -n "nickname" -d ~/.redhat-idm-console
2.3.2. Using pkiconsole
for CA, OCSP, KRA, and TKS Subsystems
pkiconsole
utility. It can access any subsystem because the command requires the host name, the subsystem's administrative TLS port, and the specific subsystem type.
pkiconsole https://server.example.com:admin_port/subsystem_type
https://192.0.2.1:8443/ca https://[2001:DB8::1111]:8443/ca
Figure 2.1. Certificate System Console
- Users and groups
- Access control lists
- Log configuration
- Subsystem certificates (meaning the certificates issued to the subsystem for use, for example, in the security domain or audit signing)
2.4. Web Interface
2.4.1. Browser Initialization
Importing a CA Certificate
- Click→ → → .
- Select the Authorities tab and click the button.
- Select the
ca.crt
file and click .
Importing a Client Certificate
- Click→ → → .
- Select the Your Certificates tab.
- Click onand select the client p12 file, such as
ca_admin_cert.p12
. - Enter the password for the client certificate on the prompt.
- Click.
- Verify that an entry is added under Your Certificates.
Accessing the Web Console
https://host_name:port
in your browser.
2.4.2. The Administrative Interfaces
Note
Figure 2.2. TPS Admin Page
2.4.3. Agent Interfaces
Figure 2.3. Certificate Manager's Agent Services Page
- The Certificate Manager agent services include approving certificate requests (which issues the certificates), revoking certificates, and publishing certificates and CRLs. All certificates issued by the CA can be managed through its agent services page.
- The TPS agent services, like the CA agent services, manages all of the tokens which have been formatted and have had certificates issued to them through the TPS. Tokens can be enrolled, suspended, and deleted by agents. Two other roles (operator and admin) can view tokens in web services pages, but cannot perform any actions on the tokens.
- KRA agent services pages process key recovery requests, which set whether to allow a certificate to be issued reusing an existing key pair if the certificate is lost.
- The OCSP agent services page allows agents to configure CAs which publish CRLs to the OCSP, to load CRLs to the OCSP manually, and to view the state of client OCSP requests.
2.4.4. End User Pages
Figure 2.4. Certificate Manager's End-Entities Page
2.5. Command Line Interfaces
2.5.1. "pki" CLI
pki
command-line interface (CLI) provides access to various services on the server using the REST interface (see the REST Interface section in the Red Hat Certificate System Planning, Installation, and Deployment Guide (Common Criteria Edition)). The CLI can be invoked as follows:
$
pki [CLI options]
<command> [command parameters]
2.5.1.1. pki CLI Initialization
$
pki -c <password> client-init
~/.dogtag/nssdb
directory. The password must be specified in all CLI operations that uses the client NSS database. Alternatively, if the password is stored in a file, you can specify the file using the -C
option. For example:
$
pki -C password_file client-init
.p12
file:
$ openssl pkcs12 -in file -clcerts -nodes -nokeys -out file.crt
$ PKICertImport -d ~/.dogtag/nssdb -n "nickname" -t ",," -a -i file.crt -u C
Important
$
pki -c <password> pkcs12-import --pkcs12-file <file> --pkcs12-password <password>
certutil -V -u C -n "nickname" -d ~/.dogtag/nssdb
2.5.1.2. Using "pki" CLI
pki
command without any additional commands or parameters:
$
pki
pki
with the command name and no additional options. For example:
$
pki ca
$
pki ca-cert
--help
option:
$
pki --help
$
pki ca-cert-find --help
help
command:
$
pki help
$
pki help ca-cert-find
$
pki ca-cert-find
$
pki -U <server URL> -n <nickname> -c <password> <command> [command parameters]
$
pki -n jsmith -c password ca-user-find ...
http://local_host_name:8080
. To communicate with a server at a different location, specify the URL with the -U
option, for example:
$
pki -U https://server.example.com:8443 -n jsmith -c password ca-user-find
2.5.2. AtoB
$
AtoB input.ascii output.bin
2.5.3. AuditVerify
$ AuditVerify -d ~jsmith/auditVerifyDir -n Log Signing Certificate -a ~jsmith/auditVerifyDir/logListFile -P "" -v
Log Signing Certificate
(-n
) in the ~jsmith/auditVerifyDir
NSS database (-d
). The list of logs to verify (-a
) are in the ~jsmith/auditVerifyDir/logListFile
file, comma-separated and ordered chronologically. The prefix (-P
) to prepend to the certificate and key database file names is empty. The output is verbose (-v
).
2.5.4. BtoA
$
BtoA input.bin output.ascii
2.5.5. CMCRequest
$
CMCRequest example.cfg
Note
CMCRequest
utility are specified as part of the configuration filed passed to the utility. See the CMCRequest(1) man page for configuration file options and further information. Also see 4.3. Requesting and Receiving Certificates Using CMC and 6.2.1. Revoking a Certificate Using CMCRequest in Red Hat Certificate System Administration Guide.
2.5.6. CMCRevoke
2.5.8. CRMFPopClient
CRMFPopClient
utility is Certificate Request Message Format (CRMF) client using NSS databases and supplying Proof of Possession.
$ CRMFPopClient -d . -p password -n "cn=subject_name" -q POP_SUCCESS -b kra.transport -w "AES/CBC/PKCS5Padding" -t false -v -o /user_or_entity_database_directory/example.csr
cn=subject_name
subject DN (-n)
, NSS database in the current directory (-d
), certificate to use for transport kra.transport
(-b
), the AES/CBC/PKCS5Padding
key wrap algorithm verbose output is specified (-v
) and the resulting CSR is written to the /user_or_entity_database_directory/example.csr
file (-o)
.
CRMFPopClient --help
command and also 4.2.4. Creating a CSR Using CRMFPopClient in Red Hat Certificate System Administration Guide.
2.5.9. HttpClient
HttpClient
utility is an NSS-aware HTTP client for submitting CMC requests.
$ HttpClient request.cfg
Note
HttpClient
utility are stored in the request.cfg
file. For further information, see the output of the HttpClient --help
command.
2.5.10. OCSPClient
$ OCSPClient -h server.example.com -p 8080 -d /etc/pki/pki-tomcat/alias -c "caSigningCert cert-pki-ca" --serial 2
server.example.com
OCSP server (-h
) on port 8080
(-p
) to check whether the certificate signed by caSigningcet cert-pki-ca
(-c
) with serial number 2
(--serial
) is valid. The NSS database in the /etc/pki/pki-tomcat/alias
directory is used.
OCSPClient --help
command.
2.5.11. PKCS10Client
PKCS10Client
utility creates a CSR in PKCS10 format for RSA and EC keys, optionally on an HSM.
$ PKCS10Client -d /etc/dirsrv/slapd-instance_name/ -p password -a rsa -l 2048 -o ~/ds.csr -n "CN=$HOSTNAME"
-a
) key with 2048 bits (-l
) in the /etc/dirsrv/slapd-instance_name/
directory (-d
with database password password
(-p
). The output CSR is stored in the ~/ds.cfg
file (-o
) and the certificate DN is CN=$HOSTNAME
(-n
).
2.5.12. PrettyPrintCert
$ PrettyPrintCert ascii_data.cert
ascii_data.cert
file and displays its contents in human readable format. The output includes information like signature algorithm, exponent, modulus, and certificate extensions.
2.5.13. PrettyPrintCrl
$ PrettyPrintCrl ascii_data.crl
ascii_data.crl
and displays its contents in human readable format. The output includes information, such as revocation signature algorithm, the issuer of the revocation, and a list of revoked certificates and their reason.
2.5.14. TokenInfo
$ TokenInfo ./nssdb/
TokenInfo
command
2.5.15. tkstool
tkstool
utility is interacting with the token Key Service (TKS) subsystem.
$ tkstool -M -n new_master -d /var/lib/pki/pki-tomcat/alias -h token_name
-M
) named new_master
(-n
) in the /var/lib/pki/pki-tomcat/alias
NSS database on the HSM token_name
tkstool -H
command.
Part II. Setting up Certificate Services
Note
CS.cfg
, server.xml
or any configuration file post-installation is expressly prohibited in a certified environment.
Chapter 3. Making Rules for Issuing Certificates (Certificate Profiles)
3.1. About Certificate Profiles
- Authentication. In every certification profile can be specified an authentication method.
- Authorization. In every certification profile can be specified an authorization method.
- Profile inputs. Profile inputs are parameters and values that are submitted to the CA when a certificate is requested. Profile inputs include public keys for the certificate request and the certificate subject name requested by the end entity for the certificate.
- Profile outputs. Profile outputs are parameters and values that specify the format in which to provide the certificate to the end entity. Profile outputs are CMC responses which contain a PKCS#7 certificate chain, when the request was successful.
- Certificate content. Each certificate defines content information, such as the name of the entity to which it is assigned (the subject name), its signing algorithm, and its validity period. What is included in a certificate is defined in the X.509 standard. With version 3 of the X509 standard, certificates can also contain extensions. For more information about certificate extensions, see Section B.3, “Standard X.509 v3 Certificate Extension Reference”.All of the information about a certificate profile is defined in the
set
entry of the profile policy in the profile's configuration file. When multiple certificates are expected to be requested at the same time, multiple set entries can be defined in the profile policy to satisfy needs of each certificate. Each policy set consists of a number of policy rules and each policy rule describes a field in the certificate content. A policy rule can include the following parts:- Profile defaults. These are predefined parameters and allowed values for information contained within the certificate. Profile defaults include the validity period of the certificate, and what certificate extensions appear for each type of certificate issued.
- Profile constraints. Constraints set rules or policies for issuing certificates. Amongst other, profile constraints include rules to require the certificate subject name to have at least one CN component, to set the validity of a certificate to a maximum of 360 days, to define the allowed grace period for renewal, or to require that the
subjectaltname
extension is always set totrue
.
3.1.1. The Enrollment Profile
caUserCert
profile in Example 3.1, “Example caCMCUserCert Profile”.
Example 3.1. Example caCMCUserCert Profile
desc=This certificate profile is for enrolling user certificates by using the CMC certificate request with CMC Signature authentication. visible=true enable=true enableBy=admin name=Signed CMC-Authenticated User Certificate Enrollment
Note
auth.instance_id=
entry in this profile means that with this profile, authentication is not needed to submit the enrollment request. However, manual approval by an authorized CA agent will be required to get an issuance.
input.list=i1 input.i1.class_id=cmcCertReqInputImp
caCMCUserCert
profile, this defines the certificate request type, which is CMC.
certOutputImpl
, which results in CMC response to be returned to the requestor in case of success.
output.list=o1 output.o1.class_id=certOutputImpl
policyset.list
parameter identifies the block name of the policies that apply to one certificate; the policyset.userCertSet.list
lists the individual policies to apply.
policyset.list=userCertSet policyset.userCertSet.list=1,10,2,3,4,5,6,7,8,9 ... policyset.userCertSet.6.constraint.class_id=keyUsageExtConstraintImpl policyset.userCertSet.6.constraint.name=Key Usage Extension Constraint policyset.userCertSet.6.constraint.params.keyUsageCritical=true policyset.userCertSet.6.constraint.params.keyUsageDigitalSignature=true policyset.userCertSet.6.constraint.params.keyUsageNonRepudiation=true policyset.userCertSet.6.constraint.params.keyUsageDataEncipherment=false policyset.userCertSet.6.constraint.params.keyUsageKeyEncipherment=true policyset.userCertSet.6.constraint.params.keyUsageKeyAgreement=false policyset.userCertSet.6.constraint.params.keyUsageKeyCertSign=false policyset.userCertSet.6.constraint.params.keyUsageCrlSign=false policyset.userCertSet.6.constraint.params.keyUsageEncipherOnly=false policyset.userCertSet.6.constraint.params.keyUsageDecipherOnly=false policyset.userCertSet.6.default.class_id=keyUsageExtDefaultImpl policyset.userCertSet.6.default.name=Key Usage Default policyset.userCertSet.6.default.params.keyUsageCritical=true policyset.userCertSet.6.default.params.keyUsageDigitalSignature=true policyset.userCertSet.6.default.params.keyUsageNonRepudiation=true policyset.userCertSet.6.default.params.keyUsageDataEncipherment=false policyset.userCertSet.6.default.params.keyUsageKeyEncipherment=true policyset.userCertSet.6.default.params.keyUsageKeyAgreement=false policyset.userCertSet.6.default.params.keyUsageKeyCertSign=false policyset.userCertSet.6.default.params.keyUsageCrlSign=false policyset.userCertSet.6.default.params.keyUsageEncipherOnly=false policyset.userCertSet.6.default.params.keyUsageDecipherOnly=false ...
3.1.2. Certificate Extensions: Defaults and Constraints
policyset.caCertSet.5.default.name=Basic Constraints Extension Default policyset.caCertSet.5.default.params.basicConstraintsCritical=true policyset.caCertSet.5.default.params.basicConstraintsIsCA=true policyset.caCertSet.5.default.params.basicConstraintsPathLen=-1
policyset.caCertSet.5.constraint.class_id=basicConstraintsExtConstraintImpl policyset.caCertSet.5.constraint.name=Basic Constraint Extension Constraint policyset.caCertSet.5.constraint.params.basicConstraintsCritical=true policyset.caCertSet.5.constraint.params.basicConstraintsIsCA=true policyset.caCertSet.5.constraint.params.basicConstraintsMinPathLen=-1 policyset.caCertSet.5.constraint.params.basicConstraintsMaxPathLen=-1
Note
3.1.3. Inputs and Outputs
input.i1.class_id
parameter in all enabled profiles to cmcCertReqInputImpl
:
input.i1.class_id=cmcCertReqInputImpl
output.o1.class_id
parameter in all enabled profiles to certOutputImpl
:
output.o1.class_id=CertOutputImpl
/ca/ee/ca/profileSubmitUserSignedCMCFull
servlet that is accessed through the end-entities interface.
3.2. Setting up Certificate Profiles
- Using the PKI command-line interface
- Using the Java-based administration console
3.2.1. Managing Certificate Enrollment Profiles Using the PKI Command-line Interface
pki
utility. For further details, see the pki-ca-profile(1) man page.
Note
3.2.1.1. Enabling and Disabling a Certificate Profile
Note
caCMCECserverCert
certificate profile:
# pki -c password -n caagent ca-profile-disable caCMCECserverCert
caCMCECserverCert
certificate profile:
# pki -c password -n caagent ca-profile-enable caCMCECserverCert
3.2.1.2. Creating a Certificate Profile in Raw Format
# pki -c password -n caadmin ca-profile-add profile_name.cfg --raw
Note
profileId=profile_name
3.2.1.3. Editing a Certificate Profile in Raw Format
caCMCECserverCert
profile:
# pki -c password -n caadmin ca-profile-edit caCMCECserverCert
VI
editor. When you close the editor, the profile configuration is updated on the server.
Important
Example 3.2. Editing a Certificate Profile in RAW Format
caCMCserverCert
profile to accept multiple user-supplied extensions:
- Disable the profile as a CA agent:
# pki -c password -n caagemt ca-profile-disable caCMCserverCert
- Edit the profile as a CA administrator:
- Download and open the profile in the
VI
editor:# pki -c password -n caadmin ca-profile-edit caCMCserverCert
- Update the configuration to accept the extensions. For details, see Example B.3, “Multiple User Supplied Extensions in CSR”.
- Enable the profile as a CA agent:
# pki -c password -n caagent ca-profile-enable caCMCserverCert
3.2.1.4. Deleting a Certificate Profile
# pki -c password -n caadmin ca-profile-del profile_name
Important
3.2.2. Managing Certificate Enrollment Profiles Using the Java-based Administration Console
3.2.2.1. Creating Certificate Profiles through the CA Console
- Log in to the Certificate System CA subsystem console.
pkiconsole https://server.example.com:8443/ca
- In the Configuration tab, select Certificate Manager, and then select Certificate Profiles.The Certificate Profile Instances Management tab, which lists configured certificate profiles, opens.
- To create a new certificate profile, click.In the Select Certificate Profile Plugin Implementation window, select the type of certificate for which the profile is being created.
- Fill in the profile information in the Certificate Profile Instance Editor.
- Certificate Profile Instance ID. This is the ID used by the system to identify the profile.
- Certificate Profile Name. This is the user-friendly name for the profile.
- Certificate Profile Description.
- End User Certificate Profile. This sets whether the request must be made through the input form for the profile. This is usually set to
true
. Setting this tofalse
allows a signed request to be processed through the Certificate Manager's certificate profile framework, rather than through the input page for the certificate profile. - Certificate Profile Authentication. This sets the authentication method. An automated authentication is set by providing the instance ID for the authentication instance. If this field is blank, the authentication method is agent-approved enrollment; the request is submitted to the request queue of the agent services interface.Unless it is for a TMS subsystem, administrators must select one of the following authentication plug-ins:
CMCAuth
: Use this plug-in when a CA agent must approve and submit the enrollment request.CMCUserSignedAuth
: Use this plug-in to enable non-agent users to enroll own certificates.
- Click. The plug-in editor closes, and the new profile is listed in the profiles tab.
- Configure the policies, inputs, and outputs for the new profile. Select the new profile from the list, and click.
- Set up policies in the Policies tab of the Certificate Profile Rule Editor window. The Policies tab lists policies that are already set by default for the profile type.
- To add a policy, click.
- Choose the default from the Default field, choose the constraints associated with that policy in the Constraints field, and click .
- Fill in the policy set ID. When issuing dual key pairs, separate policy sets define the policies associated with each certificate. Then fill in the certificate profile policy ID, a name or identifier for the certificate profile policy.
- Configure any parameters in the Defaults and Constraints tabs.Defaults defines attributes that populate the certificate request, which in turn determines the content of the certificate. These can be extensions, validity periods, or other fields contained in the certificates. Constraints defines valid values for the defaults.See Section B.1, “Defaults Reference” and Section B.2, “Constraints Reference” for complete details for each default or constraint.
To modify an existing policy, select a policy, and click. Then edit the default and constraints for that policy.To delete a policy, select the policy, and click. - Set inputs in the Inputs tab of the Certificate Profile Rule Editor window. There can be more than one input type for a profile.
Note
Unless you configure the profile for a TMS subsystem, select onlycmcCertReqInput
and delete other profiles by selecting them and clicking the button.- To add an input, click.
- Choose the input from the list, and click Section A.1, “Input Reference” for complete details of the default inputs.. See
- The New Certificate Profile Editor window opens. Set the input ID, and click .
Inputs can be added and deleted. It is possible to select edit for an input, but since inputs have no parameters or other settings, there is nothing to configure.To delete an input, select the input, and click. - Set up outputs in the Outputs tab of the Certificate Profile Rule Editor window.Outputs must be set for any certificate profile that uses an automated authentication method; no output needs to be set for any certificate profile that uses agent-approved authentication. The Certificate Output type is set by default for all profiles and is added automatically to custom profiles.Unless you configure the profile for a TMS subsystem, select only
certOutput
.Outputs can be added and deleted. It is possible to select edit for an output, but since outputs have no parameters or other settings, there is nothing to configure.- To add an output, click.
- Choose the output from the list, and click.
- Give a name or identifier for the output, and click.This output will be listed in the output tab. You can edit it to provide values to the parameters in this output.
To delete an output, select the output from list, and click. - Restart the CA to apply the new profile.
systemctl restart pki-tomcatd-nuxwdog@instance_name.service
- After creating the profile as an administrator, a CA agent has to approve the profile in the agent services pages to enable the profile.
- Open the CA's services page.
https://server.example.com:8443/ca/services
- Click the Manage Certificate Profiles link. This page lists all of the certificate profiles that have been set up by an administrator, both active and inactive.
- Click the name of the certificate profile to approve.
- At the bottom of the page, click thebutton.
Note
3.2.2.2. Editing Certificate Profiles in the Console
- Log into the agent services pages and disable the profile.Once a certificate profile is enabled by an agent, that certificate profile is marked enabled in the Certificate Profile Instance Management tab, and the certificate profile cannot be edited in any way through the console.
- Log in to the Certificate System CA subsystem console.
pkiconsole https://server.example.com:8443/ca
- In the Configuration tab, select Certificate Manager, and then select Certificate Profiles.
- Select the certificate profile, and click.
- The Certificate Profile Rule Editor window appears. Many any changes to the defaults, constraints, inputs, or outputs.
Note
The profile instance ID cannot be modified.If necessary, enlarge the window by pulling out one of the corners of the window. - Restart the CA to apply the changes.
- In the agent services page, re-enable the profile.
Note
3.2.3. Listing Certificate Enrollment Profiles
pki
utility. For example:
# pki -c password -n caadmin ca-profile-find ------------------ 59 entries matched ------------------ Profile ID: caCMCserverCert Name: Server Certificate Enrollment using CMC Description: This certificate profile is for enrolling server certificates using CMC. Profile ID: caCMCECserverCert Name: Server Certificate wth ECC keys Enrollment using CMC Description: This certificate profile is for enrolling server certificates with ECC keys using CMC. Profile ID: caCMCECsubsystemCert Name: Subsystem Certificate Enrollment with ECC keys using CMC Description: This certificate profile is for enrolling subsystem certificates with ECC keys using CMC. Profile ID: caCMCsubsystemCert Name: Subsystem Certificate Enrollment using CMC Description: This certificate profile is for enrolling subsystem certificates using CMC. ... ----------------------------- Number of entries returned 20
3.2.4. Displaying Details of a Certificate Enrollment Profile
caECFullCMCUserSignedCert
:
$ pki -c password -n caadmin ca-profile-show caECFullCMCUserSignedCert ----------------------------------- Profile "caECFullCMCUserSignedCert" ----------------------------------- Profile ID: caECFullCMCUserSignedCert Name: User-Signed CMC-Authenticated User Certificate Enrollment Description: This certificate profile is for enrolling user certificates with EC keys by using the CMC certificate request with non-agent user CMC authentication. Name: Certificate Request Input Class: cmcCertReqInputImpl Attribute Name: cert_request Attribute Description: Certificate Request Attribute Syntax: cert_request Name: Certificate Output Class: certOutputImpl Attribute Name: pretty_cert Attribute Description: Certificate Pretty Print Attribute Syntax: pretty_print Attribute Name: b64_cert Attribute Description: Certificate Base-64 Encoded Attribute Syntax: pretty_print
caECFullCMCUserSignedCert
, in raw format:
$ pki -c password -n caadmin ca-profile-show caECFullCMCUserSignedCert --raw #Wed Jul 25 14:41:35 PDT 2018 auth.instance_id=CMCUserSignedAuth policyset.cmcUserCertSet.1.default.params.name= policyset.cmcUserCertSet.4.default.class_id=authorityKeyIdentifierExtDefaultImpl policyset.cmcUserCertSet.6.default.params.keyUsageKeyCertSign=false policyset.cmcUserCertSet.10.default.class_id=noDefaultImpl policyset.cmcUserCertSet.10.constraint.name=Renewal Grace Period Constraint output.o1.class_id=certOutputImpl ...
3.3. Defining Key Defaults in Profiles
policyset.set1.p3.constraint.class_id=noConstraintImpl policyset.set1.p3.constraint.name=No Constraint policyset.set1.p3.default.class_id=subjectKeyIdentifierExtDefaultImpl policyset.set1.p3.default.name=Subject Key Identifier Default ... policyset.set1.p11.constraint.class_id=keyConstraintImpl policyset.set1.p11.constraint.name=Key Constraint policyset.set1.p11.constraint.params.keyType=RSA policyset.set1.p11.constraint.params.keyParameters=1024,2048,3072,4096 policyset.set1.p11.default.class_id=userKeyDefaultImpl policyset.set1.p11.default.name=Key Default
policyset
list, then, the Key Default (p11
) must be listed before the Subject Key Identifier Default (p3
).
policyset.set1.list=p1,p2,p11,p3
,p4,p5,p6,p7,p8,p9,p10
3.4. Configuring Profiles to Enable Renewal
3.4.1. About Renewal
3.4.1.1. The Renewal Process
renewGracePeriodConstraint
entry. For example:
policyset.cmcUserCertSet.10.constraint.class_id=renewGracePeriodConstraintImpl policyset.cmcUserCertSet.10.constraint.name=Renewal Grace Period Constraint policyset.cmcUserCertSet.10.constraint.params.renewal.graceBefore=30 policyset.cmcUserCertSet.10.constraint.params.renewal.graceAfter=30 policyset.cmcUserCertSet.10.default.class_id=noDefaultImpl policyset.cmcUserCertSet.10.default.name=No Default
3.4.1.1.1. Renewing Using the Same Key
allowSameKeyRenewal
parameter set to true
in the uniqueKeyConstraint
entry. For example:
policyset.cmcUserCertSet.9.constraint.class_id=uniqueKeyConstraintImpl policyset.cmcUserCertSet.9.constraint.name=Unique Key Constraint policyset.cmcUserCertSet.9.constraint.params.allowSameKeyRenewal=true policyset.cmcUserCertSet.9.default.class_id=noDefaultImpl policyset.cmcUserCertSet.9.default.name=No Default
3.4.1.1.2. Renewal Using a New Key
subjectDN
from the user signing certificate used to sign the request for the new certificate.
3.5. Setting the Signing Algorithms for Certificates
3.5.1. Setting the CA's Default Signing Algorithm
- Open the CA console.
pkiconsole https://server.example.com:8443/ca
- In the Configuration tab, expand the Certificate Manager tree.
- In the General Settings tab, set the algorithm to use in the Algorithm drop-down menu.
3.5.2. Setting the Signing Algorithm Default in a Profile
.cfg
file, the algorithm is set with two parameters:
policyset.cmcUserCertSet.8.constraint.class_id=signingAlgConstraintImpl policyset.cmcUserCertSet.8.constraint.name=No Constraint policyset.cmcUserCertSet.8.constraint.params.signingAlgsAllowed=SHA256withRSA,SHA512withRSA,SHA256withEC,SHA384withRSA,SHA384withEC,SHA512withEC policyset.cmcUserCertSet.8.default.class_id=signingAlgDefaultImpl policyset.cmcUserCertSet.8.default.name=Signing Alg policyset.cmcUserCertSet.8.default.params.signingAlg=-
Note
- Open the CA console.
pkiconsole https://server.example.com:8443/ca
- In the Configuration tab, expand the Certificate Manager tree.
- Click the Certificate Profiles item.
- Click the Policies tab.
- Select the Signing Alg policy, and click the button.
- To set the default signing algorithm, set the value in the Defaults tab. If this is set to -, then the profile uses the CA's default.
- To set a list of allowed signing algorithms which can be accepted in a certificate request, open the Constraints tab, and set the list of algorithms in the Value field for
signingAlgsAllowed
.The possible values for the constraint are listed in Section B.2.10, “Signing Algorithm Constraint”.
3.7. Managing Subject Names and Subject Alternative Names
Important
3.7.1. Using the Requester CN or UID in the Subject Name
cn
or uid
value from a certificate request can be used to build the subject name of the issued certificate. This section demonstrates a profile that requires the naming attribute (CN or UID) being specified in the Subject Name Constraint to be present in the certificate request. If the naming attribute is missing, the request is rejected.
- The CN or UID format is set in the
pattern
configuration in the Subject Name Constraint. - The format of the subject DN, including the CN or UID token and the specific suffix for the certificate, is set in the Subject Name Default.
policyset.serverCertSet.1.constraint.class_id=subjectNameConstraintImpl policyset.serverCertSet.1.constraint.name=Subject Name Constraint policyset.serverCertSet.1.constraint.params.pattern=CN=[^,]+,.+
policyset.serverCertSet.1.constraint.params.accept=true policyset.serverCertSet.1.default.class_id=subjectNameDefaultImpl policyset.serverCertSet.1.default.name=Subject Name Default policyset.serverCertSet.1.default.params.name=CN=$request.req_subject_name.cn$,DC=example, DC=com
cn=John Smith
, then the certificate will be issued with a subject DN of cn=John Smith,DC=example, DC=com
. If the request comes in but it has a UID of uid=jsmith
and no CN, then the request is rejected.
policyset.serverCertSet.1.constraint.class_id=subjectNameConstraintImpl policyset.serverCertSet.1.constraint.name=Subject Name Constraint policyset.serverCertSet.1.constraint.params.pattern=UID=[^,]+,.+
policyset.serverCertSet.1.constraint.params.accept=true policyset.serverCertSet.1.default.class_id=subjectNameDefaultImpl policyset.serverCertSet.1.default.name=Subject Name Default policyset.serverCertSet.1.default.params.name=UID=$request.req_subject_name.uid$,DC=example, DC=com
pattern
parameter is covered in Section B.2.11, “Subject Name Constraint” and Section B.1.28, “Subject Name Default”.
3.7.2. Inserting LDAP Directory Attribute Values and Other Information into the Subject Alt Name
policyset.userCertSet.8.default.class_id=subjectAltNameExtDefaultImpl policyset.userCertSet.8.default.name=Subject Alt Name Constraint policyset.userCertSet.8.default.params.subjAltNameExtCritical=false policyset.userCertSet.8.default.params.subjAltExtType_0=RFC822Name policyset.userCertSet.8.default.params.subjAltExtPattern_0=$request.requestor_email$ policyset.userCertSet.8.default.params.subjAltExtGNEnable_0=true
Type_
, Pattern_
, and Enable_
values numerically, such as Type_1
.
- Inserting LDAP attribute values requires enabling the user directory authentication plug-in,
SharedSecret
.- Open the CA Console.
pkiconsole https://server.example.com:8443/ca
- Select Authentication in the left navigation tree.
- In the Authentication Instance tab, click , and add an instance of the
SharedSecret
authentication plug-in. - Enter the following information:
Authentication InstanceID=SharedToken shrTokAttr=shrTok ldap.ldapconn.host=server.example.com ldap.ldapconn.port=636 ldap.ldapconn.secureConn=true ldap.ldapauth.bindDN=cn=Directory Manager password=password ldap.ldapauth.authtype=BasicAuth ldap.basedn=ou=People,dc=example,dc=org
- Save the new plug-in instance.
For information on setting a CMC shared token, see Section 8.1.3.2, “Setting a CMC Shared Secret”. - The
ldapStringAttributes
parameter instructs the authentication plug-in to read the value of themail
attribute from the user's LDAP entry and put that value in the certificate request. When the value is in the request, the certificate profile policy can be set to insert that value for an extension value.The format for thednpattern
parameter is covered in Section B.2.11, “Subject Name Constraint” and Section B.1.28, “Subject Name Default”. - To enable the CA to insert the LDAP attribute value in the certificate extension, edit the profile's configuration file, and insert a policy set parameter for an extension. For example, to insert the
mail
attribute value in the Subject Alternative Name extension in thecaFullCMCSharedTokenCert
profile, change the following code:policyset.setID.8.default.params.
subjAltExtPattern_0=$request.auth_token.mail[0]$
For more details about editing a profile, see Section 3.2.1.3, “Editing a Certificate Profile in Raw Format”. - Restart the CA.
systemctl restart pki-tomcatd-nuxwdog@instance_name.service
caFullCMCSharedTokenCert
profile enrollment form will have the Subject Alternative Name extension added with the value of the requester's mail
LDAP attribute. For example:
Identifier: Subject Alternative Name - 2.5.29.17 Critical: no Value: RFC822Name: jsmith@example.com
Pattern_
parameters in the policy set. The common tokens are listed in Table 3.1, “Variables Used to Populate Certificates”, and the default profiles contain examples for how these tokens are used.
Policy Set Token | Description |
---|---|
$request.auth_token.cn[0]$ | The LDAP common name (cn ) attribute of the user who requested the certificate. |
$request.auth_token.mail[0]$ | The value of the LDAP email (mail ) attribute of the user who requested the certificate. |
$request.auth_token.tokencertsubject$ | The certificate subject name. |
$request.auth_token.uid$ | The LDAP user ID (uid ) attribute of the user who requested the certificate. |
$request.auth_token.userdn$ | The user DN of the user who requested the certificate. |
$request.auth_token.userid$ | The value of the user ID attribute for the user who requested the certificate. |
$request.uid$ | The value of the user ID attribute for the user who requested the certificate. |
$request.requestor_email$ | The email address of the person who submitted the request. |
$request.request_name$ | The person who submitted the request. |
$request.upn$ | The Microsoft UPN. This has the format (UTF8String)1.3.6.1.4.1.311.20.2.3,$request.upn$. |
$server.source$ | Instructs the server to generate a version 4 UUID (random number) component in the subject name. This always has the format (IA5String)1.2.3.4,$server.source$. |
$request.auth_token.user$ | Used when the request was submitted by TPS. The TPS subsystem trusted manager who requested the certificate. |
$request.subject$ | Used when the request was submitted by TPS. The subject name DN of the entity to which TPS has resolved and requested for. For example, cn=John.Smith.123456789,o=TMS Org |
3.7.3. Using the CN Attribute in the SAN Extension
dNSName
Subject Alternative Name (SAN) value in the certificate request.
dNSName
value based on the CN is appended to existing SANs.
- Disable the profile:
# pki -c password -p 8080 \ -n "PKI Administrator for example.com" ca-profile-disable profile_name
- Edit the profile:
# pki -c password -p 8080 \ -n "PKI Administrator for example.com" ca-profile-edit profile_name
- Add the following configuration with a unique set number for the profile. For example:
policyset.serverCertSet.12.constraint.class_id=noConstraintImpl policyset.serverCertSet.12.constraint.name=No Constraint policyset.serverCertSet.12.default.class_id=commonNameToSANDefaultImpl policyset.serverCertSet.12.default.name=Copy Common Name to Subject
The previous example uses12
as the set number. - Append the new policy set number to the
policyset.userCertSet.list
parameter. For example:policyset.userCertSet.list=1,10,2,3,4,5,6,7,8,9,12
- Save the profile.
- Enable the profile:
# pki -c password -p 8080 \ -n "PKI Administrator for example.com" ca-profile-enable profile_name
Note
commonNameToSANDefaultImpl
default.
3.7.4. Accepting SAN Extensions from a CSR
3.7.4.1. Configuring a Profile to Retrieve SANs from a CSR
Note
caCMCECserverCert
:
prefix.constraint.class_id=noConstraintImpl prefix.constraint.name=No Constraint prefix.default.class_id=userExtensionDefaultImpl prefix.default.name=User supplied extension in CSR prefix.default.params.userExtOID=2.5.29.17
3.7.4.2. Generating a CSR with SANs
certutil
utility:
# certutil -R -k ec -q nistp256 -d . -s "cn=Example Multiple SANs" --extSAN dns:www.example.com,dns:www.example.org -a -o /root/request.csr.p10
Chapter 4. Setting up Key Archival and Recovery
Note
Note
Note
4.1. About Key Archival and Recovery
pki
utility, which can generate a key and a certificate profile which is configured to support key archival. For details about the pki
utility, see the Command-Line Interface (CLI) section in the Red Hat Certificate System Planning, Installation, and Deployment Guide (Common Criteria Edition).
4.1.1. Key Archival
Figure 4.1. How the Key Archival Process Works
- The client generates and encrypts its private key and submits the request to the CA.
- After approving the certificate request and issuing the certificate, the Certificate Manager sends it to the KRA for storage, along with the public key. The Certificate Manager waits for verification from the KRA that the private key has been received and stored and that it corresponds to the public encryption key.
- The KRA decrypts it with the transport private key. After confirming that the private encryption key corresponds to the public encryption key, the KRA encrypts it again with its public key pair of the storage key before storing it in its internal database.
- The Certificate Manager issues the certificate, which is embedded in the CMC response.
Figure 4.2. Async and Sync Recovery, Side by Side
Important
4.1.2. Key Recovery
- Generate a CRMF request and submit it through the CA’s enrollment portal.For more information, see Section 5.3.2.3.1, “Example on Obtaining an Encryption-only certificate with Key Archival”.
- Import the certificates into an email client capable of doing SMIME.
- Confirm that the key has been archived. In the KRA's agent services page, select Show completed requests. If the key has been archived successfully, there will be information about that key. If the key is not shown, check the logs, and correct the problem. If the key has been successfully archived, close the browser window.
- Verify the key. Send a signed and encrypted email. When the email is received, open it, and check the message to see if it is signed and encrypted. There should be a security icon at the top-right corner of the message window that indicates that the message is signed and encrypted.
- Delete the certificate. Check the encrypted email again; the mail client should not be able to decrypt the message.
- Test whether an archived key can be recovered successfully:
- Open the KRA's agent services page, and click the Recover Keys link. Search for the key by the key owner, serial number, or public key. If the key has been archived successfully, the key information will be shown.
- Click.
- In the form that appears, enter the base-64 encoded certificate that corresponds to the private key to recover; use the CA to get this information. If the archived key was searched for by providing the base-64 encoded certificate, then the certificate does not have to be supplied here.
- Make sure that the Async Recovery checkbox is selected to allow the browser session to be closed while recovery is ongoing.
- Depending on the agent scheme, a specified number of agents must authorize this key recovery. Have the agents search for the key to recover and then to approve the initiated recovery.
- Once all the agents have authorized the recovery, the next screen requests a password to encrypt the PKCS #12 file with the certificate.
- The next screen returns a link to download a PKCS #12 blob containing the recovered key pair. Follow the link, and save the blob to file.
Important
Opening the PKCS #12 file directly from the browser in thegcr-viewer
utility can fail in certain situations. To work around the problem, download the file and manually open it ingcr-viewer
.
- Restore the key to the browser's database. Import the
.p12
file into the browser and mail client. - Open the test email. The message should be shown again.
Chapter 5. Requesting, Enrolling, and Managing Certificates
5.1. About Enrolling and Renewing Certificates
- A user generates a certificate request.
- The certificate request is submitted to the CA.
- 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.
- The request is approved.
- The user retrieves the new certificate.
5.2. Creating Certificate Signing Requests
CMCRequest
utility accepts Certificate Signing Requests (CSR) in PKCS #10 and CRMF format.
certutil
: Supports creating PKCS #10 requests.PKCS10Client
: Supports creating PKCS #10 requests.CRMFPopClient
: Supports creating CRMF requests.
5.2.1. Creating a CSR Using certutil
certutil
utility to create a CSR.
certutil
, see:
- The certutil(1) man page
- The output of the
certutil --help
command
5.2.1.1. Using certutil
to Create a CSR with EC Keys
certutil
utility to create an Elliptic Curve (EC) key pair and CSR:
- 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/
- Create the binary CSR and store it in the
/user_or_entity_database_directory/request.csr
file:$ certutil -d . -R -k ec -q nistp256 -s "CN=subject_name" -o /user_or_entity_database_directory/request-bin.csr
Enter the required NSS database password when prompted.For further details about the parameters, see the certutil(1) man page. - Convert the created binary format CSR to PEM format:
$ BtoA /user_or_entity_database_directory/request-bin.csr /user_or_entity_database_directory/request.csr
- Optionally, verify that the CSR file is correct:
$ cat /user_or_entity_database_directory/request.csr MIICbTCCAVUCAQAwKDEQMA4GA1UEChMHRXhhbXBsZTEUMBIGA1UEAxMLZXhhbXBs ...
This is a PKCS#10 PEM certificate request. - For the next steps, see Section 5.3.1, “The CMC Enrollment Process”, but skip the step about creating the certificate request.
5.2.1.2. Using certutil
to Create a CSR With User-defined Extensions
certutil
utility.
- 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/
- Create the CSR with user-defined Key Usage extension as well as user-defined Extended Key Usage extension and store it in the
/user_or_entity_database_directory/request.csr
file:$ certutil -d . -R -k rsa -g 1024 -s "CN=subject_name" --keyUsage keyEncipherment,dataEncipherment,critical --extKeyUsage timeStamp,msTrustListSign,critical -a -o /user_or_entity_database_directory/request.csr
Enter the required NSS database password when prompted.For further details about the parameters, see the certutil(1) man page. - Optionally, verify that the CSR file is correct:
$ cat /user_or_entity_database_directory/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. - For the next steps, see Section 5.3.1, “The CMC Enrollment Process”, but skip the step about creating the certificate request.
Note
Remove the header information from the CSR.
5.2.2. Creating a CSR Using PKCS10Client
PKCS10Client
utility to create a CSR.
PKCS10Client
, see:
- The PKCS10Client(1) man page
- The output of the
PKCS10Client --help
command
5.2.2.1. Using PKCS10Client
to Create a CSR
PKCS10Client
utility to create an Elliptic Curve (EC) key pair and CSR:
- 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/
- Create the CSR and store it in the
/user_or_entity_database_directory/example.csr
file:$ PKCS10Client -d . -p NSS_password -a ec -c nistp256 -o /user_or_entity_database_directory/example.csr -n "CN=subject_name"
For further details about the parameters, see the PKCS10Client(1) man page. - Optionally, verify that the CSR is correct:
$ cat /user_or_entity_database_directory/example.csr -----BEGIN CERTIFICATE REQUEST----- MIICzzCCAbcCAQAwgYkx ... -----END CERTIFICATE REQUEST-----
5.2.2.2. Using PKCS10Client
to Create a CSR for SharedSecret-based CMC
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.
- 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/
- Create the CSR and store it in the
/user_or_entity_database_directory/example.csr
file:$ PKCS10Client -d . -p NSS_password -o /user_or_entity_database_directory/example.csr -y true -n "CN=subject_name"
For further details about the parameters, see the PKCS10Client(1) man page. - Optionally, verify that the CSR is correct:
$ cat /user_or_entity_database_directory/example.csr -----BEGIN CERTIFICATE REQUEST----- MIICzzCCAbcCAQAwgYkx ... -----END CERTIFICATE REQUEST-----
5.2.3. Creating a CSR Using CRMFPopClient
CRMFPopClient
utility to create a CSR.
CRMFPopClient
, see the CRMFPopClient(1) man page.
5.2.3.1. Using CRMFPopClient
to Create a CSR with Key Archival
CRMFPopClient
utility to create an RSA key pair and a CSR with the key archival option:
- 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/
- Retrieve the KRA transport certificate:
$ pki 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 A lgorithm: 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
- Export the KRA transport certificate:
$ pki ca-cert-show 0x7 --output kra.transport
- Create the CSR and store it in the
/user_or_entity_database_directory/example.csr
file:$ CRMFPopClient -d . -p password -n "cn=subject_name" -q POP_SUCCESS -b kra.transport -w "AES/CBC/PKCS5Padding" -v -o /user_or_entity_database_directory/example.csr
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(1) man page. - Optionally, verify that the CSR is correct:
$ cat /user_or_entity_database_directory/example.csr -----BEGIN CERTIFICATE REQUEST----- MIICzzCCAbcCAQAwgYkx ... -----END CERTIFICATE REQUEST-----
5.2.3.2. Using CRMFPopClient
to Create a CSR for SharedSecret-based CMC
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.
- 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/
- Retrieve the KRA transport certificate:
$ pki 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 A lgorithm: 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
- Export the KRA transport certificate:
$ pki ca-cert-show 0x7 --output kra.transport
- Create the CSR and store it in the
/user_or_entity_database_directory/example.csr
file:$ CRMFPopClient -d . -p password -n "cn=subject_name" -q POP_SUCCESS -b kra.transport -w "AES/CBC/PKCS5Padding" -y -v -o /user_or_entity_database_directory/example.csr
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 theCRMFPopClient --help
command. - Optionally, verify that the CSR is correct:
$ cat /user_or_entity_database_directory/example.csr -----BEGIN CERTIFICATE REQUEST----- MIICzzCCAbcCAQAwgYkx ... -----END CERTIFICATE REQUEST-----
5.3. Requesting and Receiving Certificates Using CMC
- 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
5.3.1. The CMC Enrollment Process
- 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 - 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 CImportant
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
- 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
For further details, see the CMCRequest(1) man page. - Create the CMC request:
$ CMCRequest /home/user_name/cmc-request.cfg
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:# 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
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
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 theCMCAuth
authentication plug-in. Whereas in user-initiated enrollments, the profile must use theCMCUserSignedAuth
plug-in. For further details, see Section 8.1.2, “CMC Authentication Plug-ins”. - Submit the CMC request to the CA:
$ HttpClient /home/user_name/cmc-submit.cfg
- 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
5.3.2. Practical CMC Enrollment Scenarios
5.3.2.1. Obtaining System and Server Certificates
- 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 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
- For a KRA transport certificate:
servlet=/ca/ee/ca/profileSubmitCMCFull?profileId=caCMCkraTransportCert
- For a OCSP signing certificate:
servlet=/ca/ee/ca/profileSubmitCMCFull?profileId=caCMCocspCert
- For a 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
- 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
- An agent signs the CMC request. See Section 5.3.2.2.1, “Signing a CMC Request with an Agent Certificate”.
- Certificate enrollment is authenticated by using a Shared Secret. See Section 5.3.2.2.2, “Authenticating for Certificate Enrollment Using a Shared Secret”.
5.3.2.2.1. Signing a CMC Request with an Agent Certificate
5.3.2.3. Obtaining an Encryption-only Certificate for a User
Note
- 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.3.2.3.1. Example on Obtaining an Encryption-only certificate with Key Archival
Note
-q POP_SUCCESS
option instead of -q POP_NONE
to the CRMFPopClient
utility for a single-trip issuance.
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”.
- Search for the KRA transport certificate. For example:
$ pki cert-find --name KRA_transport_certificate_subject_CN
- 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
- 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/
- 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
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:#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
- Create the CMC request:
$ CMCRequest /home/user_name/cmc.cfg
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:#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
- Submit the CMC request to the CA:
$ HttpClient /home/user_name/cmc-submit.cfg
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
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
- 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
- Create the
DecryptPOP
CMC request:$ CMCRequest /home/user_name/cmc.DecryptedPOP.cfg
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:#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
- Submit the
DecryptedPOP
CMC request to the CA:$ HttpClient /home/user_name/decrypted_POP_cmc-submit.cfg
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
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
5.4. Renewing Certificates
CMCUserSignedAuth
authentication plug-in, and to renew with agent approval, use profiles that require the CMCAuth
authentication plug-in. For further details about these plug-ins and in which profiles they are enabled by default, see Section 8.1.2, “CMC Authentication Plug-ins”.
5.4.1. Renewal Using the Same Key
Note
uniqueKeyConstraint
entry with the params.allowSameKeyRenewal
parameter set to True
as described in Section 3.4.1, “About Renewal” and Section 3.4.1.1.1, “Renewing Using the Same Key”.
5.4.2. Renewal Using a New Key
subjectDN
attribute as the signing certificate.
5.5. Tracing Issued Certificate to CSR, and CSR to Issued Certificate
- Access the
https://host_name:port/ca/agent/ca
. - Click Search for Requests
- Select and fill in Request ID Range (for example
12
for Lowest Request ID and12
for Highest Request ID. - Select Request Type and choose enrollment type.
- Select Request Status and choose completed status
- Make sure everything else is unselected.
- Click.
- Click on the request number. You see the certificate in clear text at this point.
- To display the CSR and certificate linking, right-click and select This Frame and View Frame Source.
- Search for
inputList.inputName="Certificate Request";
. The request is theinputList.inputVal
below that. - Search for
outputList.outputSyntax="pretty_print";
. The certificate is theoutputList.outputVal
below that.
- Access the
https://host_name:port/ca/agent/ca
. - Click Find.
- Click Details.
- You see the certificate in clear text, along with a Request ID link. Click on the link to open the Request page.
- To display the certificate and CSR linking:
- Search for
inputList.inputName="Certificate Request";
. The request is theinputList.inputVal
below that. - Search for
outputList.outputSyntax="pretty_print";
. The certificate is theoutputList.outputVal
below that.
Chapter 6. Revoking Certificates and Issuing CRLs
6.1. About Revoking Certificates
- Revoke the certificate if a revocation request is received by the CA and approved.
- Make the revoked certificate status available to parties or applications that need to verify its validity status.
Note
6.1.1. CRL Issuing Points
6.1.2. Delta CRLs
DeltaCRLIndicator
extension.
6.1.3. Publishing CRLs
6.2. Revoking Certificates
6.2.1. Performing a CMC Revocation
subjectDN
attribute. Then the user can send the signed request to the Certificate Manager.
CMCRequest
. For details, see Section 6.2.1.1, “Revoking a Certificate UsingCMCRequest
”.CMCRevoke
. For details, see Section 6.2.1.2, “Revoking a Certificate UsingCMCRevoke
”.
Important
CMCRequest
utility to generate CMC revocation requests, because it provides more options than CMCRevoke
.
6.2.1.1. Revoking a Certificate Using CMCRequest
CMCRequest
:
- Create a configuration file for the CMC revocation request, such as
/home/user_name/cmc-request.cfg
, with the following content:#numRequests: Total number of PKCS10 requests or CRMF requests. numRequests=1 #output: full path for the CMC request in binary format output=/home/user_name/cmc.revoke.userSigned.req #tokenname: name of token where user signing cert can be found #(default is internal) tokenname=internal #nickname: nickname for user signing certificate which will be used #to sign the CMC full request. nickname=signer_user_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 user signing #certificate and keys password=myPass #format: request format, either pkcs10 or crmf. format=pkcs10 ## revocation parameters revRequest.enable=true revRequest.serial=45 revRequest.reason=unspecified revRequest.comment=user test revocation revRequest.issuer=issuer revRequest.sharedSecret=shared_secret
- Create the CMC request:
# CMCRequest /home/user_name/cmc-request.cfg
If the command succeeds, theCMCRequest
utility stores the CMC request in the file specified in theoutput
parameter in the request configuration file. - Create a configuration file, such as
/home/user_name/cmc-submit.cfg
, which you use in a later step to submit the CMC revocation 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.revoke.userSigned.req #output: full path for the response in binary format output=/home/user_name/cmc.revoke.userSigned.resp #tokenname: name of token where TLS client authentication certificate #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=signer_user_certificate
Important
If the CMC revocation request is signed, set thesecure
andclientmode
parameters totrue
and, additionally, fill thenickname
parameter. - Depending on who signed the request, the
servlet
parameter in the configuration file forHttpClient
must be set accordingly:- If an agent signed the request, set:
servlet=/ca/ee/ca/profileSubmitCMCFull
- If a user signed the request, set:
servlet=/ca/ee/ca/profileSubmitUserSignedCMCFull
- Submit the CMC request:
# HttpClient /home/user_name/cmc-submit.cfg
CMCRequest
, see the CMCRequest(1) man page.
6.2.1.2. Revoking a Certificate Using CMCRevoke
CMCRevoke
, is used to sign a revocation request with an agent's certificate. This utility simply passes the required information — certificate serial number, issuer name, and revocation reason — to identify the certificate to revoke, and then the require information to identify the CA agent performing the revocation (certificate nickname and the database with the certificate).
Important
CMCRevoke
requires that the CA administrator followed the instructions specified in the Enabling CMCRevoke for the Web User Interface section in the Red Hat Certificate System 9 Planning, Installation and Deployment Guide (Common Criteria Edition) during the installation.
CMCRevoke
utility):
0
— unspecified1
— the key was compromised2
— the CA key was compromised3
— the employee's affiliation changed4
— the certificate has been superseded5
— cessation of operation6
— the certificate is on hold
6.2.1.2.1. Testing CMCRevoke
- Create a CMC revocation request for an existing certificate.
CMCRevoke -d/path/to/agent-cert-db -nnickname -iissuerName -sserialName -mreason -ccomment
For example, if the directory containing the agent certificate is~jsmith/.mozilla/firefox/
, the nickname of the certificate isAgentCert
, and the serial number of the certificate is22
, the command is as shown:CMCRevoke -d"~jsmith/.mozilla/firefox/" -n"ManagerAgentCert" -i"cn=agentAuthMgr" -s22 -m0 -c"test comment"
Note
Surround values that include spaces in quotation marks.Important
Do not have a space between the argument and its value. For example, giving a serial number of 26 is-s26
, not-s 26
. - Open the end-entities page.
http
s
://server.example.com:8443/ca/ee/ca
- Select the Revocation tab.
- Select the CMC Revoke link on the menu.
- Paste the output from the
CMCRevoke
into the text area. - Remove
-----BEGIN NEW CERTIFICATE REQUEST-----
and----END NEW CERTIFICATE REQUEST-----
from the pasted content. - Click.
- The returned page should confirm that correct certificate has been revoked.
6.2.2. Performing Revocation as an Agent from the Web UI
6.2.2.1. Listing Certificates
- Open the Certificate Manager agent services page.
- Click List Certificates.
Figure 6.1. List Certificates
- To find a certificate with a specific serial number, enter the serial number in both the upper limit and lower limit fields of the List Certificates form, in either decimal or hexadecimal form. Use
0x
to indicate the beginning of a hexadecimal number; for example,0x00000006
. Serial numbers are displayed in hexadecimal form in the Search Results and Details pages. - To find all certificates within a range of serial numbers, enter the upper and lower limits of the serial number range in decimal or hexadecimal form.
Leaving either the lower limit or upper limit field blank displays the certificate with the specified number, plus all certificates before or after it in sequence. - To limit the returned list to valid certificates, select the check boxes labeled with filtering methods. It is possible to include revoked certificates, to include expired certificates or certificates that are not yet valid, or to display only valid certificates.
- Enter the maximum number of certificates matching the criteria that should be returned in the results page.When any number is entered, the first certificates up to that number matching the criteria are displayed.
- Click.The Certificate System displays a list of the certificates that match the search criteria. Select a certificate in the list to examine it in more detail or perform various operations on it. For more information, refer to Section 6.2.2.3, “Examining Certificate Details”.
6.2.2.2. Searching for Certificates (Advanced)
- Open the Certificate Manager agent services page. The agent must submit the proper client certificate to access this page.
- Click Search for Certificates to display the Search for Certificates form to specify search criteria.
- To search by particular criteria, use one or more of the sections of the Search for Certificates form. To use a section, select the check box, then fill in any necessary information.
- Serial Number Range. Finds a certificate with a specific serial number or lists all certificates within a range of serial numbers.
- To find a certificate with a specific serial number, enter the serial number in both the upper limit and lower limit fields in either decimal or hexadecimal. Use
0x
to indicate the beginning of a hexadecimal number, such as0x2A
. Serial numbers are displayed in hexadecimal form in the Search Results and Details pages. - To find all certificates within a range of serial numbers, enter the upper and lower limits of the serial number range in decimal or hexadecimal. Leaving either the lower limit or upper limit field blank returns all certificates before or after the number specified.
- Status. Selects certificates by their status. A certificate has one of the following status codes:
- Valid. A valid certificate has been issued, its validity period has begun but not ended, and it has not been revoked.
- Invalid. An invalid certificate has been issued, but its validity period has not yet begun.
- Revoked. The certificate has been revoked.
- Expired. An expired certificate has passed the end of its validity period.
- Revoked and Expired. The certificate has passed its validity period and been revoked.
- Subject Name. Lists certificates belonging to a particular owner; it is possible to use wildcards in this field.
Note
Certificate System certificate request forms support all UTF-8 characters for the common name, organizational unit, and requester name fields. The common name and organization unit fields are included in the subject name of the certificate. This means that the searches for subject names support UTF-8 characters.This support does not include supporting internationalized domain names. - Revocation Information. Lists certificates that have been revoked during a particular period, by a particular agent, or for a particular reason. For example, an agent can list all certificates revoked between July 2005 and April 2006 or all certificates revoked by the agent with the username
admin
.- To list certificates revoked within a time period, select the day, month, and year from the drop-down lists to identify the beginning and end of the period.
- To list certificates revoked by a particular agent, enter the name of the agent; it is possible to use wildcards in this field.
- To list certificates revoked for a specific reason, select the revocation reasons from the list.
- Issuing Information. Lists certificates that have been issued during a particular period or by a particular agent. For example, an agent can list all certificates issued between July 2005 and April 2006 or all certificates issued by the agent with the username
jsmith
.- To list certificates issued within a time period, select the day, month, and year from the drop-down lists to identify the beginning and end of the period.
- To list certificates issued by a particular agent, enter the name of the agent; it is possible to use wildcards in this field.
- To list certificates enrolled through a specific profile, enter the name of the profile.
- Dates of Validity. List certificates that become effective or expire during a particular period. For example, an agent can list all certificates that became valid on June 1, 2003, or that expired between January 1, 2006, and June 1, 2006.It is also possible to list certificates that have a validity period of a certain length of time, such as all certificates that are valid for less than one month.
- To list certificates that become effective or expire within a time period, select the day, month, and year from the drop-down lists to identify the beginning and end of the period.
- To list certificates that have a validity period of a certain length in time, selector from the drop-down list, enter a number, and select a time unit from the drop-down list: days, weeks, months, or years.
- Basic Constraints. Shows CA certificates that are based on the Basic Constraints extension.
- Type. Lists certain types of certificates, such as all certificates for subordinate CAs. This search works only for certificates containing the Netscape Certificate Type extension, which stores type information. For each type, choose from the drop-down list to find certificates where that type is , , or .
- To find a certificate with a specific subject name, use the Subject Name section. Select the check box, then enter the subject name criteria. Enter values for the included search criteria and leave the others blank.The standard tags or components are as follows:
- Email address. Narrows the search by email address.
- Common name. Finds certificates associated with a specific person or server.
- UserID. Searches certificates by the user ID for the person to whom the certificate belongs.
- Organization unit. Narrows the search to a specific division, department, or unit within an organization.
- Organization. Narrows the search by organization.
- Locality. Narrows the search by locality, such as the city.
- State. Narrows the search by state or province.
- Country. Narrows the search by country; use the two-letter country code, such as
US
.
Note
Certificate System certificate request forms support all UTF-8 characters for the common name and organizational unit fields. The common name and organization unit fields are included in the subject name of the certificate. This means that the searches for subject names or those elements in the subject name support UTF-8 characters.This support does not include supporting internationalized domain names, such as in email addresses. - After entering the field values for the server to match, specify the type of search to perform:
- Exact searches for certificate subject names match the exact components specified and contain none of the components left blank. Wildcards cannot be used in this type of search.
- Partial searches for certificate subject names match the specified components, but the returned certificates may also contain values in components that were left blank. Wildcard patterns can be used in this type of search by using a question mark (
?
) to match an arbitrary single character and an asterisk (*
) to match an arbitrary string of characters.Note
Placing a single asterisk in a search field means that the component must be in the certificate's subject name but may have any value. Leave the field blank if it does not matter if the field is present.
- After entering the search criteria, scroll to the bottom of the form, and enter the number of certificates matching the specified criteria that should be returned.Setting the number of certificates to be returned returns the first certificates found that match the search criteria up to that number. It is also possible to put a time limit on the search in seconds.
- Click.
- The Search Results form appears, showing a list of the certificates that match the search criteria. Select a certificate in the list to examine it in more detail. For more information, refer to Section 6.2.2.3, “Examining Certificate Details”.
6.2.2.3. Examining Certificate Details
- On the agent services page, click List Certificates or Search for Certificates, specify search criteria, and click to display a list of certificates.
- On the Search Results form, select a certificate to examine.If the desired certificate is not shown, scroll to the bottom of the list, specify an additional number of certificates to be returned, and click. The system displays the next certificates up to that number that match the original search criteria.
- After selecting a certificate, click thebutton at the left side of its entry.
- The Certificate page shows the detailed contents of the selected certificate and instructions for installing the certificate in a server or in a web browser.
Figure 6.2. Certificate Details
- The certificate is shown in base-64 encoded form at the bottom of the Certificate page, under the heading Installing this certificate in a server.
6.2.2.4. Revoking Certificates
- The owner of the certificate has changed status and no longer has the right to use the certificate.
- The private key of a certificate owner has been compromised.
6.2.2.4.1. Revoking Certificates
- Open the Certificate Manager agent services page.
- Click.
Note
The search form that appears has the same search criteria sections as the Search for Certificates form. - Specify the search criteria by selecting the check boxes for the sections and filling in the required information.
- Scroll to the bottom of the form, and set the number of matching certificates to display.
- Click.
- The search returns a list of matching certificates. It is possible to revoke one or all certificates in the list.
Note
If the search criteria are very specific and all of the certificates returned are to be revoked, then click thebutton at the bottom of the page. The number shown on the button is the total number of certificates returned by the search. This is usually a larger number than the number of certificates displayed on the current page.Verify that all of the certificates returned by the search should be revoked, not only those displayed on the current page. - Click thebutton next to the certificate to be revoked.
Warning
Whether revoking a single certificate or a list of certificates, be extremely careful that the correct certificate has been selected or that the list contains only certificates which should be revoked. Once a revocation operation has been confirmed, there is no way to undo it. - Select an invalidity date. The invalidity date is the date which it is known or suspected that the user's private key was compromised or that the certificate became invalid. A set of drop down lists allows the agent to select the correct invalidity date.
- Select a reason for the revocation.
- Key compromised
- CA key compromised
- Affiliation changed
- Certificate superseded
- Cessation of operation
- Certificate is on hold
- Enter any additional comment. The comment is included in the revocation request.
Completed
.
6.2.2.4.2. Taking Ceritificates Off Hold
- Search for the on hold certificate, as in Section 6.2.2.2, “Searching for Certificates (Advanced)”. Scroll to the Revocation Information section, and set the Certificate is on hold revocation reason as the search criterion.
- In the results list, click thebutton by the certificate to take off hold.
6.2.2.5. Managing the Certificate Revocation List
6.2.2.5.1. Viewing or Examining CRLs
- Go to the Certificate Manager agent services page.
- Click Display Certificate Revocation List to display the form for viewing the CRL.
- Select the CRL to view. If the administrator has created multiple issuing points, these are listed in thedrop-down list. Otherwise, only the master CRL is shown.
- Choose how to display the CRL by selecting one of the options from themenu. The choices on this menu are as follows:
- Cached CRL. Views the CRL from the cache rather than from the CRL itself. This option displays results faster than viewing the entire CRL.
- Entire CRL. Retrieves and displays the entire CRL.
- CRL header. Retrieves and displays the CRL header only.
- Base 64 Encoded. Retrieves and displays the CRL in base-64 encoded format.
- Delta CRL. Retrieves and displays a delta CRL, which is a subset of the CRL showing only new revocations since the last CRL was published. This option is available only if delta CRL generation is enabled.
- To examine the selected CRL, click.The CRL appears in the browser window. This allows the agent to check whether a particular certificate (by its serial number) appears in the list and to note recent changes such as the total number of certificates revoked since the last update, the total number of certificates taken off hold since the last update, and the total number of certificates that expired since the last update.
6.2.2.5.2. Updating the CRL
- Open the Certificate Manager agent services page.
- Click Update Revocation List to display the form for updating the CRL.
Figure 6.3. Update Certificate Revocation List
- Select the CRL issuing point which will update the CRL. There can be multiple issuing points configured for a single CA.
- Select the algorithm to use to sign the new CRL. Before choosing an algorithm, make sure that any system or network applications that need to read or view this CRL support the algorithm.
- SHA-256 with RSA.
- SHA-384 with RSA.
- SHA-512 with RSA.
Before selecting an algorithm, make sure that the Certificate System has that algorithm enabled. The Certificate System administrator will have that information. - Clickto update the CRL with the latest certificate revocation information.
6.2.3. Performing Revocation on Own Certificate as a User Using the Web UI
6.2.3.1. Revoking Your User Certificate
- Click the Revocation tab.
- Click the User Certificate link.
- Select the reason why the certificate is being revoked, and click.
- Select the certificates to revoke from the list.
6.2.3.2. Checking Whether a Certificate Is Revoked
- Click the Retrieval tab.
- Click the Import Certificate Revocation List link.
- Select the radio button by Check whether the following certificate is included in CRL cache or Check whether the following certificate is listed by CRL, and enter the serial number of the certificate.
- Click the Submit button.A message is returned either saying that the certificate is not listed in any CRL or giving the information for the CRL which contains the certificate.
6.2.3.3. Downloading and Importing CRLs
- Click the Retrieval tab.
- Click the Import Certificate Revocation List link.
- Select the radio button to view, download, or import the CRL.
- To import the CRL into the browser or download and save it, select the appropriate radio button. There are two options: to download/import the full CRL or the delta CRL. The delta CRL only imports/downloads the list of certificates which have been revoked since the last time the CRL was generated.
- To view the CRL, select Display the CRL information and select which CRL subset (called an issuing point) to view. This shows the CRL information, including the number of certificates included in it.
- Click thebutton.
- Save the file or approve the import operation.
6.3. Issuing CRLs
- The Certificate Manager uses its OCSP signing key to sign CRLs. To use a separate signing key pair for CRLs, set up a CRL signing key and change the Certificate Manager configuration to use this key to sign CRLs. See 9.2.3.11. Setting a CA to Use a Different Certificate to Sign CRLs in Red Hat Certificate System's Planning, Installation, and Deployment Guide for more information.
- Set up CRL issuing points. An issuing point is already set up and enabled for a master CRL.
Figure 6.4. Default CRL Issuing Point
Additional issuing points for the CRLs can be created. See Section 6.3.1, “Configuring Issuing Points” for details.There are five types of CRLs the issuing points can create, depending on the options set when configuring the issuing point to define what the CRL will list:- Master CRL contains the list of revoked certificates from the entire CA.
- ARL is an Authority Revocation List containing only revoked CA certificates.
- CRL with expired certificates includes revoked certificates that have expired in the CRL.
- CRL from certificate profiles determines the revoked certificates to include based on the profiles used to create the certificates originally.
- CRLs by reason code determines the revoked certificates to include based on the revocation reason code.
- Configure the CRLs for each issuing point. See Section 6.3.2, “Configuring CRLs for Each Issuing Point” for details.
- Set up the CRL extensions which are configured for the issuing point. See Section 6.3.3, “Setting CRL Extensions” for details.
- Set up the delta CRL for an issuing point by enabling extensions for that issuing point,
DeltaCRLIndicator
orCRLNumber
. - Set up the
CRLDistributionPoint
extension to include information about the issuing point. - Set up publishing CRLs to files, an LDAP directory, or an OCSP responder. See Chapter 7, Publishing Certificates and CRLs for details about setting up publishing.
6.3.1. Configuring Issuing Points
- Open the Certificate System Console.
pkiconsole https://server.example.com:8443/ca
- In the Configuration tab, expand Certificate Manager from the left navigation menu. Then select CRL Issuing Points.
- To edit an issuing point, select the issuing point, and click. The only parameters which can be edited are the name of the issuing point and whether the issuing point is enabled or disabled.To add an issuing point, click. The CRL Issuing Point Editor window opens.
Figure 6.5. CRL Issuing Point Editor
Note
If some fields do not appear large enough to read the content, expand the window by dragging one of the corners.Fill in the following fields:- Enable. Enables the issuing point if selected; deselect to disable.
- CRL Issuing Point name. Gives the name for the issuing point; spaces are not allowed.
- Description. Describes the issuing point.
- Click.
6.3.2. Configuring CRLs for Each Issuing Point
- Open the CA console.
pkiconsole https://server.example.com:8443/ca
- In the navigation tree, select Certificate Manager, and then select CRL Issuing Points.
- Select the issuing point name below the Issuing Points entry.
- Configure how and how often the CRLs are updated by supplying information in the Update tab for the issuing point. This tab has two sections, Update Schema and Update Frequency.
- The Update Schema section has the following options:
- Enable CRL generation. This checkbox sets whether CRLs are generated for that issuing point.
- Generate full CRL every # delta(s). This field sets how frequently CRLs are created in relation to the number of changes.
- Extend next update time in full CRLs. This provides an option to set the
nextUpdate
field in the generated CRLs. ThenextUpdate
parameter shows the date when the next CRL is issued, regardless of whether it is a full or delta CRL. When using a combination of full and delta CRLs, enablingExtend next update time in full CRLs
will make thenextUpdate
parameter in a full CRL show when the next full CRL will be issued. Otherwise, thenextUpdate
parameter in the full CRL will show when the next delta CRL will be issued, since the delta will be the next CRL to be issued.
- The Update Frequency section sets the different intervals when the CRLs are generated and issued to the directory.
- Every time a certificate is revoked or released from hold. This sets the Certificate Manager to generate the CRL every time it revokes a certificate. The Certificate Manager attempts to issue the CRL to the configured directory whenever it is generated. Generating a CRL can be time consuming if the CRL is large. Configuring the Certificate Manager to generate CRLs every time a certificate is revoked may engage the server for a considerable amount of time; during this time, the server will not be able to update the directory with any changes it receives.This setting is not recommended for a standard installation. This option should be selected to test revocation immediately, such as testing whether the server issues the CRL to a flat file.
- Update the CRL at. This field sets a daily time when the CRL should be updated. To specify multiple times, enter a comma-separate list of times, such as
01:50,04:55,06:55
. To enter a schedule for multiple days, enter a comma-separated list to set the times within the same day, and then a semicolon separated list to identify times for different days. For example, this sets revocation on Day 1 of the cycle at 1:50am, 4:55am, and 6:55am and then Day 2 at 2am, 5am, and 5pm:01:50,04:55,06:55;02:00,05:00,17:00
- Next update grace period. If the Certificate Manager updates the CRL at a specific frequency, the server can be configured to have a grace period to the next update time to allow time to create the CRL and issue it. For example, if the server is configured to update the CRL every 20 minutes with a grace period of 2 minutes, and if the CRL is updated at 16:00, the CRL is updated again at 16:18.
Important
Due to a known issue, when currently setting full and delta Certificate Revocation List schedules, theUpdate CRL every time a certificate is revoked or released from hold
option also requires you to fill out the twograce period
settings. Thus, in order to select this option you need to first select theUpdate CRL every
option and enter a number for theNext update grace period # minutes
box. - The Cache tab sets whether caching is enabled and the cache frequency.
Figure 6.6. CRL Cache Tab
- Enable CRL cache. This checkbox enables the cache, which is used to create delta CRLs. If the cache is disabled, delta CRLs will not be created. For more information about the cache, see Section 6.1, “About Revoking Certificates”.
- Update cache every. This field sets how frequently the cache is written to the internal database. Set to
0
to have the cache written to the database every time a certificate is revoked. - Enable cache recovery. This checkbox allows the cache to be restored.
- Enable CRL cache testing. This checkbox enables CRL performance testing for specific CRL issuing points. CRLs generated with this option should not be used in deployed CAs, as CRLs issued for testing purposed contain data generated solely for the purpose of performance testing.
- The Format tab sets the formatting and contents of the CRLs that are created. There are two sections, CRL Format and CRL Contents.
Figure 6.7. CRL Format Tab
- The CRL Format section has two options:
- Revocation list signing algorithm is a drop down list of allowed ciphers to encrypt the CRL.
- Allow extensions for CRL v2 is a checkbox which enabled CRL v2 extensions for the issuing point. If this is enabled, set the required CRL extensions described in Section 6.3.3, “Setting CRL Extensions”.
Note
Extensions must be turned on to create delta CRLs. - The CRL Contents section has three checkboxes which set what types of certificates to include in the CRL:
- Include expired certificates. This includes revoked certificates that have expired. If this is enabled, information about revoked certificates remains in the CRL after the certificate expires. If this is not enabled, information about revoked certificates is removed when the certificate expires.
- CA certificates only. This includes only CA certificates in the CRL. Selecting this option creates an Authority Revocation List (ARL), which lists only revoked CA certificates.
- Certificates issued according to profiles. This only includes certificates that were issued according to the listed profiles; to specify multiple profiles, enter a comma-separated list.
- Click.
- Extensions are allowed for this issuing point and can be configured. See Section 6.3.3, “Setting CRL Extensions” for details.
6.3.3. Setting CRL Extensions
Note
CRLReason
, InvalidityDate
, and CRLNumber
. Other extensions are available but are disabled by default. These can be enabled and modified. For more information about the available CRL extensions, see Section B.4.2, “Standard X.509 v3 CRL Extensions Reference”.
- Open the CA console.
pkiconsole https://server.example.com:8443/ca
- In the navigation tree, select Certificate Manager, and then select CRL Issuing Points.
- Select the issuing point name below the Issuing Points entry, and select the CRL Extension entry below the issuing point.The right pane shows the CRL Extensions Management tab, which lists configured extensions.
Figure 6.8. CRL Extensions
- To modify a rule, select it, and click.
- Most extensions have two options, enabling them and setting whether they are critical. Some require more information. Supply all required values. See Section B.4.2, “Standard X.509 v3 CRL Extensions Reference” for complete information about each extension and the parameters for those extensions.
- Click.
- Clickto see the updated status of all the rules.
6.3.4. Generating CRLs from Cache
Note
enableCRLCache
parameter in most environments. However, the Enable CRL cache testing
parameter should not be enabled in a production environment.
6.3.4.1. Configuring CRL Generation from Cache in the Console
- Open the console.
pkiconsole https://server.example.com:8443/ca
- In the Configuration tab, expand the Certificate Manager folder and the CRL Issuing Points subfolder.
- Select the MasterCRL node.
- Select Enable CRL cache.
- Save the changes.
6.4. Setting Full and Delta CRL Schedules
Interval 1, 2, 3, 4, 5, 6, 7 ... Full CRL 1 4 7 ... Delta CRL 1, 2, 3, 4, 5, 6, 7 ...
Note
6.4.1. Configuring CRL Update Intervals in the Console
- Open the console.
pkiconsole https://server.example.com:8443/ca
- In the Configuration tab, expand the Certificate Manager folder and the CRL Issuing Points subfolder.
- Select the MasterCRL node.
- Enter the required interval in the Generate full CRL every # delta(s) field.
- Set the update frequency, either by specifying the occasion of a certificate revocation, a cyclical interval or set times for the updates to occur:
- Select the Update CRL every time a certificate is revoked or released from hold checkbox. The Update CRL every time a certificate is revoked or released from hold option also requires you to fill out the two Grace period settings. This is a known issue, and the bug is being tracked in Red Hat Bugzilla.
- Select the Update CRL every time a certificate is revoked or released from hold checkbox.
- Select the Update CRL at checkbox and enter specific times separated by commas, such as
01:50,04:55,06:55
. - Select Update CRL every checkbox and enter the required interval, such as
240
.
- Save the changes.
Important
Note
6.4.2. Configuring CRL Generation Schedules over Multiple Days
ca.crl.MasterCRL.dailyUpdates=01:00,03:00,18:00;02:00,05:00,17:00
Note
ca.crl.MasterCRL.dailyUpdates=01:00,03:00,18:00,*23:00;02:00,05:00,21:00,*23:30
Note
6.5. Using the Online Certificate Status Protocol (OCSP) Responder
6.5.1. Setting up the OCSP Responder
Note
- Configure the CRLs for every CA that will publish to an OCSP responder.
- Enable publishing, set up a publisher, and set publishing rules in every CA that the OCSP service will handle (Chapter 7, Publishing Certificates and CRLs). This is not necessary if the Certificate Managers publish to an LDAP directory and the Online Certificated Status Manager is set up to read from that directory.
- The certificate profiles must be configured to include the Authority Information Access extension, pointing to the location at which the Certificate Manager listens for OCSP service requests (Section 6.5.4, “Enabling the Certificate Manager's Internal OCSP Service”).
- Configure the OCSP Responder.
- Configure the Revocation Info store (Section 6.5.2.2, “Configure the Revocation Info Stores: Internal Database” and Section 6.5.2.3, “Configure the Revocation Info Stores: LDAP Directory”).
- Identify every publishing Certificate Manager to the OCSP responder (Section 6.5.2, “Identifying the CA to the OCSP Responder”).
- If necessary, configure the trust settings for the CA which signed the OCSP signing certificate (Section 14.5, “Changing the Trust Settings of a CA Certificate”).
- Restart both subsystems after configuring them.
- Verify that the CA is properly connected to the OCSP responder (Section 6.5.2.1, “Verify Certificate Manager and Online Certificate Status Manager Connection”).
6.5.2. Identifying the CA to the OCSP Responder
Note
- Get the Certificate Manager's base-64 CA signing certificate from the end-entities page of the CA.
- Open the Online Certificate Status Manager agent page. The URL has the format
https://
hostname:SSLport/ocsp/agent/ocsp
. - In the left frame, click.
- In the form, paste the encoded CA signing certificate inside the text area labeled Base 64 encoded certificate (including the header and footer).
- To verify that the certificate is added successfully, in the left frame, click List Certificate Authorities.
6.5.2.1. Verify Certificate Manager and Online Certificate Status Manager Connection
6.5.2.2. Configure the Revocation Info Stores: Internal Database
- Open the Online Certificate Status Manager Console.
pkiconsole https://server.example.com:8443/ocsp
- In the Configuration tab, select Online Certificate Status Manager, and then select Revocation Info Stores.The right pane shows the two repositories the Online Certificate Status Manager can use; by default, it uses the CRL in its internal database.
- Select the
defStore
, and click . - Edit the
defStore
values.- notFoundAsGood. Sets the OCSP service to return an OCSP response of GOOD if the certificate in question cannot be found in any of the CRLs. If this is not selected, the response is UNKNOWN, which, when encountered by a client, results in an error message.
- byName. The OCSP Responder only supports the basic response type, which includes the ID of the OCSP Responder making the response. The ResponderID field within the basic response type is determined by the value of the
ocsp.store.defStore.byName
parameter. IfbyName
parameter is true or is missing, the OCSP authority signing certificate subject name is used as the ResponderID field of the OCSP response. IfbyName
parameter is false, the OCSP authority signing certificate key hash will be the ResponderID field of the OCSP response. - includeNextUpdate. Includes the timestamp of the next CRL update time.
6.5.2.3. Configure the Revocation Info Stores: LDAP Directory
Important
ldapStore
method is enabled, the OCSP user interface does not check the certificate status.
- Open the Online Certificate Status Manager Console.
pkiconsole https://server.example.com:8443/ocsp
- In the Configuration tab, select Online Certificate Status Manager, and then select Revocation Info Stores.The right pane shows the two repositories the Online Certificate Status Manager can use; by default, it uses the CRL in its internal database.
- To use the CRLs in LDAP directories, clickto enable the
ldapStore
option. - Select
ldapStore
, and click . - Set the
ldapStore
parameters.- numConns. The total number of LDAP directories the OCSP service should check. By default, this is set to 0. Setting this value shows the corresponding number of host, port, baseDN, and refreshInSec fields.
- host. The fully-qualified DNS hostname of the LDAP directory.
- port. The non-TLS port of the LDAP directory.
- baseDN. The DN to start searching for the CRL. For example,
O=example.com
. - refreshInSec. How often the connection is refreshed. The default is 86400 seconds (daily).
- caCertAttr. Leave the default value,
cACertificate;binary
, as it is. It is the attribute to which the Certificate Manager publishes its CA signing certificate. - crlAttr. Leave the default value,
certificateRevocationList;binary
, as it is. It is the attribute to which the Certificate Manager publishes CRLs. - notFoundAsGood. Sets the OCSP service to return an OCSP response of GOOD if the certificate in question cannot be found in any of the CRLs. If this is not selected, the response is UNKNOWN, which, when encountered by a client, results in an error message.
- byName. The OCSP Responder only supports the basic response type, which includes the ID of the OCSP Responder making the response. The ResponderID field within the basic response type is determined by the value of the
ocsp.store.defStore.byName
parameter. IfbyName
parameter is true or is missing, the OCSP authority signing certificate subject name is used as the ResponderID field of the OCSP response. IfbyName
parameter is false, the OCSP authority signing certificate key hash will be the ResponderID field of the OCSP response. - includeNextUpdate. The Online Certificate Status Manager can include the timestamp of the next CRL update time.
6.5.2.4. Testing the OCSP Service Setup
- Turn on revocation checking in the browser or client.
- Request a certificate from the CA that has been enabled for OCSP services.
- Approve the request.
- Download the certificate to the browser or client.
- Make sure the CA is trusted by the browser or client.
- Check the status of Certificate Manager's internal OCSP service.Open the CA agent services page, and select the OCSP Services link.
- Test the independent Online Certificate Status Manager subsystem.Open the Online Certificate Status Manager agent services page, and click the List Certificate Authorities link.The page should show information about the Certificate Manager configured to publish CRLs to the Online Certificate Status Manager. The page also summarizes the Online Certificate Status Manager's activity since it was last started.
- Revoke the certificate.
- Verify the certificate in the browser or client. The server should return that the certificate has been revoked.
- Check the Certificate Manager's OCSP-service status again to verify that these things happened:
- The browser sent an OCSP query to the Certificate Manager.
- The Certificate Manager sent an OCSP response to the browser.
- The browser used that response to validate the certificate and returned its status, that the certificate could not be verified.
- Check the independent OCSP service subsystem again to verify that these things happened:
- The Certificate Manager published the CRL to the Online Certificate Status Manager.
- The browser sent an OCSP response to the Online Certificate Status Manager.
- The Online Certificate Status Manager sent an OCSP response to the browser.
- The browser used that response to validate the certificate and returned its status, that the certificate could not be verified.
6.5.3. Setting the Response for Bad Serial Numbers
notFoundAsGood
parameter sets how the OCSP handles a certificate with an invalid serial number. This parameter is enabled by default, which means that if a certificate is present with a bad serial number but the certificate is otherwise valid, the OCSP returns a status of GOOD
for the certificate.
notFoundAsGood
setting. In that case, the OCSP returns a status of UNKNOWN
with a certificate with a bad serial number. The client interprets that as an error and can respond accordingly.
- Open the Online Certificate Status Manager Console.
pkiconsole https://server.example.com:8443/ocsp
- In the Configuration tab, select Online Certificate Status Manager, and then select Revocation Info Stores.
- Select the
defStore
, and click . - Edit the
notFoundAsGood
value. Selecting the checkbox means that the OCSP returns a value ofGOOD
even if the serial number on the certificate is bad. Unselecting the checkbox means that the OCSP sends a value ofUNKNOWN
, which the client can intrepret as an error. - Restart the OCSP Manager.
systemctl restart pki-tomcatd-nuxwdog@instance_name.service
6.5.4. Enabling the Certificate Manager's Internal OCSP Service
- Go to the CA's end-entities page. For example:
http
s
://server.example.com:8443/ca/ee/ca
- Find the CA signing certificate.
- Look for the Authority Info Access extension in the certificate, and note the
Location URIName
value, such ashttp
.s
://server.example.com:8443
/ca/ocsp - Update the enrollment profiles to enable the Authority Information Access extension, and set the
Location
parameter to the Certificate Manager's URI. For information on editing the certificate profiles, see Section 3.2, “Setting up Certificate Profiles”. - Restart the CA instance.
systemctl restart pki-tomcatd-nuxwdog@instance_name.service
6.5.5. Submitting OCSP Requests Using the OCSPClient program
]# OCSPClient -h server.example.com -p 8080 -d /etc/pki/pki-tomcat/alias -c "caSigningCert cert-pki-ca" --serial 2 CertID.serialNumber=2 CertStatus=Good
OCSPClient
command can be used with the following command-line options:
Option | Description |
---|---|
-d database | Security database location (default: current directory) |
-h hostname | OCSP server hostname (default: example.com) |
-p port | OCSP server port number (default: 8080) |
-t path | OCSP service path (default: /ocsp/ee/ocsp) |
-c nickname | CA certificate nickname (defaut: CA Signing Certificate) |
-n times | Number of submissions (default: 1) |
--serial serial_number | Serial number of certificate to be checked |
--input input_file | Input file containing DER-encoded OCSP request |
--output output_file | Output file to store DER-encoded OCSP response |
-v, --verbose | Run in verbose mode |
--help | Show help message |
6.5.6. Submitting OCSP Requests Using the GET Method
- Generate an OCSP request for the certificate the status of which is being queried. For example:
]# openssl ocsp -CAfile ca.pem -issuer issuer.pem -serial serial_number -reqout - | base64 MEIwQDA+MDwwOjAJBgUrDgMCGgUABBT4cyABkyiCIhU4JpmIBewdDnn8ZgQUbyBZ44kgy35o7xW5BMzM8FTvyTwCAQE=
- Paste the URL in the address bar of a web browser to return the status information. The browser must be able to handle OCSP requests.
https://server.example.com:8443/ocsp/ee/ocsp/MEIwQDA+MDwwOjAJBgUrDgMCGgUABBT4cyABkyiCIhU4JpmIBewdDnn8ZgQUbyBZ44kgy35o7xW5BMzM8FTvyTwCAQE=
- The OCSP Manager responds with the certificate status which the browser can interpret. The possible statuses are GOOD, REVOKED, and UNKNOWN.
curl
to send the request and openssl
to parse the response. For example:
- Generate an OCSP request for the certificate the status of which is being queried. For example:
]# openssl ocsp -CAfile ca.pem -issuer issuer.pem -serial serial_number -reqout - | base64 MEIwQDA+MDwwOjAJBgUrDgMCGgUABBT4cyABkyiCIhU4JpmIBewdDnn8ZgQUbyBZ44kgy35o7xW5BMzM8FTvyTwCAQE=
- Connect to the OCSP Manager using
curl
to send the OCSP request.curl https://server.example.com:8443/ocsp/ee/ocsp/MEIwQDA+MDwwOjAJBgUrDgMCGgUABBT4cyABkyiCIhU4JpmIBewdDnn8ZgQUbyBZ44kgy35o7xW5BMzM8FTvyTwCAQE= > ocspresp.der
- Parse the response using
openssl
:openssl ocsp -respin ocspresp.der -resp_text
Part III. Additional Configuration to Manage CA Services
Chapter 7. Publishing Certificates and CRLs
Note
- Configure publishing to a file, LDAP directory, or OCSP responder.There can be a single publisher or multiple publishers, depending on how many locations will be used. The locations can be split by certificates and CRLs or narrower definitions, such as certificate type. Rules determine which type to publish and to what location by being associated with the publisher.
- Set rules to determine what certificates are published to the locations. Any rule which a certificate or CRL matches is activated, so the same certificate can be published to a file and to an LDAP directory by matching a file-based rule and matching a directory-based rule.Rules can be set for each object type: CA certificates, CRLs, user certificates, and cross-pair certificates. Disable all rules that will not be used.
- Configure CRLs. CRLs must be configured before they can be published. See Chapter 6, Revoking Certificates and Issuing CRLs.
- Enable publishing after setting up publishers, mappers, and rules. Once publishing is enabled, the server starts publishing immediately. If the publishers, mappers, and rules are not completely configured, publishing may not work correctly or at all.
7.1. About Publishing
Note
CRL
is set as the type.
/etc/CS/certificates
, the certificate is published as a file to that location. If another rule matches all certificates issued to users, and the rule has a publisher that publishes to the LDAP attribute userCertificate;binary
attribute, the certificate is published to the directory specified when LDAP publishing was enabled in this attribute in the user's entry.
7.1.1. Publishers
7.1.2. Mappers
7.1.3. Rules
7.1.4. Publishing to Files
- For each certificate the server issues, it creates a file that contains the certificate in either DER-encoded or base-64 encoded format. Each file is named either
cert-
serial_number.der
orcert-
serial_number.b64
. The serial_number is the serial number of the certificate contained in the file. For example, the filename for a DER-encoded certificate with the serial number1234
iscert-1234.der
. - Every time the server generates a CRL, it creates a file that contains the new CRL in either DER-encoded or base-64 encoded format. Each file is named either issuing_point_name-this_update
.der
or issuing_point_name-this_update.b64
, depending on the format. The issuing_point_name identifies the CRL issuing point which published the CRL, and this_update specifies the value derived from the time-dependent update value for the CRL contained in the file. For example, the filename for a DER-encoded CRL with the valueThis Update: Friday January 28 15:36:00 PST 2021
, isMasterCRL-20210128-153600.der
.
7.1.5. OCSP Publishing
7.1.6. LDAP Publishing
- For each certificate the server issues, it creates a blob that contains the certificate in its DER-encoded format in the specified attribute of the user's entry. The certificate is published as a DER encoded binary blob.
- Every time the server generates a CRL, it creates a blob that contains the new CRL in its DER-encoded format in the specified attribute of the entry for the CA.
7.2. Configuring Publishing to a File
- Log into the Certificate Manager Console.
pkiconsole https://server.example.com:8443/ca
- In the Configuration tab, select Certificate Manager from the navigation tree on the left. Select Publishing, and then Publishers.The Publishers Management tab, which lists configured publisher instances, opens on the right.
- Click Select Publisher Plug-in Implementation window, which lists registered publisher modules.to open the
- Select the
FileBasedPublisher
module, then open the editor window.This is the module that enables the Certificate Manager to publish certificates and CRLs to files. - Configure the information for publishing the certificate:
- The publisher ID, an alphanumeric string with no spaces like
PublishCertsToFile
- The path to the directory in which the Certificate Manager should publish the files. The path can be an absolute path or can be relative to the Certificate System instance directory. For example,
/export/CS/certificates
. - The file type to publish, by selecting the checkboxes for DER-encoded files, base-64 encoded files, or both.
- For CRLs, the format of the timestamp. Published certificates include serial numbers in their file names, while CRLs use timestamps.
- For CRLs, whether to generate a link in the file to go to the latest CRL. If enabled, the link assumes that the name of the CRL issuing point to use with the extension will be supplied in the crlLinkExt field.
- For CRLs, whether to compress (zip) CRLs and the compression level to use.
7.3. Configuring Publishing to an OCSP
7.3.1. Enabling Publishing to an OCSP with Client Authentication
- Log into the Certificate Manager Console.
pkiconsole https://server.example.com:8443/ca
- In the Configuration tab, select Certificate Manager from the navigation tree on the left. Select Publishing, and then Publishers.
- Click Select Publisher Plug-in Implementation window, which lists registered publisher modules.to open the
- Select the
OCSPPublisher
module, then open the editor window. This is the publisher module that enables the Certificate Manager to publish CRLs to the Online Certificate Status Manager.- The publisher ID must be an alphanumeric string with no spaces, like
PublishCertsToOCSP
. - The host can be the fully-qualified domain name, such as
ocspResponder.example.com
, or an IPv4 or IPv6 address. - The default path is the directory to send the CRL to, like
/ocsp/agent/ocsp/addCRL
. - If client authentication is used (enableClientAuth is checked), then the nickname field gives the nickname of the certificate to use for authentication. This certificate must already exist in the OCSP security database; this will usually be the CA subsystem certificate.
- Create a user entry for the CA on the OCSP Manager. The user is used to authenticate to the OCSP when sending a new CRL. There are two things required:
- Name the OCSP user entry after the CA server, like
CA-
hostname-EEport. - Use whatever certificate was specified in the publisher configuration as the user certificate in the OCSP user account. This is usually the CA's subsystem certificate.
Setting up subsystem users is covered in Section 12.3.2.1, “Creating Users”.
7.4. Configuring Publishing to an LDAP Directory
- Configure the Directory Server to which certificates will be published. Certain attributes have to be added to entries and bind identities and authentication methods have to be configured.
- Configure a publisher for each type of object published: CA certificates, cross-pair certificates, CRLs, and user certificates. The publisher declares in which attribute to store the object. The attributes set by default are the X.500 standard attributes for storing each object type. This attribute can be changed in the publisher, but generally, it is not necessary to change the LDAP publishers.
- Set up mappers to enable an entry's DN to be derived from the certificate's subject name. This generally does not need set for CA certificates, CRLs, and user certificates. There can be more than one mapper set for a type of certificate. This can be useful, for example, to publish certificates for two sets of users from different divisions of a company who are located in different parts of the directory tree. A mapper is created for each of the groups to specify a different branch of the tree.For details about setting up mappers, see Section 7.4.3, “Creating Mappers”.
- Create rules to connect publishers to mappers, as described in Section 7.5, “Creating Rules”.
- Enable publishing, as described in Section 7.6, “Enabling Publishing”.
7.4.1. Configuring the LDAP Directory
- Set up the entry for the CA. For the Certificate Manager to publish its CA certificate and CRL, the directory must include an entry for the CA.
Note
When LDAP publishing is configured, the Certificate Manager automatically creates or converts an entry for the CA in the directory. This option is set in both the CA and CRL mapper instances and enabled by default. If the directory restricts the Certificate Manager from creating entries in the directory, turn off this option in those mapper instances, and add an entry for the CA manually in the directory.When adding the CA's entry to the directory, select the entry type based on the DN of the CA:- If the CA's DN begins with the
cn
component, create a newperson
entry for the CA. Selecting a different type of entry may not allow thecn
component to be specified. - If the CA's DN begins with the
ou
component, create a neworganizationalunit
entry for the CA.
The entry does not have to be in thepkiCA
orcertificationAuthority
object class. The Certificate Manager will convert this entry to thepkiCA
orcertificationAuthority
object class automatically by publishing its CA's signing certificate.Note
ThepkiCA
object class is defined in RFC 4523, while thecertificationAuthority
object class is defined in the (obsolete) RFC 2256. Either object class is acceptable, depending on the schema definitions used by the Directory Server. In some situations, both object classes can be used for the same CA entry.For more information on creating directory entries, see the Red Hat Directory Server documentation. - Add the correct schema elements to the CA and user directory entries.For a Certificate Manager to publish certificates and CRLs to a directory, it must be configured with specific attributes and object classes.
Object Type Schema Reason End-entity certificate userCertificate;binary (attribute) This is the attribute to which the Certificate Manager publishes the certificate.This is a multi-valued attribute, and each value is a DER-encoded binary X.509 certificate. The LDAP object class namedinetOrgPerson
allows this attribute. ThestrongAuthenticationUser
object class allows this attribute and can be combined with any other object class to allow certificates to be published to directory entries with other object classes. The Certificate Manager does not automatically add this object class to the schema table of the corresponding Directory Server.If the directory object that it finds does not allow theuserCertificate;binary
attribute, adding or removing the certificate fails.CA certificate caCertificate;binary (attribute) This is the attribute to which the Certificate Manager publishes the certificate.The Certificate Manager publishes its own CA certificate to its own LDAP directory entry when the server starts. The entry corresponds to the Certificate Manager's issuer name.This is a required attribute of thepkiCA
orcertificationAuthority
object class. The Certificate Manager adds this object class to the directory entry for the CA if it can find the CA's directory entry.CRL certificateRevocationList;binary (attribute) This is the attribute to which the Certificate Manager publishes the CRL.The Certificate Manager publishes the CRL to its own LDAP directory entry. The entry corresponds to the Certificate Manager's issuer name.This is an attribute of thepkiCA
orcertificationAuthority
object class. The value of the attribute is the DER-encoded binary X.509 CRL. The CA's entry must already contain thepkiCA
orcertificationAuthority
object class for the CRL to be published to the entry.Delta CRL deltaRevocationList;binary (attribute) This is the attribute to which the Certificate Manager publishes the delta CRL. The Certificate Manager publishes the delta CRL to its own LDAP directory entry, separate from the full CRL. The delta CRL entry corresponds to the Certificate Manager's issuer name.This attribute belongs to thedeltaCRL
orcertificationAuthority-V2
object class. The value of the attribute is the DER-encoded binary X.509 delta CRL. - Set up a bind DN for the Certificate Manager to use to access the Directory Server.The Certificate Manager user must have read-write permissions to the directory to publish certificates and CRLs to the directory so that the Certificate Manager can modify the user entries with certificate-related information and the CA entry with CA's certificate and CRL related information.The bind DN entry can be either of the following:
- An existing DN that has write access, such as the Directory Manager.
- A new user which is granted write access. The entry can be identified by the Certificate Manager's DN, such as
cn=testCA, ou=Research Dept, o=Example Corporation, st=California, c=US
.Note
Carefully consider what privileges are given to this user. This user can be restricted in what it can write to the directory by creating ACLs for the account. For instructions on giving write access to the Certificate Manager's entry, see the Directory Server documentation.
- Set the directory authentication method for how the Certificate Manager authenticates to Directory Server. There are three options: basic authentication (simple username and password); TLS without client authentication (simple username and password); and TLS with client authentication (certificate-based).See the Red Hat Directory Server documentation for instructions on setting up these methods of communication with the server.
7.4.2. Configuring LDAP Publishers
Publisher | Description |
---|---|
LdapCaCertPublisher | Publishes CA certificates to the LDAP directory. |
LdapCrlPublisher | Publishes CRLs to the LDAP directory. |
LdapDeltaCrlPublisher | Publishes delta CRLs to the LDAP directory. |
LdapUserCertPublisher | Publishes all types of end-entity certificates to the LDAP directory. |
LdapCrossCertPairPublisher | Publishes cross-signed certificates to the LDAP directory. |
7.4.3. Creating Mappers
Mapper | Description |
---|---|
LdapUserCertMap | Locates the correct attribute of user entries in the directory in order to publish user certificates. |
LdapCrlMap | Locates the correct attribute of the CA's entry in the directory in order to publish the CRL. |
LdapCaCertMap | Locates the correct attribute of the CA's entry in the directory in order to publish the CA certificate. |
- Log into the Certificate Manager Console.
pkiconsole https://server.example.com:8443/ca
- In the Configuration tab, select Certificate Manager from the navigation tree on the left. Select Publishing, and then Mappers.The Mappers Management tab, which lists configured mappers, opens on the right.
- To create a new mapper instance, click Select Mapper Plugin Implementation window opens, which lists registered mapper modules. Select a module, and edit it. For complete information about these modules, see Section C.2, “Mapper Plug-in Modules ”.. The
- Edit the mapper instance, and click.See Section C.2, “Mapper Plug-in Modules ” for detailed information about each mapper.
7.4.4. Completing Configuration: Rules and Enabling
7.5. Creating Rules
- Log into the Certificate Manager Console.
pkiconsole https://server.example.com:8443/ca
- In the Configuration tab, select Certificate Manager from the navigation tree on the left. Select Publishing, and then Rules.The Rules Management tab, which lists configured rules, opens on the right.
- To edit an existing rule, select that rule from the list, and click Rule Editor window.. This opens the
- To create a rule, click Select Rule Plug-in Implementation window.. This opens theSelect the
Rule
module. This is the only default module. If any custom modules have been been registered, they are also available. - Edit the rule.
- type. This is the type of certificate for which the rule applies. For a CA signing certificate, the value is
cacert
. For a cross-signed certificate, the value isxcert
. For all other types of certificates, the value iscerts
. For CRLs, specifycrl
. - predicate. This sets the predicate value for the type of certificate or CRL issuing point to which this rule applies. The predicate values for CRL issuing points, delta CRLs, and certificates are listed in Table 7.3, “Predicate Expressions”.
- enable.
- mapper. Mappers are not necessary when publishing to a file; they are only needed for LDAP publishing. If this rule is associated with a publisher that publishes to an LDAP directory, select an appropriate mapper here. Leave blank for all other forms of publishing.
- publisher. Sets the publisher to associate with the rule.
Predicate Type | Predicate |
---|---|
CRL Issuing Point | issuingPointId== Issuing_Point_Instance_ID && isDeltaCRl==[true|false]
To publish only the master CRL, set
isDeltaCRl==false . To publish only the delta CRL, set isDeltaCRl==true . To publish both, set a rule for the master CRL and another rule for the delta CRL.
|
Certificate Profile | profileId== profile_name
To publish certificates based on the profile used to issue them, set
profileId== to a profile name, such as caServerCert .
|
7.6. Enabling Publishing
Note
- Log into the Certificate Manager Console.
pkiconsole https://server.example.com:8443/ca
- In the Configuration tab, select Certificate Manager from the navigation tree on the left. Select Publishing.The right pane shows the details for publishing to an LDAP-compliant directory.
- To enable publishing to a file only, select Enable Publishing.
- To enable LDAP publishing, select both Enable Publishing and Enable Default LDAP Connection.In the Destination section, set the information for the Directory Server instance.
- Host name. If the Directory Server is configured for TLS client authenticated communication, the name must match the
cn
component in the subject DN of the Directory Server's TLS server certificate.The hostname can be the fully-qualified domain name or an IPv4 or IPv6 address. - Port number.
- Directory Manager DN. This is the distinguished name (DN) of the directory entry that has Directory Manager privileges. The Certificate Manager uses this DN to access the directory tree and to publish to the directory. The access control set up for this DN determines whether the Certificate Manager can perform publishing. It is possible to create another DN that has limited read-write permissions for only those attributes that the publishing system actually needs to write.
- Password. This is the password which the CA uses to bind to the LDAP directory to which the certificate or CRL is published. The Certificate Manager saves this password in its
password.conf
file. For example:CA LDAP Publishing:password
- Client certificate. This sets the certificate the Certificate Manager uses for TLS client authentication to the publishing directory. By default, the Certificate Manager uses its TLS server certificate.
- LDAP version. Select LDAP version 3.
- Authentication. The way the Certificate Manager authenticates to the Directory Server. The choices are
Basic authentication
andTLS client authentication
.If the Directory Server is configured for basic authentication or for TLS communication without client authentication, selectBasic authentication
and specify values for the Directory manager DN and password.If the Directory Server is configured for TLS communication with client authentication, selectTLS client authentication
and theUse TLS communication
option, and identify the certificate that the Certificate Manager must use for TLS client authentication to the directory.
7.7. Setting up Resumable CRL Downloads
7.7.1. Retrieving CRLs Using wget
wget
. The wget
command can be used to retrieve any published CRL. For example, to retrieve a full CRL which is newer than the previous full CRL:
[root@server ~]# wget --no-check-certificate -d https://server.example.com:8443/ca/ee/ca/crl/MasterCRL.bin
wget
are summarized in Table 7.4, “wget Options to Use for Retrieving CRLs”.
Argument | Description |
---|---|
no argument | Retrieves the full CRL. |
-N | Retrieves the CRL that is newer than the local copy (delta CRL). |
-c | Retrieves a partially-downloaded file. |
--no-check-certificate | Skips TLS for the connection, so it is not necessary to configure TLS between the host and client. |
-d | Prints debug information. |
7.8. Publishing Cross-Pair Certificates
crossCertificatePair
entry to an LDAP directory or to a file; this is enabled by default. If this has been disabled, it can be re-enabled through the Certificate Manager Console by doing the following:
- Open the CA console.
pkiconsole https://server.example.com:8443/ca
- In the Configuration tab, select the Certificate Manager link in the left pane, then the Publishing link.
- Click the Rules link under Publishing. This opens the Rules Management pane on the right.
- If the rule exists and has been disabled, select the enable checkbox. If the rule has been deleted, then click and create a new rule.
- Select xcerts from the type drop-down menu.
- Make sure the enable checkbox is selected.
- Select LdapCaCertMap from the mapper drop-down menu.
- Select LdapCrossCertPairPublisher from the publisher drop-down menu.
LdapCaCertMap
, by default designates that the crossCertificatePair
be stored to the LdapCaSimpleMap
LDAP entry. The publisher, LDAPCrossPairPublisher
, by default sets the attribute to store the cross-pair certificate in the CA entry to crossCertificatePair;binary
.
7.9. Testing Publishing to Files
- Open the CA's end-entities page, and request a certificate.
- Approve the request through the agent services page, if required.
- Retrieve the certificate from the end-entities page, and download the certificate into the browser.
- Check whether the server generated the DER-encoded file containing the certificate.Open the directory to which the binary blob of the certificate is supposed to be published. The certificate file should be named
cert-
serial_number.der
. - Convert the DER-encoded certificate to its base 64-encoded format using the Binary to ASCII tool. For more information on this tool, refer to the
BtoA(1)
man page.BtoA input_file output_file
input_file sets the path to the file that contains the DER-encoded certificate, and output_file sets the path to the file to write the base-64 encoded certificate. - Open the ASCII file; the base-64 encoded certificate is similar to the one shown:
-----BEGIN CERTIFICATE----- MMIIBtgYJYIZIAYb4QgIFoIIBpzCCAZ8wggGbMIIBRaADAgEAAgEBMA0GCSqGSIb3DQEBBAUAMFcxC AJBgNVBAYTAlVTMSwwKgYDVQQKEyNOZXRzY2FwZSBDb21tdW5pY2F0aWhfyyuougjgjjgmkgjkgmjg fjfgjjjgfyjfyj9ucyBDb3Jwb3JhdGlvbjpMEaMBgGA1UECxMRSXNzdWluZyhgdfhbfdpffjphotoo gdhkBBdXRob3JpdHkwHhcNOTYxMTA4MDkwNzM0WhcNOTgxMTA4MDkwNzMM0WjBXMQswCQYDVQQGEwJ VUzEsMCoGA1UEChMjTmV0c2NhcGUgQ29tbXVuaWNhdGlvbnMgQ29ycG9yY2F0aW9ucyBDb3Jwb3Jhd GlvbjpMEaMBgGA1UECxMRSXNzdWluZyBBdXRob3JpdHkwHh -----END CERTIFICATE-----
- Convert the base 64-encoded certificate to a readable form using the Pretty Print Certificate tool. For more information on this tool, refer to the
PrettyPrintCert(1)
man page.PrettyPrintCert input_file [output_file]
input_file sets the path to the ASCII file that contains the base-64 encoded certificate, and output_file, optionally, sets the path to the file to write the certificate. If an output file is not set, the certificate information is written to the standard output. - Compare the output with the certificate issued; check the serial number in the certificate with the one used in the filename.If everything matches, the Certificate Manager is configured correctly to publish certificates to file.
- Revoke the certificate.
- Check whether the server generated the DER-encoded file containing the CRL.Open the directory to which the server is to publish the CRL as a binary blob. The CRL file should have a name in the form
crl-
this_update.der
. this_update specifies the value derived from the time-dependentThis Update
variable of the CRL. - Convert the DER-encoded CRL to its base 64-encoded format using the Binary to ASCII tool.
BtoA input_file output_file
- Convert the base 64-encoded CRL to readable form using the Pretty Print CRL tool.
PrettyPrintCrl input_file [output_file]
- Compare the output.
7.10. Viewing Certificates and CRLs Published to File
dumpasn1
tool or the PrettyPrintCert
or PrettyPrintCrl
tool.
- Convert the base-64 file to binary. For example:
AtoB /tmp/example.b64 /tmp/example.bin
- Use the
PrettyPrintCert
orPrettyPrintCrl
tool to convert the binary file to pretty-print format. For example:PrettyPrintCert example.bin example.cert
dumpasn1
, PrettyPrintCert
, or PrettyPrintCrl
tool with the DER-encoded file. For example:
PrettyPrintCrl example.der example.crl
7.11. Updating Certificates and CRLs in a Directory
- Search the internal database for certificates that are out of sync and publish or unpublish.
- Publish certificates that were issued while the Directory Server was down. Similarly, unpublish certificates that were revoked or that expired while Directory Server was down.
- Publish or unpublish a range of certificates based on serial numbers, from serial number xx to serial number yy.
7.11.1. Manually Updating Certificates in the Directory
- Update the directory with certificates.
- Remove expired certificates from the directory.Removing expired certificates from the publishing directory can be automated by scheduling an automated job.
- Remove revoked certificates from the directory.
- Open the Certificate Manager agent services page.
- Select the Update Directory Server link.
- Select the appropriate options, and click.The Certificate Manager starts updating the directory with the certificate information in its internal database. If the changes are substantial, updating the directory can take considerable time. During this period, any changes made through the Certificate Manager, including any certificates issued or any certificates revoked, may not be included in the update. If any certificates are issued or revoked while the directory is updated, update the directory again to reflect those changes.
- Modify the default publishing rule for user certificates by changing the value of the
predicate
parameter toprofileId!=caCACert
. - Use the
LdapCaCertPublisher
publisher plug-in module to add another rule, with the predicate parameter set toprofileId=caCACert
, for publishing subordinate CA certificates.
7.11.2. Manually Updating the CRL in the Directory
- Open the Certificate Manager agent services page.
- Select Update Revocation List.
- Click.
Chapter 8. Authentication for Enrolling Certificates
8.1. Automatic Approval by an Authentication Plug-in
auth.instance_id
parameter in a profile specifies the authentication mechanism. A certificate request can either be automatically approved through an authentication plug-in, or be manually approved by a CA agent.
Note
8.1.1. Setting up Auto-approval of Enrollment Requests
- For agent-pre-approved CMC requests, set in the CA profile:
auth.instance_id=CMCAuth authz.acl=group="Certificate Manager Agents"
Theauthz.acl
parameter defines the group that is allowed to approve requests. - For user-initiated requests:
- When using CMC Shared Token, set in the CA profile:
auth.instance_id=CMCUserSignedAuth
Required default and constraint:policyset.cmcUserCertSet.1.constraint.class_id=cmcSharedTokenSubjectNameConstraintImpl policyset.cmcUserCertSet.1.constraint.name=CMC Shared Token Subject Name Constraint policyset.cmcUserCertSet.1.default.class_id=authTokenSubjectNameDefaultImpl policyset.cmcUserCertSet.1.default.name=Subject Name Default
- When using User-signed requests, set in the CA profile:
auth.instance_id=CMCUserSignedAuth
Required default and constraint:policyset.cmcUserCertSet.1.default.params.name= policyset.cmcUserCertSet.9.constraint.class_id=uniqueKeyConstraintImpl policyset.cmcUserCertSet.9.constraint.name=Unique Key Constraint policyset.cmcUserCertSet.9.constraint.params.allowSameKeyRenewal=true policyset.cmcUserCertSet.9.default.class_id=noDefaultImpl policyset.cmcUserCertSet.9.default.name=No Default
8.1.2. CMC Authentication Plug-ins
CMCAuth
- Use this plug-in when a CA agent signs CMC requests.To use the
CMCAuth
plug-in, set the following in the enrollment profile:auth.instance_id=CMCAuth
By default, the following enrollment profiles use theCMCAuth
plug-in:- For system certificates:
caCMCauditSigningCert
caCMCcaCert
caCMCECserverCert
caCMCECsubsystemCert
caCMCECUserCert
caCMCkraStorageCert
caCMCkraTransportCert
caCMCocspCert
caCMCserverCert
caCMCsubsystemCert
- For user certificates:
caCMCUserCert
caECFullCMCUserCert
caFullCMCUserCert
CMCUserSignedAuth
- Use this plug-in when users submit signed or SharedSecret-based CMC requests.To use the
CMCUserSignedAuth
plug-in, set the following in the enrollment profile:auth.instance_id=CMCUserSignedAuth
A user-signed CMC request must be signed by the user's certificate which contains the samesubjectDN
attribute as the requested certificate. You can only use a user-signed CMC request if the user already obtained a signing certificate which can be used to prove the user's identity for other certificates.A SharedSecret-based CMC request means that the request was signed by the private key of the request itself. In this case, the CMC request must use the Shared Secret mechanism for authentication. A SharedSecret-based CMC request is typically used to obtain the user's first signing certificate, which is later used to obtain other certificates. For further details, see Section 8.1.3, “CMC SharedSecret Authentication”.By default, the following enrollment profiles use theCMCUserSignedAuth
plug-in:caFullCMCUserSignedCert
caECFullCMCUserSignedCert
caFullCMCSharedTokenCert
caECFullCMCSharedTokenCert
8.2. Manual Approval by a CA Agent
- Set the
auth.instance_id
to an empty value:auth.instance_id=
- Do not set the
authz.acl
parameter.
8.3. Manually Reviewing the Certificate Status Using the Command Line
pki
command-line interface, see Section 2.5.1.1, “pki CLI Initialization”.
- Display the list of pending certificate requests:
$ pki agent_authentication_parameters ca-cert-request-find --status pending
This command lists all pending certificate requests. - Download a particular certificate request:
$ pki agent_authentication_parameters ca-cert-request-review id --file request.xml
- Open the
request.xml
file in an editor or a separate terminal, and review the contents of the request to ensure it is legitimate. Then answer the prompt: if the request is valid, answer "approve
and press Enter. If the request is invalid, answerreject
and press Enter. Organizations can subscribe semantic differences toreject
andcancel
; both result in no certificate being issued.
8.4. Manually Reviewing the Certificate Status Using the Web Interface
- Open the following URL in a web browser:
https://server_host_name:8443/ca/agent/ca
- Authenticate as an agent. For information about authenticating as a user and configuring your browser, see Section 2.4.1, “Browser Initialization”.
- On the sidebar on the left, click the List requests link.
- Filter the requests be selecting
Show all requests
for Request type andShow pending requests
for Request status. - Clickin the lower right corner.
- The results page lists all pending requests waiting for review. Click on the request number to review a request.
- Review the request information and ensure that it is a legitimate request. If necessary, modify the policy information to correct any mistakes or make any desired changes to the certificate, such as changing the not valid after field. Optionally, leave an additional note.The drop down menu includes several review status updates. Select Approve request to approve the request or Reject request to deny it, and click . Organizations can subscribe semantic differences to Reject request and Cancel Request; both result in no certificate being issued.
Chapter 9. Authorization for Enrolling Certificates (Access Evaluators)
Note
9.1. Authorization Mechanism
type
, op
, value
), evaluates an expression such as group='Certificate Manager Agents'
and returns a boolean depending on the result of evaluation.
9.2. Default Evaluators
accessEvaluator.impl.group.class=com.netscape.cms.evaluators.GroupAccessEvaluator accessEvaluator.impl.ipaddress.class=com.netscape.cms.evaluators.IPAddressAccessEvaluator accessEvaluator.impl.user.class=com.netscape.cms.evaluators.UserAccessEvaluator accessEvaluator.impl.user_origreq.class=com.netscape.cms.evaluators.UserOrigReqAccessEvaluator
group
access evaluator evaluates the group membership properties of a user. For example, in the following enrollment profile entry, only the CA agents are allowed to go through enrollment with that profile:
authz.acl=group="Certificate Manager Agents"
ipaddress
access evaluator evaluates the IP address of the requesting subject. For example, in the following enrollment profile entry, only the host bearing the specified IP address can go through enrollment with that profile:
authz.acl=ipaddress="a.b.c.d.e.f"
user
access evaluator evaluates the user ID for exact match. For example, in the following enrollment profile entry, only the user matching the listed user is allowed to go through enrollment with that profile:
authz.acl=user="bob"
user_origreq
access evaluator evaluates the authenticated user against a previous matching request for equality. This special evaluator is designed specifically for renewal purpose to make sure the user requesting the renewal is the same user that owns the original request. For example, in the following renewal enrollment profile entry, the UID of the authenticated user must match the UID of the user requesting the renewal:
authz.acl=user_origreq="auth_token.uid"
Part IV. Managing the Subsystem Instances
Chapter 10. Self Tests
10.1. Running Self-Tests
10.1.1. Running Self-Tests
10.1.1.1. Running Self-Tests from the Console
- Log into the Console.
pkiconsole https://server.example.com:admin_port/subsystem_type
- Select the subsystem name at the top of the left pane.
- Select the Self Tests tab.
- Click.The self-tests that are configured for the subsystem will run. If any critical self-tests fail, the server will stop.
- The On-Demand Self Tests Results window appears, showing the logged events for this run of the self-tests.
10.1.1.2. Running TPS Self-Tests
pki tps-selftest-find
pki tps-selftest-run
pki tps-selftest-show
10.2. Debugging Self-Tests Failures
# systemctl restart pki-tomcatd-nuxwdog@instance_name.service
10.2.1. Self-Test Logging
selftests.log
, is added to the log directory that contains reports for both the start up self-tests and the on-demand self-tests.
Chapter 11. Managing Certificate/Key Crypto Token
About Crypto Tokens
11.1. About certutil
and PKICertImport
certutil
command is provided by Network Security Services (NSS). certutil
is used for validating and importing certificates. A basic overview of how we use certutil
is presented below, however, PKICertImport
is our wrapper script of choice for safely validating and importing certificates. Using certutil
to do so requires multiple command invocations and correct usage is outside the scope of this documentation.
11.1.1. certutil
Basic Usage
certutil [command] [options]
certutil
invocation takes a command flag, usually denoted by a capital letter, and a series of options which control what the command does. If an option takes a value, that value is named between "<" and ">" symbols.
11.1.2. PKICertImport Basic Usage
PKICertImport [options]
PKICertImport
invocation accepts a series of options to validate and import a specified certificate. Unlike the broad use cases of certutil
, PKICertImport
is only focused on safely importing and validating certificates. See Section 11.1.4, “Common certutil
and PKICertImport
Options” for more information about available options.
Note
PKICertImport
prompts for the NSS DB and/or HSM passwords multiple times throughout the course of its execution. This is expected as PKICertImport
has to interact with the NSS DB multiple times. To avoid having to input the NSS DB password repetitively, specify a password file via -f <filename>
. When done, be sure to delete the password file.
11.1.3. certutil
Common Commands
certutil
and provide a brief overview of several common commands. PKICertImport
is not compatible with nor require these command flags.
certutil -A
-A
command denotes "adding" a certificate. It requires a certificate to import (-i
), a nickname (-n
) for that certificate, and a series of trust flags (-t
) for the certificate.
certutil -V
-V
command denotes "verifying" a certificate. It requires a certificate nickname to validate (-n
) and a type of verification (-u
) to perform.
certutil -D
-D
command denotes "deleting" a certificate. It requires a certificate nickname (-n
) to remove.
certutil -M
-M
command denotes "modifying" a certificate. It requires a certificate nickname (-n
) to modify, and a series of trust flags (-t
) to give the certificate.
certutil -L
-L
command denotes "listing" a certificate or all certificates. If given the nickname option (-n
), it will list detailed information about that certificate, else if omitted, it will list general information about all certificates present.
certutil -L
would show each certificate by its nickname along with its trust info. For example:
Certificate Nickname
|
Trust Attributes |
---|---|
caSigningCert pki-ca1
|
CT, C, C
|
Note
certutil -L
correspond to what is specified with the -t
option.
certutil -L
does not modify the database, and can thus be executed safely as many times as desired.
11.1.4. Common certutil
and PKICertImport
Options
PKICertImport
as well.
-n <nickname>
-n <nickname>
option specifies the nickname for a certificate. This can be any text and is only used as a reference to the certificate. It MUST be unique.
-d <directory>
-d <directory>
option specifies the path to the NSS DB directory in use. We usually assume you are already in this directory and use "." to refer to the current directory.
-t <trust>
-t <trust>
option specifies the trust level for the certificate.
- trust for TLS
- trust for email
- trust for object signing
c
, C
, and T
.
c
states that this certificate should be a Certificate Authority (CA).C
states that this is a trusted certificate authority for signing server certificates (C
implies lowercasec
, hence you do not need to specify both).T
states that this certificate is a trusted authority for signing client certificates (T
implies lowercasec
, hence you do not need to specify bothT
andc
).
-t CT,C,c
means that the certificate is trusted for signing client and server TLS certificates, signing server email certificates (S/MIME), and is a valid CA for object signing (though untrusted).
- This ensures that, if this certificate signs another certificate, which in turn is used for object signing, it will be deemed invalid.
-t ,,
.
certutil -L -d
- Each certificate's nickname will be listed and the trust flags will be specified at the end of the line.
-h
option.
man certutil
command on a system with certutil properly installed.
-h <HSM>
-h <HSM>
option specifies the name of the HSM to perform operations on.
-h
option is incompatible with the -t
option, as HSMs cannot store trust. Only an NSS DB can store trust, so using the certutil -A
command or the certutil -M
command in conjunction with -h <HSM>
will fail. Instead, specify the desired trust level on a separate certutil -M
command without the -h
option.
-e
-e
option specifies that the validity of the signature is checked as well, when used in conjunction with the certutil -V
command. PKICertImport
always performs the certificate signature validation and does not understand the -e
option.
-a
-a
option specifies that the key in question is in PEM (ASCII) format.
-i <certificate>
-i <certificate>
option specifies the path to the certificate. This is only used in the certutil -A
command to specify the path to the certificate to import.
-u <usage>
-u <usage>
option specifies that usage of the certificate to verify when used in conjunction with the certutil -V
command.
-u C
stands for verify a client TLS certificate. Note that this mostly accepts any certificate, but will check expiration date and signature.-u V
stands for verify a server TLS certificate. Note that this will reject CA certificates and will check expiration date and signature.-u L
stands for verify a CA TLS certificate. Note that this will validate trust flags (to see ifc
is present) and will check key usage to ensure that the key is a CA key. This also checks expiration and signatures.-u O
stands for verify a OCSP status responder certificate. Note that this checks expiry and signatures.-u J
stands for verify an object signing certificate. Note that this checks expiry and signatures.
c
flag for an CA TLS certificate), certutil -V
will give incorrect results.
Note
man certutil
command on a system with certutil properly installed.
11.2. Importing a Root Certificate
cd
/path/to/nssdb
ca_root.crt
. Please substitute the correct name and path to this file as appropriate for your scenario.
certutil
and PKICertImport
options used below, see Section 11.1, “About certutil
and PKICertImport
”.
To import the root certificate:
- Execute
PKICertImport -d . -n "CA Root" -t "CT,C,C" -a -i ca_root.crt -u L
command.This command validates and imports the root certificate into your NSS DB. The validation succeeds when no error message is printed and the return code is 0. To check the return code, executeecho $?
immediately after executing the previous command above. In most cases, a visual error message is printed. The certificate usually fails to validate because it is expired or because it is not a CA certificate. Therefore, make sure your certificate file is correct and up-to-date. Contact the issuer and ensure that all intermediate and root certificates are present on your system.
11.3. Importing an Intermediate Certificate Chain
cd
/path/to/nssdb
ca_sub_<num>.crt
(for example ca_sub_1.crt
, ca_sub_2.crt
, and so on). Substitute names and paths for your certificates as appropriate to your deployment.
Note
fullchain.crt
, fullchain.pem
, or similar and it contains multiple certificates, split it into the above format by copying each block (between and including the ----BEGIN CERTIFICATE----- and an -----END CERTIFICATE----- markers) to its own file. The first ones should be named ca_sub_<num>.crt
and the last will be your server cert named service.crt
. Server certificates are discussed in later sections.
certutil
and PKICertImport
options used below, see Section 11.1, “About certutil
and PKICertImport
”.
For every intermediate certificate in the chain:
- Execute
PKICertImport -d . -n "CA Sub $num" -t "CT,C,C" -a -i ca_sub_$num.crt -u L
This command validates and imports the Intermediate CA certificate into your NSS DB. The validation succeeds when no error message is printed and the return code is 0. To check the return code, executeecho $?
immediately after executing the previous command above. In most cases, a visual error message is printed. If the validation does not succeed, contact the issuer and ensure that all intermediate and root certificates are present on your system.
11.4. Importing a certificate into an NSS Database
- For any subsystem's
auditSigningCert
, please follow the steps below for validating an object Signing certificate. - For the CA subsystem's
caSigningCert
, please follow the steps above for importing and validating an intermediate certificate chain, but do so only with the caSigningCert. - For the CA subsystem's
ocspSigningCert
, please follow the steps below for validating an OCSP certificate. - For user's client or S/MIME certificate, follow the Client Certificate steps.
certutil
and PKICertImport
options used below, see Section 11.1, “About certutil
and PKICertImport
”.
Importing a Client Certificate Into the NSS Database
- Change into the NSS database directory. For example:
# cd /path/to/nssdb/
- Import and trust the root certificate, if it is not already imported and trusted. For details, see Section 11.2, “Importing a Root Certificate”.
- Import and validate the intermediate certificates, if not already imported and validated. For details, see Section 11.3, “Importing an Intermediate Certificate Chain”.
- Validate and import the client certificate:
#
PKICertImport -d . -n "client name" -t ",," -a -i client.crt -u C
The validation succeeds when no error message is printed and the return code is 0. To check the return code, executeecho $?
immediately after executing the previous command above. In most cases, a visual error message is printed. If the validation does not succeed, contact the issuer and ensure that all intermediate and root certificates are present on your system.
Importing an Object Signing Certificate
- Change into the NSS database directory. For example:
# cd /path/to/nssdb/
- Import and trust the root certificate, if it is not already imported and trusted. For details, see Section 11.2, “Importing a Root Certificate”.
- Import and validate the intermediate certificates, if not already imported and validated. For details, see Section 11.3, “Importing an Intermediate Certificate Chain”.
- Validate and import the object signing certificate:
#
PKICertImport -d . -n "certificate name" -t ",,P" -a -i objectsigning.crt -u J
The validation succeeds when no error message is printed and the return code is 0. To check the return code, executeecho $?
immediately after executing the previous command above. In most cases, a visual error message is printed. If the validation does not succeed, contact the issuer and ensure that all intermediate and root certificates are present on your system.
Importing an OCSP Responder
- Change into the NSS database directory. For example:
# cd /path/to/nssdb/
- Import and trust the root certificate, if it is not already imported and trusted. For details, see Section 11.2, “Importing a Root Certificate”.
- Import and validate the intermediate certificates, if not already imported and validated. For details, see Section 11.3, “Importing an Intermediate Certificate Chain”.
- Validate and import the OCSP responder certificate:
#
PKICertImport -d . -n "certificate name" -t ",," -a -i ocsp.crt -u O
The validation succeeds when no error message is printed and the return code is 0. To check the return code, executeecho $?
immediately after executing the previous command above. In most cases, a visual error message is printed. If the validation does not succeed, contact the issuer and ensure that all intermediate and root certificates are present on your system.
Chapter 12. Managing Certificate System Users and Groups
12.1. About Authorization
Note
- The users authenticate to the interface using a certificate.
- The server authenticates the user by checking the certificate against one stored in the database. The server also checks that the certificate is valid and finds the group membership of the user by associating the DN of the certificate with a user and checking the user entry.
- When the user tries to perform an operation, the authorization mechanism compares the user ID of the user, the group in which the user belongs, or the IP address of the user to the ACLs set for that user, group, or IP address. If an ACL exists that allows that operation, then the operation proceeds.
12.2. Default Groups
- Administrators. This group is given full access to all of the tasks available in the administrative interface.
- Agents. This group is given full access to all of the tasks available in the agent services interface.
- Auditors. This group is given access to view the signed audit logs. This group does not have any other privileges.
- Enterprise administrators. Each subsystem instance is automatically assigned a subsystem-specific role as an enterprise administrator when it is joined to a security domain during configuration. These roles automatically provide trusted relationships among subsystems in the security domain, so that each subsystem can efficiently carry out interactions with other subsystems.
12.2.1. Administrators
Administrators
group for the group. Every member of that group has administrative privileges for that instance of Certificate System.
Role | Description |
---|---|
Security Domain Administrators |
By default, the CA administrator of the CA hosting the domain is assigned as the security domain administrator.
|
Enterprise CA Administrators |
|
Enterprise KRA Administrators |
|
Enterprise OCSP Administrators |
|
Enterprise TKS Administrators |
|
Enterprise TPS Administrators |
|
12.2.2. Auditors
Auditors
group and storing the auditor's certificate in the user entry. The auditor's certificate is used to encrypt the private key of the key pair used to sign the audit log.
Auditors
group is set when the subsystem is configured. No auditors are assigned to this group during configuration.
12.2.3. Agents
- The Certificate Manager Agents group.
- The Key Recovery Authority Agents group.
- The Online Certificate Status Manager Agents group.
- The Token Key Service Agents group.
- The Token Processing System Agents group.
12.2.4. Enterprise Groups
Note
- Enterprise CA Administrators
- Enterprise KRA Administrators
- Enterprise OCSP Administrators
- Enterprise TKS Administrators
- Enterprise TPS Administrators
12.3. Managing Users and Groups for a CA, OCSP, KRA, or TKS
12.3.1. Managing Groups
12.3.1.1. Creating a New Group
- Log into the administrative console.
pkiconsole https://server.example.com:8443/subsystem_type
- Select Users and Groups from the navigation menu on the left.
- Select the Groups tab.
- Click, and fill in the group information.It is only possible to add users who already exist in the internal database.
- Edit the ACLs to grant the group privileges. See Section 12.4.3, “Editing ACLs” for more information. If no ACIs are added to the ACLs for the group, the group will have no access permissions to any part of Certificate System.
12.3.1.2. Changing Members in a Group
- Log into the administrative console.
- Select Users and Groups from the navigation tree on the left.
- Click the Groups tab.
- Select the group from the list of names, and click.
- Make the appropriate changes.
- To change the group description, type a new description in the Group description field.
- To remove a user from the group, select the user, and click.
- To add users, click. Select the users to add from the dialog box, and click .
12.3.2. Managing Users (Administrators, Agents, and Auditors)
12.3.2.1. Creating Users
Note
12.3.2.1.1. Creating Users Using the Command Line
- Add a user account. For example, to add the
example
user to the CA:# pki -c password -n caadmin \ ca-user-add example --fullName "Example User" --------------------- Added user "example" --------------------- User ID: example Full name: Example User
This command uses thecaadmin
user to add a new account. - Optionally, add a user to a group. For example, to add the
example
user to theCertificate Manager Agents
group:# pki -p password -n "caadmin" \ user-add-membership example Certificate Manager Agents
- Create a certificate request:
- If a Key Recovery Authority (KRA) exists in your Certificate System environment:
# CRMFPopClient -d ~/.dogtag/pki-instance_name/ -p password \ -n "user_name" -q POP_SUCCESS -b kra.transport -w "AES/CBC/PKCS5Padding" \ -v -o ~/user_name.req
This command stores the Certificate Signing Request (CSR) in theCRMF
format in the~/user_name.req
file. - If no Key Recovery Authority (KRA) exists in your Certificate System environment:
# PKCS10Client -d ~/.dogtag/pki-instance_name/ -p password \ -n "user_name" -o ~/user_name.req
This command stores the CSR inpkcs10
format in the~/user_name.req
file.
- Create an enrollment request:
- Create the
~/cmc.role_crmf.cfg
file 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 #Multiple files are supported. They must be separated by space. input=~/user_name.req #output: full path for the CMC request in binary format output=~/cmc.role_crmf.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=PKI Administrator for Example.com #dbdir: directory for cert8.db, key3.db and secmod.db dbdir=~/.dogtag/pki-instance_name/ #password: password for cert8.db which stores the agent #certificate password=password #format: request format, either pkcs10 or crmf format=crmf
Set the parameters based on your environment and the CSR format used in the previous step. - Pass the previously created configuration file to the
CMCRequest
utility to create the CMC request:# CMCRequest ~/cmc.role_crmf.cfg
- Submit a Certificate Management over CMS (CMC) request:
- Create the
~/HttpClient_role_crmf.cfg
file with the following content:# #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=~/cmc.role_crmf.req #output: full path for the response in binary format output=~/cmc.role_crmf.resp #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=~/.dogtag/pki-instance_name/ #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=PKI Administrator for Example.com #servlet: servlet name servlet=/ca/ee/ca/profileSubmitCMCFull
Set the parameters based on your environment. - Submit the request to the CA:
# HttpClient ~/HttpClient_role_crmf.cfg Total number of bytes read = 3776 after SSLSocket created, thread token is Internal Key Storage Token client cert is not null handshake happened writing to socket Total number of bytes read = 2523 MIIJ1wYJKoZIhvcNAQcCoIIJyDCCCcQCAQMxDzANBglghkgBZQMEAgEFADAxBggr ... The response in data format is stored in ~/cmc.role_crmf.resp
- Verify the result:
# CMCResponse ~/cmc.role_crmf.resp Certificates: Certificate: Data: Version: v3 Serial Number: 0xE Signature Algorithm: SHA256withRSA - 1.2.840.113549.1.1.11 Issuer: CN=CA Signing Certificate,OU=pki-instance_name Security Domain Validity: Not Before: Friday, July 21, 2017 12:06:50 PM PDT America/Los_Angeles Not After: Wednesday, January 17, 2018 12:06:50 PM PST America/Los_Angeles Subject: CN=user_name ... Number of controls is 1 Control #0: CMCStatusInfoV2 OID: {1 3 6 1 5 5 7 7 25} BodyList: 1 Status: SUCCESS
- Optionally, to import the certificate as the user to its own
~/.dogtag/pki-instance_name/
database:# certutil -d ~/.dogtag/pki-instance_name/ -A -t "u,u,u" -n "user_name certificate" -i ~/cmc.role_crmf.resp
- Add the certificate to the user record:
- List certificates issued for the user to discover the certificate's serial number. For example, to list certificates that contain the
example
user name in the certificate's subject:pki -c password -n caadmin ca-user-cert-find example ----------------- 1 entries matched ----------------- Cert ID: 2;6;CN=CA Signing Certificate,O=EXAMPLE;CN=PKI Administrator,E=example@example.com,O=EXAMPLE Version: 2 Serial Number: 0x6 Issuer: CN=CA Signing Certificate,O=EXAMPLE Subject: CN=PKI Administrator,E=example@example.com,O=EXAMPLE ---------------------------- Number of entries returned 1
The serial number of the certificate is required in the next step. - Add the certificate using its serial number from the certificate repository to the user account in the Certificate System database. For example, for a CA user:
pki -c password -n caadmin ca-user-cert-add example --serial 0x6
12.3.2.1.2. Creating Users Using the Console
- Log into the administrative console.
pkiconsole https://server.example.com:8443/subsystem_type
- In the Configuration tab, select Users and Groups. Click .
- Fill in the information in the Edit User Information dialog.Most of the information is standard user information, such as the user's name, email address, and password. This window also contains a field called User State, which can contain any string, which is used to add additional information about the user; most basically, this field can show whether this is an active user.
- Select the group to which the user will belong. The user's group membership determines what privileges the user has. Assign agents, administrators, and auditors to the appropriate subsystem group.
- Store the user's certificate.
- Request a user certificate through the CA end-entities service page.
- If auto-enrollment is not configured for the user profile, then approve the certificate request.
- Retrieve the certificate using the URL provided in the notification email, and copy the base-64 encoded certificate to a local file or to the clipboard.
- Select the new user entry, and click.
- Click, and paste in the base-64 encoded certificate.
12.3.2.2. Changing a Certificate System User's Certificate
- Log into the administrative console.
- Select Users and Groups.
- Select the user to edit from the list of user IDs, and click.
- Clickto add the new certificate.
- In the Import Certificate window, paste the new certificate in the text area. Include the
-----BEGIN CERTIFICATE-----
and-----END CERTIFICATE-----
marker lines.
12.3.2.3. Renewing Administrator, Agent, and Auditor User Certificates
- Renew the admin user certificate. For details, seeSection 5.4, “Renewing Certificates”.
- Add the renewed user certificate to the user entry in the internal LDAP database.
- Open the console for the subsystem.
pkiconsole https://server.example.com:admin_port/subsystem_type
- Configuration | Users and Groups | Users | admin | Certificates | Import
- In the Configuration tab, select Users and Groups.
- In the Users tab, double-click the user entry with the renewed certificate, and click .
- Click, and paste in the base-64 encoded certificate.
This can also be done by usingldapmodify
to add the renewed certification directly to the user entry in the internal LDAP database, by replacing theuserCertificate
attribute in the user entry, such asuid=admin,ou=people,dc=
subsystem-base-DN.
12.3.2.4. Deleting a Certificate System User
- Log into the administrative console.
- Select Users and Groups from the navigation menu on the left.
- Select the user from the list of user IDs, and click.
- Confirm the delete when prompted.
12.4. Configuring Access Control for Users
12.4.1. About Access Control
LogAdmins
, can be added to the ACLs relevant to logs to allow read or modify access to this group. If this group is not added to any other ACLs, members of this group only have access to the logs.
allow|deny (operation) user|group|IP="name"
Note
allow (read) group="Administrators"
allow (read,modify) group="Administrators"
||
) with a space on either side. For example:
allow (read) group="Administrators" || group="Auditors"
Note
Administrators
group. If an ACL has only the following ACL, JohnB is denied any access since he does not match any of the allow ACIs:
Allow (read,modify) group="Auditors" || user="BrianC"
JohnB
, a member of the Administrators
group, has just been fired. It may be necessary to deny access specifically to JohnB
if the user cannot be deleted immediately. Another situation is that a user, BrianC
, is an administrator, but he should not have the ability to change some resource. Since the Administrators
group must access this resource, BrianC
can be specifically denied access by creating an ACI that denies this user access.
=
) or does not equal (!=
).
group="groupname"
. The syntax to exclude a group is group!="groupname"
, which allows any group except for the group named. For example:
group="Administrators" || group!="Auditors"
*
). For example:
group="* Managers"
user="userID"
. The syntax to exclude the user is user!="userID"
, which allows any user ID except for the user ID named. For example:
user="BobC" || user!="JaneK"
anybody
. For example:
user="anybody"
*
). For example:
user="*johnson"
ipaddress="ipaddress"
. The syntax to exclude an ID address from the ACL is ipaddress!="ipaddress"
. An IP address is specified using its numeric value; DNS values are not permitted. For example:
ipaddress="12.33.45.99" ipaddress!="23.99.09.88"
ipaddress="0:0:0:0:0:0:13.1.68.3"
*
). For example:
ipaddress="12.33.45.*"
user="BobC" || group="Auditors" || group="Administrators"
12.4.2. Adding ACLs
- Log into the administrative console.
- Select Access Control List.
- Click Access Control Editor.to open the
- Fill the
Resource name
andAvailable rights
fields. - To add an access control instruction (ACI), click, and supply the ACI information.
- Select the allow or deny radio button from the Access field to allow or deny the operation to the groups, users, or IP addresses specified. For more information about allowing or denying access, see Section 12.4.1, “About Access Control”.
- Set the rights. The available options are
read
andmodify
. To select both, hold the or button while selecting the entries. - Specify the user, group, or IP address that will be granted or denied access in the Syntax field. See Section 12.4.1, “About Access Control” for details on syntax.
- Click Access Control Editor window.to return to the
- Clickto store the ACI.
12.4.3. Editing ACLs
- Log into the administrative console.
- Select Access Control List in the left navigation menu.
- Select the ACL to edit from the list, and click.The ACL opens in the Access Control Editor window.
- To add an ACI, click, and supply the ACI information.To edit an ACI, select the ACI from the list in the ACI entries text area of the ACL Editor window. Click .
- Select the allow or deny radio button from the Access field to allow or deny the operation to the groups, users, or IP addresses specified. For more information about allowing or denying access, see Section 12.4.1, “About Access Control”.
- Set the rights for the access control. The options are
read
andmodify
. To set both, use the or buttons. - Specify the user, group, or IP address that will be granted or denied access in the Syntax field. See Section 12.4.1, “About Access Control” for details on syntax.
Chapter 13. Configuring Subsystem Logs
13.1. Managing Logs
13.1.1. Configuring Logs in the Console
- In the navigation tree of the Configuration tab, select Log.
- The Log Event Listener Management tab lists the currently configured listeners.To create a new log instance, click Select Log Event Listener Plug-in Implementation window., and select a module plug-in from the list in the
- Set or modify the fields in the Log Event Listener Editor window. The different parameters are listed in Table 13.1, “Log Event Listener Fields”.
Field | Description |
---|---|
Log Event Listener ID | Gives the unique name that identifies the listener. The names can have any combination of letters (aA to zZ), digits (0 to 9), an underscore (_), and a hyphen (-), but it cannot contain other characters or spaces. |
type | Gives the type of log file. system creates error and system logs; transaction records audit logs. |
enabled | Sets whether the log is active. Only enabled logs actually record events. The value is either true or false . |
level | Sets the log level in the text field. The level must be manually entered in the field; there is no selection menu. The choices are Debug, Information, Warning, Failure, Misconfiguration, Catastrophe, and Security. |
fileName | Gives the full path, including the file name, to the log file. The subsystem user should have read/write permission to the file. |
bufferSize | Sets the buffer size in kilobytes (KB) for the log. Once the buffer reaches this size, the contents of the buffer are flushed out and copied to the log file. The default size is 512 KB. |
flushInterval | Sets the amount of time before the contents of the buffer are flushed out and added to the log file. The default interval is 5 seconds. |
maxFileSize | Sets the size, in kilobytes (KB), a log file can become before it is rotated. Once it reaches this size, the file is copied to a rotated file, and the log file is started new. The default size is 2000 KB. |
rolloverInterval | Sets the frequency for the server to rotate the active log file. The available options are hourly, daily, weekly, monthly, and yearly. The default is monthly. |
13.1.2. Managing Audit Logs
Note
/var/log/pki/instance_name/subsystem_name/
directory with other types of logs, while signed audit logs are written to /var/log/pki/instance_name/subsystem_name/signedAudit/
. The default location for logs can be changed by modifying the configuration.
13.1.2.1. Configuring a Signed Audit Log in the Console
Note
logSigning
parameter to enable
and providing the nickname of the certificate used to sign the log. A special log signing certificate is created when the subsystems are first configured.
AuditVerify
tool to verify that signed audit logs have not been tampered with.
- Open the Console.
- In the navigation tree of the Configuration tab, select Log.
- In the Log Event Listener Management tab, select the SignedAudit entry.
- Click.
- There are two fields which must be reset in the Log Event Listener Editor window.
- Set the logSigning field to
true
to enable signed logging.Note
For more fine-grained audit event select, set audit event filters during the installation configuration. For details, see the Filtering Audit Events section in the Red Hat Certificate System Planning, Installation, and Deployment Guide (Common Criteria Edition). - Set any events which are logged to the audit log. Appendix E, Audit Events lists the loggable events. Log events are separated by commas with no spaces.
- Save the log configuration.
AuditVerify(1)
man page for details about using this tool. For further details, see Section 13.2.2, “Using Signed Audit Logs”.
13.1.2.2. Handling Audit Logging Failures
- Servlets are disabled and will not process new requests.
- All pending and new requests are killed.
- The subsystem is shut down.
13.2. Using Logs
13.2.1. Viewing Logs in the Console
- Log into the Console.
- Select the Status tab.
- Under Logs, select the log to view.
- Set the viewing preferences in the Display Options section.
- Entries — The maximum number of entries to be displayed. When this limit is reached, the Certificate System returns any entries that match the search request. Zero (0) means no messages are returned. If the field is blank, the server returns every matching entry, regardless of the number found.
- Source — Select the Certificate System component or service for which log messages are to be displayed. Choosing All means messages logged by all components that log to this file are displayed.
- Level — Select a message category that represents the log level for filtering messages.
- Filename — Select the log file to view. Choose Current to view the currently active system log file.
- Click.The table displays the system log entries. The entries are in reverse chronological order, with the most current entry placed at the top. Use the scroll arrows on the right edge of the panel to scroll through the log entries.Each entry has the following information shown:
- Source — The component or resource that logged the message.
- Level — The severity of the corresponding entry.
- Date — The date on which the entry was logged.
- Time — The time at which the entry was logged.
- Details — A brief description of the log.
- To view a full entry, double-click it, or select the entry, and click.
13.2.2. Using Signed Audit Logs
13.2.2.1. Listing Audit Logs
pki subsystem-audit-file-find
command to list existing audit log files on the server.
server.example.com
:
# pki -h server.example.com -p 8443 -n auditor ca-audit-file-find ----------------- 3 entries matched ----------------- File name: ca_audit.20170331225716 Size: 2883 File name: ca_audit.20170401001030 Size: 189 File name: ca_audit Size: 6705 ---------------------------- Number of entries returned 3 ----------------------------
~/.dogtag/nssdb/
directory for authenticating to the CA. For further details about the parameters used in the command and alternative authentication methods, see the pki(1) man page.
13.2.2.2. Downloading Audit Logs
pki subsystem-audit-file-retrieve
command to download a specific audit log from the server.
server.example.com
:
- Optionally, list the available log files on the CA. See Section 13.2.2.1, “Listing Audit Logs”.
- Download the log file. For example, to download the
ca_audit
file:# pki -U https://server.example.com:8443 -n auditor ca-audit-file-retrieve ca_audit
The command uses the client certificate with the auditor nickname stored in the~/.dogtag/nssdb/
directory for authenticating to the CA. For further details about the parameters used in the command and alternative authentication methods, see the pki(1) man page.
grep
utility:
# grep "\[AuditEvent=ACCESS_SESSION_ESTABLISH\]" log_file
13.2.2.3. Verifying Signed Audit Logs
- Initialize the NSS database and import the CA certificate. For details, see the Command-line Initialization section in the Red Hat Certificate System 9 Planning, Installation and Deployment Guide (Common Criteria Edition).
- If the audit signing certificate does not exist in the PKI client database, import it:
- Search the audit signing certificate for the subsystem logs you want to verify. For example:
# pki ca-cert-find --name "CA Audit Signing Certificate" --------------- 1 entries found --------------- Serial Number: 0x5 Subject DN: CN=CA Audit Signing Certificate,O=EXAMPLE Status: VALID Type: X.509 version 3 Key Algorithm: PKCS #1 RSA with 2048-bit key Not Valid Before: Fri Jul 08 03:56:08 CEST 2016 Not Valid After: Thu Jun 28 03:56:08 CEST 2018 Issued On: Fri Jul 08 03:56:08 CEST 2016 Issued By: system ---------------------------- Number of entries returned 1 ----------------------------
- Import the audit signing certificate into the PKI client:
# pki client-cert-import "CA Audit Signing Certificate" --serial 0x5 --trust ",,P" --------------------------------------------------- Imported certificate "CA Audit Signing Certificate" ---------------------------------------------------
- Download the audit logs. See Section 13.2.2.2, “Downloading Audit Logs”.
- Verify the audit logs.
- Create a text file that contains a list of the audit log files you want to verify in chronological order. For example:
# cat > ~/audit.txt << EOF ca_audit.20170331225716 ca_audit.20170401001030 ca_audit EOF
- Use the
AuditVerify
utility to verify the signatures. For example:# AuditVerify -d ~/.dogtag/nssdb/ -n "CA Audit Signing Certificate" \ -a ~/audit.txt Verification process complete. Valid signatures: 10 Invalid signatures: 0
For further details about usingAuditVerify
, see the AuditVerify(1) man page.
13.2.3. Displaying Operating System-level Audit Logs
Note
auditd
logging framework must be configured per the Enabling OS-level Audit Logs section in the Red Hat Certificate System 9 Planning, Installation and Deployment Guide (Common Criteria Edition).
ausearch
utility as root or as a privileged user with the sudo
utility.
13.2.3.1. Displaying Audit Log Deletion Events
rhcs_audit_deletion
), use the -k
parameter to find events matching that key:
# ausearch -k rhcs_audit_deletion
13.2.3.2. Displaying Access to the NSS Database for Secret and Private Keys
rhcs_audit_nssdb
), use the -k
parameter to find events matching that key:
# ausearch -k rhcs_audit_nssdb
13.2.3.3. Displaying Time Change Events
rhcs_audit_time_change
), use the -k
parameter to find events matching that key:
# ausearch -k rhcs_audit_time_change
13.2.3.4. Displaying Package Update Events
SOFTWARE_UPDATE
), use the -m
parameter to find events matching that type:
# ausearch -m SOFTWARE_UPDATE
13.2.3.5. Displaying Changes to the PKI Configuration
rhcs_audit_config
), use the -k
parameter to find events matching that key:
# ausearch -k rhcs_audit_config
Chapter 14. Managing Subsystem Certificates
14.1. Required Subsystem Certificates
14.1.1. Certificate Manager Certificates
14.1.1.1. CA Signing Key Pair and Certificate
caSigningCert cert-
instance_ID CA, where instance_ID identifies the Certificate Manager instance. The default validity period for the certificate is five years.
- If the Certificate Manager is a root CA, its CA signing certificate is self-signed, meaning the subject name and issuer name of the certificate are the same.
- If the Certificate Manager is a subordinate CA, its CA signing certificate is signed by another CA, usually the one that is a level above in the CA hierarchy (which may or may not be a root CA). The root CA's signing certificate must be imported into individual clients and servers before the Certificate Manager can be used to issue certificates to them.
Note
14.1.1.2. OCSP Signing Key Pair and Certificate
cn=OCSP cert-
instance_ID CA, and it contains extensions, such as OCSPSigning
and OCSPNoCheck
, required for signing OCSP responses.
ocspSigningCert cert-
instance_ID, where instance_ID CA identifies the Certificate Manager instance.
14.1.1.3. Subsystem Certificate
subsystemCert cert-
instance_ID.
14.1.1.4. TLS Server Key Pair and Certificate
Server-Cert cert-
instance_ID, where instance_ID identifies the Certificate Manager instance.
14.1.1.5. Audit Log Signing Key Pair and Certificate
Note
14.1.2. Online Certificate Status Manager Certificates
14.1.2.1. OCSP Signing Key Pair and Certificate
ocspSigningCert cert-
instance_ID, where instance_ID OSCP is the Online Certificate Status Manager instance name.
14.1.2.2. TLS Server Key Pair and Certificate
Server-Cert cert-
instance_ID, where instance_ID identifies the Online Certificate Status Manager instance name.
14.1.2.3. Subsystem Certificate
subsystemCert cert-
instance_ID.
14.1.2.4. Audit Log Signing Key Pair and Certificate
Note
14.1.2.5. Recognizing Online Certificate Status Manager Certificates
- If the Online Certificate Status Manager's server certificate is signed by the CA that is publishing CRLs, then nothing needs to be done.
- If the Online Certificate Status Manager's server certificate is signed by the same root CA that signed the subordinate Certificate Manager's certificates, then the root CA must be marked as a trusted CA in the subordinate Certificate Manager's certificate database.
- If the Online Certificate Status Manager's TLS server certificate is signed by a different root CA, then the root CA certificate must be imported into the subordinate Certificate Manager's certificate database and marked as a trusted CA.
Note
14.1.3. Key Recovery Authority Certificates
14.1.3.1. Transport Key Pair and Certificate
14.1.3.2. Storage Key Pair
14.1.3.3. TLS Server Certificate
Server-Cert cert-
instance_ID, where instance_id identifies the KRA instance is installed.
14.1.3.4. Subsystem Certificate
subsystemCert cert-
instance_ID.
14.1.3.5. Audit Log Signing Key Pair and Certificate
Note
14.1.4. TKS Certificates
14.1.4.1. TLS Server Certificate
Server-Cert cert-
instance_ID.
14.1.4.2. Subsystem Certificate
subsystemCert cert-
instance_ID.
14.1.4.3. Audit Log Signing Key Pair and Certificate
Note
14.1.5. TPS Certificates
14.1.5.1. TLS Server Certificate
Server-Cert cert-
instance_ID.
14.1.5.2. Subsystem Certificate
subsystemCert cert-
instance_ID.
14.1.5.3. Audit Log Signing Key Pair and Certificate
14.1.6. About Subsystem Certificate Key Types
pkispawn
utility.
Example 14.1. Key Type-related Configuration Parameters for a CA
pkispawn
when creating a new CA.
pki_ocsp_signing_key_algorithm=SHA256withRSA pki_ocsp_signing_key_size=2048 pki_ocsp_signing_key_type=rsa pki_ca_signing_key_algorithm=SHA256withRSA pki_ca_signing_key_size=2048 pki_ca_signing_key_type=rsa pki_sslserver_key_algorithm=SHA256withRSA pki_sslserver_key_size=2048 pki_sslserver_key_type=rsa pki_subsystem_key_algorithm=SHA256withRSA pki_subsystem_key_size=2048 pki_subsystem_key_type=rsa pki_admin_keysize=2048 pki_admin_key_size=2048 pki_admin_key_type=rsa pki_audit_signing_key_algorithm=SHA256withRSA pki_audit_signing_key_size=2048 pki_audit_signing_key_type=rsa
Note
- The Understanding the
pkispawn
Utility section in the Red Hat Certificate System Planning, Installation, and Deployment Guide (Common Criteria Edition). - The pki_default.cfg(5) man page for descriptions of the parameters and examples.
14.1.7. Using an HSM to Store Subsystem Certificates
key3.db
and cert8.db
, respectively, in the /var/lib/pki/instance_name/alias/
directory. However, Red Hat Certificate System also supports hardware security modules (HSM), external devices which can store keys and certificates in a centralized place on the network. Using an HSM can make some functions, like cloning, easier because the keys and certificates for the instance are readily accessible.
serverCert="nethsm:Server-Cert cert-instance_ID
Note
14.2. Renewing Subsystem Certificates
HttpClient
utility. For details about the different system certificate profiles, see Section 5.3.2.1, “Obtaining System and Server Certificates”.
14.2.1. Renewing Certificates Using certutil
certutil
can be used to generate a certificate request using an existing key pair in the certificate database. The new certificate request can then be converted to a CMC request to be submitted to the CA. For details, see Section 5.2.1, “Creating a CSR Using certutil
”.
Note
- Get the password for the token database.
cat /var/lib/pki/instance_name/conf/password.conf internal=263163888660
- Open the certificate database directory of the instance whose certificate is being renewed.
cd /var/lib/pki/instance_name/alias
- List the key and nickname for the certificate being renewed. In order to renew a certificate, the key pairs used to generate and the subject name given to the new certificate must be the same as the one in the old certificate.
# certutil -K -d . certutil: Checking token "NSS Certificate DB" in slot "NSS User Private Key and Certificate Services" Enter Password or Pin for "NSS Certificate DB": < 0> rsa 69481646e38a6154dc105960aa24ccf61309d37d caSigningCert cert-pki-tomcat CA
- Copy the
alias
directory as a backup, then delete the original certificate from the certificate database. For example:certutil -D -n "ServerCert cert-example" -d .
- Run the
certutil
command with the options set to the values in the existing certificate.certutil -d . -R -k "NSS Certificate DB:cert-pki-tomcat CA" -s "cn=CA Authority,o=Example Domain" -a -o example.req2.txt
The difference between generating a new certificate and key pair and renewing the certificate is the value of the-k
option. To generate an entirely new request and key pair, then-k
sets the key type and is used with-g
, which sets the bit length. For a renewal request, the-k
option uses the certificate nickname to access the existing key pair stored in the security database.For further details about the parameters, see the certutil(1) man page. - Submit the certificate request and then retrieve it and install it.
14.2.2. Renewing Expired Certificate System Server Certificates
- If the system certificate is expired:
- Create a temporary certificate:
# pki-server cert-create sslserver --temp
- Import the temporary certificate into Certificate System's Network Security Services (NSS) database:
# pki-server cert-import sslserver
- Start Certificate System:
# systemctl start pki-tomcatd-nuxwdog@instance_name.service
- Display the certificates and note the ID of the expired system certificate:
# pki-server cert-find
- Create the new permanent certificate:
# pki-server cert-create certificate_ID
- Stop Certificate System:
# systemctl stop pki-tomcatd-nuxwdog@instance_name.service
- Import the new certificate to replace the expired certificate:
# pki-server cert-import certificate_ID
- Start Certificate System:
# systemctl start pki-tomcatd-nuxwdog@instance_name.service
14.3. Changing the Names of Subsystem Certificates
CA Signing Certificate |
|
OCSP Signing Certificate |
|
Subsystem Certificate |
|
Server Certificate |
|
Audit Signing Certificate |
|
Transport Certificate |
|
Storage Certificate |
|
Server Certificate |
|
Subsystem Certificate |
|
Audit Log Signing Certificate |
|
OCSP Signing Certificate |
|
Server Certificate |
|
Subsystem Certificate |
|
Audit Log Signing Certificate |
|
KRA Transport Certificate[a] |
|
Server Certificate |
|
Subsystem Certificate |
|
Audit Log Signing Certificate |
|
[a]
This needs changed in the TKS configuration if the KRA transport certificate nickname changes, even if the TKS certificates all stay the same.
|
Server Certificate |
|
Subsystem Certificate |
|
Audit Log Signing Certificate |
|
14.4. Managing the Certificate Database
Note
certutil
can be used to manage the certificate database by editing trust settings and adding and deleting certificates. For details about this tool, see http://www.mozilla.org/projects/security/pki/nss/tools/.
14.4.1. Installing Certificates in the Certificate System Database
certutil
utility.
14.4.1.1. Installing Certificates through the Console
- Any of the certificates used by a Certificate System subsystem
- Any trusted CA certificates from external CAs or other Certificate System CAs
- Certificate chains
- Open the console.
pkiconsole https://server.example.com:secure_port/subsystem_type
- In the Configuration tab, select System Keys and Certificates from the left navigation tree.
- There are two tabs where certificates can be installed, depending on the subsystem type and the type of certificate.
- The CA Certificates tab is for installing CA certificates and certificate chains. For Certificate Managers, this tab is used for third-party CA certificates or other Certificate System CA certificates; all of the local CA certificates are installed in the Local Certificates tab. For all other subsystems, all CA certificates and chains are installed through this tab.
- The Local Certificates tab is where all server certificates, subsystem certificates, and local certificates such as OCSP signing or KRA transport are installed.
Select the appropriate tab. - To install a certificate in the Local Certificates tab, click . To install a certificate in the CA Certificates tab, click . Both will open the Certificate Setup Wizard.
- When the wizard opens, select the Install a certificate radio button, and click .
- Select the type of certificate to install. The options for the drop-down menu are the same options available for creating a certificate, depending on the type of subsystem, with the additional option to install a cross-pair certificate.
- Paste in the certificate body, including the
-----BEGIN CERTIFICATE-----
and-----END CERTIFICATE-----
, into the text area, or specify the absolute file location; this must be a local file.The certificate will look like the following:-----BEGIN CERTIFICATE----- MIICKzCCAZSgAwIBAgIBAzANgkqkiG9w0BAQQFADA3MQswCQYDVQQGEw JVUzERMA8GA1UEChMITmV0c2NhcGUxFTATBgNVBAsTDFN1cHJpeWEncy BDQTAeFw05NzEwMTgwMTM2MjVaFw05OTEwMTgwMTM2MjVaMEgxCzAJBg NVBAYTAlVTMREwDwYDVQQKEwhOZXRzY2FwZTENMAsGA1UECxMEUHawcz EXMBUGA1UEAxMOU3Vwcml5YSBTaGV0dHkwgZ8wDQYJKoZIhdfNAQEBBQ ADgY0AMIGJAoGBAMr6eZiPGfjX3uRJgEjmKiqG7SdATYzBcABu1AVyd7 chRFOGD3wNktbf6hRo6EAmM5R1Askzf8AW7LiQZBcrXpc0k4du+2j6xJ u2MPm8WKuMOTuvzpo+SGXelmHVChEqooCwfdiZywyZNmgaMa2MS6pUkf QVAgMBAAGjNjA0MBEGCWCGSAGG+EIBAQQEAwIAgD -----END CERTIFICATE-----
- The wizard displays the certificate details. Review the fingerprint to make sure this is the correct certificate, or use thebutton to go back and submit a different one. Give a nickname for the certificate.The wizard installs the certificate.
- Any CA that signed the certificate must be trusted by the subsystem. Make sure that this CA's certificate exists in the subsystem's certificate database (internal or external) and that it is trusted.If the CA certificate is not listed, add the certificate to the certificate database as a trusted CA. If the CA's certificate is listed but untrusted, change the trust setting to trusted, as shown in Section 14.5, “Changing the Trust Settings of a CA Certificate”.When installing a certificate issued by a CA that is not stored in the Certificate System certificate database, add that CA's certificate chain to the database. To add the CA chain to the database, copy the CA chain to a text file, start the wizard again, and install the CA chain.
14.4.1.2. Installing Certificates Using certutil
certutil
, do the following:
- Open the subsystem's security database directory.
cd /var/lib/pki/instance_name/alias
- Run the
certutil
command with the-A
to add the certificate and-i
pointing to the file containing the certificate issued by the CA.certutil -A -n cert-name -t trustargs -d . -a -i certificate_file
Note
If the Certificate System instance's certificates and keys are stored on an HSM, then specify the token name using the-h
option.For example:certutil -A -n "ServerCert cert-instance_name" -t u,u,u -d . -a -i /tmp/example.cert
certutil
command, see http://www.mozilla.org/projects/security/pki/nss/tools/certutil.html.
14.4.1.3. About CA Certificate Chains
14.4.2. Viewing Database Content
cert8.db
, can be viewed through the subsystem administrative console. Alternatively, the certificates can be listed using the certutil
utility. certutil
must be used to view the TPS certificates because the TPS subsystem does not use an administrative console.
Note
cert8.db
database are the subsystem certificates used for subsystem operations. User certificates are stored with the user entries in the LDAP internal database.
14.4.2.1. Viewing Database Content through the Console
- Open the subsystem console.
pkiconsole https://server.example.com:secure_port/subsystem_type
- In the Configuration tab, select System Keys and Certificates from the left navigation tree.
- There are two tabs, CA Certificates and Local Certificates, which list different kinds of certificates.
- CA Certificates lists CA certificates for which the corresponding private key material is not available, such as certificates issued by third-party CAs such as Entrust or Verisign or external Certificate System Certificate Managers.
- Local Certificates lists certificates kept by the Certificate System subsystem instance, such as the KRA transport certificate or OCSP signing certificate.
Figure 14.1. Certificate Database Tab
- The Certificate Database Management table lists the all of the certificates installed on the subsystem. The following information is supplied for each certificate:
- Certificate Name
- Serial Number
- Issuer Names, the common name (
cn
) of the issuer of this certificate. - Token Name, the name of the cryptographic token holding the certificate; for certificate stored in the database, this is
internal
.
14.4.2.2. Viewing Database Content Using certutil
certutil
, open the instance's certificate database directory, and run the certutil
with the -L
option. For example:
cd /var/lib/pki/instance_name/alias certutil -L -d . Certificate Authority - Example Domain CT,c, subsystemCert cert-instance name u,u,u Server-Cert cert-instance_name u,u,u
certutil
, run the certutil
with the -K
option. For example:
cd /var/lib/pki/instance_name/alias certutil -K -d . Enter Password or Pin for "NSS Certificate DB": <0> subsystemCert cert-instance_name <1> <2> Server-Cert cert-instance_name
certutil
command, see http://www.mozilla.org/projects/security/pki/nss/tools/certutil.html.
14.4.3. Deleting Certificates from the Database
Note
14.4.3.1. Deleting Certificates through the Console
- Open the subsystem console.
pkiconsole https://server.example.com:secure_port/subsystem_type
- In the Configuration tab, select System Keys and Certificates from the left navigation tree.
- Select the certificate to delete, and click.
- When prompted, confirm the delete.
14.4.3.2. Deleting Certificates Using certutil
certutil
:
- Open the instance's certificate databases directory.
/var/lib/pki/instance_name/al