Search
SupportConsoleDevelopersStart a trialContact

3.7. Managing Subject Names and Subject Alternative Names

download PDF
The subject name of a certificate is a distinguished name (DN) that contains identifying information about the entity to which the certificate is issued. This subject name can be built from standard LDAP directory components, such as common names and organizational units. These components are defined in X.500. In addition to — or even in place of — the subject name, the certificate can have a subject alternative name, which is a kind of extension set for the certificate that includes additional information that is not defined in X.500.
The naming components for both subject names and subject alternative names can be customized.

Important

If the subject name is empty, then the Subject Alternative Name extension must be present and marked critical.

3.7.1. Using the Requester CN or UID in the Subject Name

The 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.
There are two parts to this configuration:
  • 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.
For example, to use the CN in the subject DN: 
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
In this example, if a request comes in with the CN of 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.
The same configuration is used to pull the requester UID into the subject DN: 
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
The format for the 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

Information from an LDAP directory or that was submitted by the requester can be inserted into the subject alternative name of the certificate by using matching variables in the Subject Alt Name Extension Default configuration. This default sets the type (format) of information and then the matching pattern (variable) to use to retrieve the information. For example: 
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
This inserts the requester's email as the first CN component in the subject alt name. To use additional components, increment the Type_, Pattern_, and Enable_ values numerically, such as Type_1.
Configuring the subject alt name is detailed in Section B.1.24, “Subject Alternative Name Extension Default”, as well.
To insert LDAP components into the subject alt name of the certificate:
  1. Inserting LDAP attribute values requires enabling the user directory authentication plug-in, SharedSecret.
    1. Open the CA Console. 
      pkiconsole https://server.example.com:8443/ca
    2. Select Authentication in the left navigation tree.
    3. In the Authentication Instance tab, click Add, and add an instance of the SharedSecret authentication plug-in.
    4. 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
    5. 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”.
  2. The ldapStringAttributes parameter instructs the authentication plug-in to read the value of the mail 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 the dnpattern parameter is covered in Section B.2.11, “Subject Name Constraint” and Section B.1.28, “Subject Name Default”.
  3. 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 the caFullCMCSharedTokenCert 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”.
  4. Restart the CA. 
    systemctl restart pki-tomcatd-nuxwdog@instance_name.service
For this example, certificates submitted through the 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
There are many attributes which can be automatically inserted into certificates by being set as a token ($X$) in any of the 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.
Table 3.1. Variables Used to Populate Certificates
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

Several client applications and libraries no longer support using the Common Name (CN) attribute of the Subject DN for domain name validation, which has been deprecated in RFC 2818. Instead, these applications and libraries use the dNSName Subject Alternative Name (SAN) value in the certificate request.
Certificate System copies the CN only if it matches the preferred name syntax according to RFC 1034 Section 3.5 and has more than one component. Additionally, existing SAN values are preserved. For example, the dNSName value based on the CN is appended to existing SANs.
To configure Certificate System to automatically use the CN attribute in the SAN extension, edit the certificate profile used to issue the certificates. For example:
  1. Disable the profile: 
    # pki -c password -p 8080 \
     -n "PKI Administrator for example.com" ca-profile-disable profile_name
  2. Edit the profile: 
    # pki -c password -p 8080 \
     -n "PKI Administrator for example.com" ca-profile-edit profile_name
    1. 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 uses 12 as the set number.
    2. 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
    3. Save the profile.
  3. Enable the profile: 
    # pki -c password -p 8080 \
     -n "PKI Administrator for example.com" ca-profile-enable profile_name

Note

All default server profiles contain the commonNameToSANDefaultImpl default.

3.7.4. Accepting SAN Extensions from a CSR

In certain environments, administrators want to allow specifying Subject Alternative Name (SAN) extensions in Certificate Signing Request (CSR).

3.7.4.1. Configuring a Profile to Retrieve SANs from a CSR

To allow retrieving SANs from a CSR, use the User Extension Default. For details, see Section B.1.33, “User Supplied Extension Default”.

Note

A SAN extension can contain one or more SANs.
To accept SANs from a CSR, add the following default and constraint to a profile, such as 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

For example, to generate a CSR with two SANs using the 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
After generating the CSR, follow the steps described in Section 5.3.1, “The CMC Enrollment Process” to complete the CMC enrollment.
Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.