Subject Distinguished Names

The subject DN field together with the subject alternative name fields identifies the entity associated with the public key stored in the certificate.

General

A subject DN can consist of a number of standardized components, for example:

Component

Description

A personal digital signature certificate

CN=Firstname Lastname,SURNAME=Lastname,GIVENNAME=Firstname,SERIALNUMBER=213243-1234,C=SE

An organization login certificate

CN=Firstname Lastname,UID=firstnamelastname,OU=Finance,O=Organization,C=DE

A web server certificate

CN=www.mydomain.com

An extended validation web server certificate (usage of CN is discouraged but not prohibited as of EV Guidelines 1.6.8, march 2019)

SERIALNUMBER=5566283064,OU=Infra,O=PrimeKey Solutions AB,POSTALCODE=17163,STREETADDRESS=Lundagatan 16,BUSINESSCATEGORY=Private Organization,L=Solna,jurisdictionCountry=SE,C=SE

An IoT device certificate

CN=DeviceID

EJBCA has a fixed cap of 400 characters for the entire Subject DN, including certain UTF-8 characters which may require two or three characters to encode. If you wish to change the character limit, manually modify the size of the subjectDN column in the CertificateData table in the database.

To view all known, standard, DN components in EJBCA, inspect the file src/java/dncomponents.properties.sample or DnComponents,java. New fields are occasionally invented by various organizations, and when needed the supported components in EJBCA are updated.

Subject DNs must be well formed when entered into EJBCA, whether it is via an API such as Web Service, or via the CLI, or Web GUI.

The following display examples of badly formatted DN strings:

  • Non-escaped commas are not allowed in values

    • C=SE,O=Foo\\, Inc, OU=Foo, Dep, CN=Foo

    • Is not valid due to the non-escaped comma in 'Foo, Dep' and the non-escaped '-character in the end.'

  • Plus- and equal signs in values must be escaped

    • CN=user\+name\=bar

  • DN component with a trailing comma is not allowed.

    • CN=name,

  • All parts of the DN must be legal

    • SURNAME=Json,=fff,CN=oid

    • '=fff' is not valid.

  • Invalid OIDs are not allowed in DNs

    • CN=CommonName,3.3.3.3=3333Oid,O=Org

    • '3.3.3.3' is not a valid OID

  • Invalid DN components are not allowed in DNs

    • CN=CommonName,K=abc,O=Org

    • 'K' is not a valid DN component

Empty DN component parts are still allowed.

  • 'CN=' will result in 'CN=' and not give an error

  • An empty string, '', is not a valid DN, but when converting an empty DN string to an EJBCA DN String (API), it will return empty and is allowed in order to support certificates and CSRs with no subjectDN (usually only with a subjectAltName).

As an example of escaping, this is an example of issuing a certificate with equals sign, using WS. The following command can be used with clientToolBox:

./ejbcaClientToolBox.sh EjbcaWsRaCli certreq username "CN=MyName\\=12345" null ManagementCA EMPTY ENDUSER csr.pem PKCS10 PEM NONE .

Note the double escaping is due to Java/Shell. The above command results in a SOAP request with an escaped equals sign:

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/"><S:Body><ns2:certificateRequest xmlns:ns2="http://ws.protocol.core.ejbca.org/"><arg0><caName>ManagementCA</caName><certificateProfileName>ENDUSER</certificateProfileName><clearPwd>false</clearPwd><endEntityProfileName>EMPTY</endEntityProfileName><keyRecoverable>false</keyRecoverable><sendNotification>false</sendNotification><status>0</status><subjectDN>CN=MyName\=12345</subjectDN><username>username</username></arg0><arg1>-----BEGIN CERTIFICATE REQUEST-----
<snip>
-----END CERTIFICATE REQUEST-----
</arg1><arg2>0</arg2><arg4>CERTIFICATE</arg4></ns2:certificateRequest></S:Body></S:Envelope>

Subject DN Order

In a certificate, the order of the DN components (CN,O,C etc) can be placed in a different order in the binary encoded certificate.

  • Last-to-first, forward (historically called LDAP DN Order in EJBCA): CN=Common Name, O=Organization, C=Country

  • First-to-last, reverse order: C=Country, O=Organization, CN=Common name

Note that when using string representation of DNs, the actual order is usually not displayed. The order displayed is determined by the tool being used and may be the reverse of the real binary order. To see the actual binary order, an asn1 parsing tool can be used, such as OpenSSL. In practice, the DN order can be important because comparisons are often made using string compilations, where the string value may be dependent on the order.

