2.7. Managing Subject Names and Subject Alternative Names

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 is built from standard LDAP directory components, such as email addresses, 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.

2.7.1. 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.17, “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, UidPwdDirAuth.
    1. Open the CA Console.
      pkiconsole https://server.example.com:9445/ca
    2. Select Authentication in the left navigation tree.
    3. In the Authentication Instance tab, click Add, and add an instance of the UidPwdDirAuth authentication plug-in.
    4. Set the information for the LDAP directory.
    5. Set the LDAP attributes to populate.
    6. Save the new plug-in instance.
    For information on configuring the LDAP authentication modules, see Section 9.2.1, “Setting up Directory-Based Authentication”.
  2. When the new authentication plug-in is added, the corresponding parameters are added to the CA's CS.cfg file. For example, this instance of the UidPwdDirAuth plug-in is set to populate the mail attribute:
     ...
     auths.instance.UserDirEnrollment.dnpattern=
     auths.instance.UserDirEnrollment.ldapByteAttributes=
     auths.instance.UserDirEnrollment.ldapStringAttributes=mail      
     auths.instance.UserDirEnrollment.pluginName=UidPwdDirAuth
     auths.instance.UserDirEnrollment.ldap.basedn=dc=example,dc=com
     auths.instance.UserDirEnrollment.ldap.maxConns=
     auths.instance.UserDirEnrollment.ldap.minConns=
     auths.instance.UserDirEnrollment.ldap.ldapconn.host=localhost
     auths.instance.UserDirEnrollment.ldap.ldapconn.port=389
     auths.instance.UserDirEnrollment.ldap.ldapconn.secureConn=false...
    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.
  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 caDirUser profile, do the following:
    cd /var/lib/subsystem_name/profiles/ca
    
    vi caDirUser.cfg
    
    policyset.setID.8.default.params.subjAltExtPattern_0=$request.auth_token.mail$
  4. Restart the CA.
    service pki-ca restart
For this example, certificates submitted through the caDirUser 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 2.6, “Variables Used to Populate Certificates”, and the default profiles contain examples for how these tokens are used.

Table 2.6. Variables Used to Populate Certificates

Policy Set Token Description
$request.auth_token.cn$ The LDAP common name (cn) attribute of the user who requested the certificate.
$request.auth_token.mail$ 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.user$
$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.profileRemoteAddr$ The IP address of the user making the request. This can be an IPv4 or an IPv6 address, depending on the client. An IPv4 address must be in the format n.n.n.n or n.n.n.n,m.m.m.m. For example, 128.21.39.40 or 128.21.39.40,255.255.255.00. An IPv6 address uses a 128-bit namespace, with the IPv6 address separated by colons and the netmask separated by periods. For example, 0:0:0:0:0:0:13.1.68.3, FF01::43, 0:0:0:0:0:0:13.1.68.3,FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:255.255.255.0, and FF01::43,FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FF00:0000.
$request.profileRemoteHost$ The hostname or IP address of the user's machine. The hostname can be the fully-qualified domain name and the protocol, such as http://server.example.com. An IPv4 address must be in the format n.n.n.n or n.n.n.n,m.m.m.m. For example, 128.21.39.40 or 128.21.39.40,255.255.255.00. An IPv6 address uses a 128-bit namespace, with the IPv6 address separated by colons and the netmask separated by periods. For example, 0:0:0:0:0:0:13.1.68.3, FF01::43, 0:0:0:0:0:0:13.1.68.3,FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:255.255.255.0, and FF01::43,FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FF00:0000.
$request.requestor_email$ The email address of the person who submitted the request.
$request.requestowner$ The person who submitted the request.
$request.subject$ The subject name DN of the entity to which the certificate is issued. For example, uid=jsmith, e=jsmith@example.com.
$request.tokencuid$ The card unique ID (CUID) of the smart card token used for requesting the enrollment.
$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$.

2.7.2. Changing DN Attributes in CA-Issued Certificates

In certificates issued by the Certificate System, DNs identify the entity that owns the certificate. In all cases, if the Certificate System is connected with a Directory Server, the format of the DNs in the certificates should match the format of the DNs in the directory. It is not necessary that the names match exactly; certificate mapping allows the subject DN in a certificate to be different from the one in the directory.
In the Certificate System, the DN is based on the components, or attributes, defined in the X.509 standard. Table 2.7, “Allowed Characters for Value Types” lists the attributes supported by default. The set of attributes is extensible.

