12.11. Configuration for CMC

This section describes how to configure Certificate System for Certificate Management over CMS (CMC).

12.11.1. Understanding How CMC Works

Before configuring CMC, read the following documentation to learn more about the subject:

12.11.2. CMC Authentication

This section describes the authentication mechanisms Certificate System provides for CMC enrollment and situations in which they are used:

12.11.2.1. CMC Authentication Plug-ins

Certificate System provides the following 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 stored in the /var/lib/pki/instance_name/ca/profiles/ca/ directory: 
auth.instance_id=CMCAuth
By default, the following enrollment profiles use the CMCAuth plug-in:
  • For system certificates:
    • caCMCauditSigningCert
    • caCMCcaCert
    • caCMCserverCert
    • caCMCsubsystemCert
    • caCMCocspCert
    • caCMCkraStorageCert
    • caCMCkraTransportCert
    • caCMCECserverCert
    • caCMCECsubsystemCert
  • For user certificates:
    • caCMCUserCert
CMCUserSignedAuth
Use this plug-in when users submit signed or unsigned CMC requests.
To use the CMCUserSignedAuth plug-in, set the following in the enrollment profile stored in the /var/lib/pki/instance_name/ca/profiles/ca/ directory: 
auth.instance_id=CMCUserSignedAuth
A user-signed CMC request must be signed by the user's certificate which contains the same subjectDN 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.
An unsigned CMC request, which is also called a self-signed 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. An unsigned 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 12.11.4, “The CMC Shared Secret Feature”.
By default, the following enrollment profiles use the CMCUserSignedAuth plug-in:
  • caFullCMCUserSignedCert
  • caECFullCMCUserSignedCert
  • caFullCMCSelfSignedCert
  • caECFullCMCSelfSignedCert

12.11.3. Enabling the PopLinkWittnessV2 Feature

For a high-level security on the Certificate Authority (CA), enable the following option in the /var/lib/pki/instance_name/ca/conf/CS.cfg file: 
cmc.popLinkWitnessRequired=true

12.11.4. The CMC Shared Secret Feature

Use the Shared Secret feature to enable users to send unsigned CMC requests to the server. For example, this is necessary if a user wants to obtain the first signing certificate. This signing certificate can later be used to sign other certificates of this user.

12.11.4.1. Enabling the CMC Shared Secret Feature

To enable the shared token feature in a Certificate Authority (CA):
  1. Add the shrTok attribute to Directory Server's schema: 
    # ldapmodify -D "cn=Directory Manager" -H ldaps://server.example.com:636 -W -x

dn: cn=schema
changetype: modify
add: attributetypes
attributetypes: ( 2.16.840.1.117370.3.1.123 NAME 'shrTok' DESC 'User
 Defined ObjectClass for SharedToken' SYNTAX 1.3.6.1.4.1.1466.115.121.1.40
 SINGLE-VALUE X-ORIGIN 'custom for sharedToken')
  2. If the system keys are stored on a Hardware Security Module (HSM), set the cmc.token parameter in the /var/lib/pki/instance_name/ca/conf/CS.cfg file. For example: 
    cmc.token=NHSM6000
  3. Enable the shared token authentication plug-in by using one of the following methods:
    • To enable the plug-in using the pkiconsole utility:
      1. Log into the system using the pkiconsole utility. For example: 
        # pkiconsole https:host.example.com:8443/ca
      2. On the Configuration tab, select Authentication.
      3. Click Add and select SharedToken.
      4. Click Next.
      5. 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
      6. Click OK.
    • To manually enable the plug-in, add the following settings into the /var/lib/pki/instance_name/ca/conf/CS.cfg file: 
      auths.impl.SharedToken.class=com.netscape.cms.authentication.SharedSecret