The most common order is first-to-last (i.e. C,O,CN), but for historical reasons EJBCA by default uses last-to-first (CN,O,C). You can choose which DN Order to use in the Certificate Profile Fields.

Multi-value RDNs

As of EJBCA 7.0.0, multi-value Relative Distinguished Names (RDNs) are handled internally in EJBCA. However, multi-value RDNs are not allowed in End Entity Profile validations by default and must be configured to be allowed in order to be used.

Only use multi-value RDNs when you have a strong reason to do so (certificate policy requirement or unique names). Typically, federal governments use multi-value RDNs due to their strict certificate policies. It is recommended to avoid using multi-value RDNs unless you have a specific requirement to implement it and understand the ramifications for doing so.

To limit the risk of damage caused by multi-value RDNs, only the following DN components are allowed to be used in multi-value constructs, even if you have allowed usage of multi-value RDNs in the end entity profile:

  • Common Name (CN)

  • Serial number (SN)

  • Surname (SURNAME)

  • Unique Identifier (UID)

  • Given name (GIVENNAME)

  • DN Qualifier (DN_QUALIFIER)

If you nevertheless have to use multi-value RDNs, the following displays usage examples.

The first step is to configure the End Entity profile to allow multi-value RDNs, and to add the needed fields.

  • Allow multi-value RDNs: True

  • Add at least CN and UID as Subject DN Attributes. Only fields available in the End Entity Profile can be used in a multi-value RDN

If you have not enabled multi-value RDNs, or did not add the used DN attributes, for example UID, you will get one of these error messages:

  • Given userdata doesn't fulfill end entity profile. : Subject DN has multi value RDNs, which is not allowed.
  • Given userdata doesn't fulfill end entity profile. : Wrong number of UID fields in Subject DN.

Issuing certificates with multi-value RDN

It is currently not possible to register end entities i.e. enroll, with the Web UIs for multi-value RDNs. If you add an end entity using for example the CLI, you can finalize enrollment (download the certificate) in the Web UI, but registration can not be done there.

You can issue certificates with multi-value RDNs using most APIs.

Command Line Interface

bin/ejbca.sh ra addendentity --username multirdn1 --dn "CN=Tomas+UID=12345,O=PK,C=SE" --caname "ManagementCA" --type 1 --token PEM
bin/ejbca.sh ra setclearpwd multirdn1 foo123
bin/ejbca.sh batch multirdn1
 
openssl asn1parse -in p12/pem/Tomas.pem -i
135:d=3 hl=2 l= 35 cons: SET
137:d=4 hl=2 l= 12 cons: SEQUENCE
139:d=5 hl=2 l= 3 prim: OBJECT :commonName
144:d=5 hl=2 l= 5 prim: UTF8STRING :Tomas
151:d=4 hl=2 l= 19 cons: SEQUENCE
153:d=5 hl=2 l= 10 prim: OBJECT :userId
165:d=5 hl=2 l= 5 prim: UTF8STRING :12345
172:d=3 hl=2 l= 11 cons: SET
174:d=4 hl=2 l= 9 cons: SEQUENCE
176:d=5 hl=2 l= 3 prim: OBJECT :organizationName
181:d=5 hl=2 l= 2 prim: UTF8STRING :PK
185:d=3 hl=2 l= 11 cons: SET
187:d=4 hl=2 l= 9 cons: SEQUENCE
189:d=5 hl=2 l= 3 prim: OBJECT :countryName
194:d=5 hl=2 l= 2 prim: PRINTABLESTRING :SE

Web Service API

A clientToolBox command to issue a certificate with multi-value RDN is:

./ejbcaClientToolBox.sh EjbcaWsRaCli certreq multirdn4 "CN=Tomas+UID=12345,O=PK,C=SE" null ManagementCA User Client csr.pem PKCS10 PEM NONE .

Which produces the following SOAP code:

<?xml version="1.0" ?><S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/"><S:Body><ns2:certificateRequest xmlns:ns2="http://ws.protocol.core.ejbca.org/"><arg0><caName>ManagementCA</caName><certificateProfileName>Client</certificateProfileName><clearPwd>false</clearPwd><endEntityProfileName>User</endEntityProfileName><keyRecoverable>false</keyRecoverable><sendNotification>false</sendNotification><status>0</status><subjectDN>CN=CN=Tomas+UID=12345,O=PK,C=SE</subjectDN><username>multirdn4</username></arg0><arg1>
...<snip>...
</arg1><arg2>0</arg2><arg4>CERTIFICATE</arg4></ns2:certificateRequest></S:Body></S:Envelope>