Table 2.7. Allowed Characters for Value Types

Attribute Value Type Object Identifier
cn DirectoryString 2.5.4.3
ou DirectoryString 2.5.4.11
o DirectoryString 2.5.4.10
c PrintableString , two-character 2.5.4.6
l DirectoryString 2.5.4.7
st DirectoryString 2.5.4.8
street DirectoryString 2.5.4.9
title DirectoryString 2.5.4.12
uid DirectoryString 0.9.2342.19200300.100.1.1
mail IA5String 1.2.840.113549.1.9.1
dc IA5String 0.9.2342.19200300.100.1.2.25
serialnumber PrintableString 2.5.4.5
unstructuredname IA5String 1.2.840.113549.1.9.2
unstructuredaddress PrintableString 1.2.840.113549.1.9.8

By default, the Certificate System supports the attributes identified in Table 2.7, “Allowed Characters for Value Types”. This list of supported attributes can be extended by creating or adding new attributes. The syntax for adding additional X.500Name attributes, or components, is as follows:
X500Name.NEW_ATTRNAME.oid=n.n.n.n
X500Name.NEW_ATTRNAME.class=string_to_DER_value_converter_class
The value converter class converts a string to an ASN.1 value; this class must implement the netscape.security.x509.AVAValueConverter interface. The string-to-value converter class can be one of the following:
  • netscape.security.x509.PrintableConverter converts a string to a PrintableString value. The string must have only printable characters.
  • netscape.security.x509.IA5StringConverter converts a string to an IA5String value. The string must have only IA5String characters.
  • netscape.security.x509.DirStrConverter converts a string to a DirectoryString. The string is expected to be in DirectoryString format according to RFC 2253.
  • netscape.security.x509.GenericValueConverter converts a string character by character in the following order, from the smallest characterset to the largest:
    • Printable
    • IA5String
    • BMPString
    • Universal String
An attribute entry looks like the following:
X500Name.MY_ATTR.oid=1.2.3.4.5.6
X500Name.MY_ATTR.class=netscape.security.x509.DirStrConverter

2.7.2.1. Adding New or Custom Attributes

To add a new or proprietary attribute to the Certificate System schema, do the following:
  1. Stop the Certificate Manager.
    service pki-ca stop
  2. Open the /var/lib/pki-ca/conf directory.
  3. Open the configuration file, CS.cfg.
  4. Add the new attributes to the configuration file.
    For example, to add three proprietary attributes, MYATTR1 that is a DirectoryString, MYATTR2 that is an IA5String, and MYATTR3 that is a PrintableString, add the following lines at the end of the configuration file:
    X500Name.attr.MYATTR1.oid=1.2.3.4.5.6
    X500Name.attr.MYATTR1.class=netscape.security.x509.DirStrConverter
    X500Name.attr.MYATTR2.oid=11.22.33.44.55.66
    X500Name.attr.MYATTR2.class=netscape.security.x509.IA5StringConverter
    X500Name.attr.MYATTR3.oid=111.222.333.444.555.666
    X500Name.attr.MYATTR3.class=netscape.security.x509.PrintableConverter
    
  5. Save the changes, and close the file.
  6. Restart the Certificate Manager.
    service pki-ca start
  7. Reload the enrollment page and verify the changes; the new attributes should show up in the form.
  8. To verify that the new attributes are in effect, request a certificate using the manual enrollment form.
    Enter values for the new attributes so that it can be verified that they appear in the certificate subject names. For example, enter the following values for the new attributes and look for them in the subject name:
    MYATTR1: a_value
    MYATTR2: a.Value
    MYATTR3: aValue
    cn: John Doe
    o: Example Corporation
    
  9. Open the agent services page, and approve the request.
  10. When the certificate is issued, check the subject name. The certificate should show the new attribute values in the subject name.

2.7.2.2. Changing the DER-Encoding Order

It is possible to change the DER-encoding order of a DirectoryString, so that the string is configurable since different clients support different encodings.
The syntax for changing the DER-encoding order of a DirectoryString is as follows:
X500Name.dirStringEncodingOrder=encoding_list_separated_by_commas
The possible encoding values are as follows:
  • Printable
  • IA5String
  • UniversalString
  • BMPString
  • UTF8String