auths.instance.SharedToken.dnpattern=
auths.instance.SharedToken.ldap.basedn=ou=People,dc=example,dc=org
auths.instance.SharedToken.ldap.ldapauth.authtype=BasicAuth
auths.instance.SharedToken.ldap.ldapauth.bindDN=cn=Directory Manager
auths.instance.SharedToken.ldap.ldapauth.bindPWPrompt=Rule SharedToken
auths.instance.SharedToken.ldap.ldapauth.clientCertNickname=
auths.instance.SharedToken.ldap.ldapconn.host=server.example.com
auths.instance.SharedToken.ldap.ldapconn.port=636
auths.instance.SharedToken.ldap.ldapconn.secureConn=true
auths.instance.SharedToken.ldap.ldapconn.version=3
auths.instance.SharedToken.ldap.maxConns=
auths.instance.SharedToken.ldap.minConns=
auths.instance.SharedToken.ldapByteAttributes=
auths.instance.SharedToken.ldapStringAttributes=
auths.instance.SharedToken.pluginName=SharedToken
auths.instance.SharedToken.shrTokAttr=shrTok
  4. Set the nickname of an RSA issuance protection certificate in the ca.cert.issuance_protection.nickname parameter in the /var/lib/pki/instance_name/ca/conf/CS.cfg file. For example: 
    ca.cert.issuance_protection.nickname=issuance_protection_certificate
    This step is:
    • Optional if you use an RSA certificate in the ca.cert.subsystem.nickname parameter.
    • Required if you use an ECC certificate in the ca.cert.subsystem.nickname parameter.

    Important

    If the ca.cert.issuance_protection.nickname parameter is not set, Certificate System automatically uses the certificate of the subsystem specified in the ca.cert.subsystem.nickname. However, the issuance protection certificate must be an RSA certificate.
  5. Restart Certificate System: 
    # systemctl restart pki-tomcatd@instance_name.service

12.11.4.2. Creating a Shared Secret Token

The Shared Secret Workflow section in the Red Hat Certificate System Planning, Installation, and Deployment Guide describes the workflow when using a Shared Secret Token. Depending on the situation, either an end entity user or an administrator creates the Shared Secret Token.

Note

To use the shared secret token, Certificate System must use an RSA issuance protection certificate. For details, see Section 12.11.4.1, “Enabling the CMC Shared Secret Feature”.
To create a Shared Secret Token, enter: 
# CMCSharedToken -d /home/user_name/.dogtag/ -p NSS_password \
     -s "CMC_enrollment_password" -o /home/user_name/CMC_shared_token.b64 \
     -n "issuance_protection_certificate_nickname"
If you use an HSM, additionally pass the -h token_name option to the command to set the HSM security token name.
For further details about the CMCSharedToken utility, see the CMCSharedToken(8) man page.

Note

The generated token is encrypted and only the user who generated knows the password. If a CA administrator generates the token for a user, the administrator must provide the password to the user using a secure way.
After creating the Shared Token, an administrator must add the token to a user or certificate record. For details, see Section 12.11.4.3, “Setting a CMC Shared Secret”.

12.11.4.3. Setting a CMC Shared Secret

Depending on the planned action, an administrator must store a Shared Secret Token after generating it in the LDAP entry of the user or certificate.
For details about the workflow and when to use a Shared Secret, see The Shared Secret Workflow in the Red Hat Certificate System Planning, Installation, and Deployment Guide.
12.11.4.3.1. Adding a CMC Shared Secret to a User Entry for Certificate Enrollment
To use the Shared Secret Token for certificate enrollment, store it as an administrator in the LDAP entry of the user: 
# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x

dn: uid=user_name,ou=People,dc=example,dc=com
changetype: modify
replace: shrTok
shrTok: base64-encoded_token
12.11.4.3.2. Adding a CMC Shared Secret to a Certificate for Certificate Revocations
To use the Shared Secret Token for certificate revocations, store it as an administrator in the LDAP entry of the certificate to be revoked: 
# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x

dn: cn=certificate_id,ou=certificateRepository,ou=ca,o=pki-tomcat-CA
changetype: modify
replace: shrTok
shrTok: base64-encoded_token