CMP

An example using the EJBCA cmpclient working with a CMP alias in RA mode:

java -jar cmpclient.jar crmf --dn "CN=Tomas+UID=12345,O=PK,C=SE" --url http://127.0.0.1:8080/ejbca/publicweb/cmp --authparam password --reqnewkeyspec RSA2048

REST API

Using the Certificate Management REST API, a CSR with the proper multi-value RDN must first be created.

openssl req -newkey rsa:2048 -subj "/CN=Tomas+UID=12345/O=PK/C=SE" -multivalue-rdn -nodes -out csr.pem

And then make the REST API request:

curl -X POST "https://localhost:8443/ejbca/ejbca-rest-api/v1/certificate/pkcs10enroll" -H "accept: application/json" -H "Content-Type: application/json" --insecure --cert cert-superadmin.pem --key key-superadmin.pem -d "{ \"certificate_request\": \"-----BEGIN CERTIFICATE REQUEST-----\nMIIChDCCAWwCAQAwPzEjMAwGA1UEAwwFVG9tYXMwEwYKCZImiZPyLGQBAQwFMTIz\nNDUxCzAJBgNVBAoMAlBLMQswCQYDVQQGEwJTRTCCASIwDQYJKoZIhvcNAQEBBQAD\nggEPADCCAQoCggEBANH1SrgN3q/yt7Ebf9HIeJQHtxhIO6zdLbQIHhXkp3BWT2Lb\ncxOhejt2oN6FGab1vB4xHFkXpDQDfX+3Rx5hboDBd2hfsDMK6HGEihrc0gtq9jpr\nAWtbeXeR/sKLol9cVT7/tGKzWM7cyac/aotaaeXpQlrq+fV4wKqLEs4ivrKZb8yy\nd6BYLX18alnoRTZO18YlwrseaoGsWjoECTbu9Jc4vSbXKTxoxRRHBpp7zdFmY2x3\neFA6w8T5dwwEDa3Xo2hbz9diKZ+sicJMMrKgBnkv9OsK4qs2YX1gq6Ii1yrCLSf9\nFvj3goawmQlZjOcX+z89otW2dVC1Ha5oW5yn3QUCAwEAAaAAMA0GCSqGSIb3DQEB\nCwUAA4IBAQBD3MFg0e31gFn/+whfqU7uVgIQLl1M8X32wQ0ouyb0pbA/OSnHbZQF\nsAQi6aIaEBDT1ZLMVNOjBKy7GdBrBpyvApIKMIaghB9Xi8BEL7wvS9oG370XxG4k\nIrVWMdfbdAvKZXpvnu2VrlCZsqt+G0gLvI2gpRMiamdkc/luhzCmCeGOQGKEJ/36\nzuz1ATLry7kPA118G0j7YZj78LImGlJTv3nWd9AA/VgC5vPauutfHN/3Cho3ghUH\ndgPgHiQMz57cQv4VVwkj5IOWrhgcm+d4scJNyRdYWQ1SaB0AA+iSzZxVGB6Oe0ww\nVQEmeF9s5sNmHiZrFDJTvOOK3Q5OBY4f\n-----END CERTIFICATE REQUEST-----\", \"certificate_profile_name\": \"Client\", \"end_entity_profile_name\": \"User\", \"certificate_authority_name\": \"ManagementCA\", \"username\": \"multirdn5\", \"password\": \"foo123\"}"

Using multi-value RDNs for Administrators

You can use certificates with multi-value RDNs as administrator certificates in EJBCA in the standard way, where the components are counted as separate. For example adding the certificate with a DN of "CN=Tomas+UID=123456" to a Role can be done by using:

  • match with: CN

  • match value: Tomas
    or

  • match with: UID

  • match value: 12345

Using Subset of Subject DN with multi-value RDNs

Issuing certificates using the Subset of Subject DN feature in certificate profiles may not work as expected when using multi-value RDNs. When using this feature, the multi-value RDN is separated into single value RDNs. If you submit an RDN "CN=Tomas+UID=12345" the result will be:

  • When only CN is selected as Subject of Subject DN: CN=Tomas

  • When only UID is selected as Subject of Subject DN: UID=12345

  • When both CN and UID is selected as Subject of Subject DN: CN=Tomas, UID=12345 (not this is not a multi-value RDN any more)

Publishing multi-value RDNs to LDAP

LDAP Publishing with multi-value RDNs has not been tested.