For example, the DER-encoding ordered can be listed as follows:
X500Name.dirEncodingOrder=Printable,BMPString
To change the DirectoryString encoding, do the following:
  1. Stop the Certificate Manager.
    service pki-ca stop
  2. Open the /var/lib/pki-ca/conf/ directory.
  3. Open the CS.cfg configuration file.
  4. Add the encoding order to the configuration file.
    For example, to specify two encoding values, PrintableString and UniversalString, and the encoding order is PrintableString first and UniversalString next, add the following line at the end of the configuration file:
    X500Name.directoryStringEncodingOrder=PrintableString, UniversalString
    
  5. Save the changes, and close the file.
  6. Start the Certificate Manager.
    service pki-ca start
  7. To verify that the encoding orders are in effect, enroll for a certificate using the manual enrollment form. Use John_Doe for the cn.
  8. Open the agent services page, and approve the request.
  9. When the certificate is issued, use the dumpasn1 tool to examine the encoding of the certificate. The dumpasn1 tool can be downloaded at http://fedoraproject.org/extras/4/i386/repodata/repoview/dumpasn1-0-20050404-1.fc4.html.
    The cn component of the subject name should be encoded as a UniversalString.
  10. Create and submit a new request using John Smith for the cn.
    The cn component of the subject name should be encoded as a PrintableString.

2.7.3. Customizing the Subject DN in a Certificate Request Issued by an RA

By default, the DN is taken from the input provided by the user on the User Enrollment page, specifically "UID" and "Your Email." For example, "UID=yourUID, E=youremail@example.com". You can customize the DN by editing the user.vm file for the RA.

IMPORTANT

Firefox and Internet Explorer use different certificate formats. Therefore, the modifications required are slightly different, depending on the browser the end users will be using.

2.7.3.1. Customizing the Subject DN in a Certificate Request for Firefox

Firefox uses CRMF format for certificate requests.
  1. Edit the user.vm file. By default, this is located in the /var/lib/pki-ra/docroot/ee/user/ directory.
  2. Locate the validate function and form the preferred DN in the var dn= statement. For example:
    var dn = "uid="+x+".e="+e;
    x is the UID and e is the email.

    WARNING

    The Subject DN must match the pattern specified in the Subject Name Constraint definition of the enrollment profile. The default user enrollment profile is specified by /var/lib/pki-ca/profiles/ca/caDualRAuserCert.cfg.
    For example:
    policyset.userCertSet.1.constraint.name=Subject Name Constraint
    policyset.userCertSet.1.constraint.params.pattern=UID=.*
    policyset.userCertSet.1.constraint.params.accept=true
    Using this definition, certificates are only issued if the subject name matches the pattern "UID=.*". Otherwise, the certificate request is rejected.
  3. Add any custom fields to the enrollment form, so that the enrollment form requests all of the information required to form the custom DN. The request form only requests the UID, site ID, and email. The enrollment form is defined at the end of the user.vm file. For example:
    <tr>
    <td>District:</td>
    <td><input type=text name=district value=""></td>
    </tr>
    
  4. Save the user.vm file.
  5. Restart the RA.
    service pki-ra restart

2.7.3.2. Customizing the Subject DN in a Certificate Request for Internet Explorer

Internet Explorer uses PKCS#10 format for certificate requests.
  1. Edit the user.vm file to add the new subject DN format and the updated enrollment form as described in Section 2.7.3.1, “Customizing the Subject DN in a Certificate Request for Firefox”.
  2. To configure the certificate request to have the appropriate PKCS#10 format for Internet Explorer, edit the Sub Send_OnClick function in the Visual Basic blob in user.vm. Form the preferred DN in the szName statement. For example, to add the organization (O=) element to the subject DN:
     ' Contruct the X500 distinguished name
       szName = "0.9.2342.19200300.100.1.1=" & TheForm.uid.Value & ",E=" &
    TheForm.email.Value & ",CN=" & TheForm.cn.Value & ",O=" & TheForm.org.Value"
  3. Save the user.vm file.
  4. Restart the RA.
    service pki-ra restart