Chapter 8. Authentication for Enrolling Certificates

8.1. Automatic Approval by an Authentication Plug-in

The 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

For instructions on how to edit certificate enrollment profiles, see Section 3.2, “Setting up Certificate Profiles”.

8.1.1. Setting up Auto-approval of Enrollment Requests

Configuring that enrollment requests are automatically approved depends on the type of requests:
  • For agent-pre-approved CMC requests, set in the CA profile: 
    auth.instance_id=CMCAuth
authz.acl=group="Certificate Manager Agents"
    The authz.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
For details about editing a profile, see Section 3.2, “Setting up Certificate Profiles”.

8.1.2. 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: 
auth.instance_id=CMCAuth
By default, the following enrollment profiles use the CMCAuth 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 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.
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 the CMCUserSignedAuth plug-in:
  • caFullCMCUserSignedCert
  • caECFullCMCUserSignedCert
  • caFullCMCSharedTokenCert
  • caECFullCMCSharedTokenCert

8.1.3. CMC SharedSecret Authentication

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.

8.1.3.1. Creating a Shared Secret Token

The The Shared Secret Workflow section in the Red Hat Certificate System Planning, Installation, and Deployment Guide (Common Criteria Edition) 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 Enabling the CMC Shared Secret Feature section located in RHCS Planning, Installation, and Deployment Guide.
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 8.1.3.2, “Setting a CMC Shared Secret”.

8.1.3.2. 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 The Shared Secret Workflow section in the Red Hat Certificate System Planning, Installation, and Deployment Guide (Common Criteria Edition).
8.1.3.2.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
8.1.3.2.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