Username Field

The Username value represents an unique identifier for an end entity (user, server, device, etc). During the operation of adding an end entity username can be manually set or automatically generated. Selecting the Auto-generated checkbox in the end entity profile will generate unique values when end entities are added.

Password Field

Passwords are used when a user (end entity) is requesting a certificate and/or when generating a keystore. Usually this is required, and no default value is configured. When the password is only used during the request procedure, this is called an Enrollment Code in the public web, since the password is only valid once and not used to protect the keys. Note that there is no difference between an Enrollment Code and a Password other than the name.

You can use auto-generation of passwords with email notification to send the user a generated password together with information on how to fetch the certificate.

You can also specify the minimum bit-strength a password is allowed to have in order to make policy compliance easier. The strength of a password is calculated as

floor(( the number characters in the password )*log₂( number of allowed password characters ))

For non-generated passwords the number of allowed password characters is estimated to 72.

Example usage:

Password: "foobar123" (9 characters)
Allowed characters: a-z, A-Z, 0-9, 22 additional printable characters (72 in total)
Password strength / char: log2(72) = 6.17
Password strength: floor(6.17 * 9) = floor(55.53) = 55 bits

Setting this value to 55 will require the RA admin to set a 9 character password or longer.

Subject DN Fields

Subject DN fields define which DN components should be present for an end entity. If the System Configuration option Enable End Entity Profile Limitations is enabled, this restricts the values that can be used when adding or editing an end entity using all interfaces, be it web GUI, web service, CMP or something else. If you define values as required and non-modifiable, you can specify one or more values. If you specify multiple values separated by ';', the admin in the Web GUI will get a drop-down list menu to select from.

In the Validation field you may restrict the allowed input, using a regular expression (regex). EJBCA uses Java Pattern syntax, which is similar to the Perl regex syntax. Matching is case sensitive by default, but this can be changed by adding (?i) in front of the regex. Here are some examples:

• [0-9]+ allows digits only

• [0-9A-Za-z]+ allows digits and English letters only, no spaces

• [0-9A-Za-z ]+ allows digits and English letters and spaces

• .+@.+ allows strings containing "@", for example e-mail addresses

• [a-zA-Z0-9+._-]+@[a-zA-Z0-9.-]+ allows e-mail addresses with English characters only

• [a-zA-Z0-9+._-]+@yourdomain\.com allows only e-mails from a specific domain

• [a-zA-Z0-9._-]+\.yourdomain\.com allows only subdomains of yourdomain.com (but not yourdomain.com itself)

• ([a-zA-Z0-9._-]+\.)?yourdomain\.com allows yourdomain.com with or without a subdomain

When having several fields of a certain type with mixed required and not required fields some special handling might be needed when adding users using web service API. If you have for example:

• The first OU field is required (Bar1) and not modifiable.

• The next 3 OU fields are modifiable only (not required).

• The last OU is required (Bar1) and not modifiable.

Then when adding an end entity with DN "CN=Foo,OU=Bar1,OU=Bar2" will result in an error like the following:

This is because EJBCA cannot keep track of which fields you mean to set, if it is one of the required or non-required. To help EJBCA determine this you can specify the non-required OU fields with empty values, "CN=Foo,OU=Bar1,OU=,OU=,OU=,OU=Bar2".

There is one particular subject DN field that deserves extra information, postalAddress.

PostalAddress is not encoded as a string, but is an ASN.1 sequence. If you only enter the value as a string it will be encoded as a simple UTF8String, which is invalid. You need to enter is as a hex encoded ASN.1 DirectoryString. This is done by hex encoding the ASN.1 object and pre-pending it with #, i.e. #30...

Subject Alternative Names

Subject alternative names (altNames) are extra naming items that are not fit to have in the Distinguished Name, such as email, dns, ip address etc. There are a number of standard ones, and the possibility to define special ones, which many companies have done for altNames such as MS UPN, GUID, Krb5PrincipalName.

Subject alternative names can be: rfc822Name=<email>, dNSName=<host name>, uri=<http://host.com/>, ipaddress=<address>, upn=<MS UPN>, guid=<MS globally unique id>, directoryName=<LDAP escaped DN>, krb5principal=<Krb5 principal name>, permanentIdentifier=<Permanent Identifier values>, subjectIdentificationMethod=<Subject Identification Method values or parameters>

The text fields and options for Subject Alternative Names generally work in a similar way as the Subject DN fields.

Certificate Validity

By setting the Certificate Validity Start Time and End Time you can precisely specify, for a specific end entity, when the certificate will start being valid and when the certificate will cease being valid.

When selecting to use Certificate Validity Start or End time you will get the possibility to enter these fields when a new end entity is added. You can also specify a default value for the end entity profile. Different formats of specifying the validity time is provided as examples in the end entity profile page.

This function requires the 'Allow validity override' function in the Certificate Profile.

Revocation Reason to set After Certificate Issuance

Using this option you can define that when adding a new user, the revocation state of an issued certificate can be set immediately to something else than 'Active'.

Useful if you want to issue certificate that are 'On hold' for users. After the user receives the certificate they might be required to perform some action in order to have their certificate activated.

Most useful when used in combination with OCSP since it will require, in practice, instant revocation checking.

When enabling this option in the profile, a corresponding selection will be available when adding new users. The user data corresponding to this option is an ExtendedInformation attribute, ExtendedInformation.CUSTOM_REVOCATIONREASON.

Reverse Subject DN Alt Name Checks

This checkbox is not recommended to be used in normal operations. When using the External RA and more than one DN field type is set in the profile, for example one optional OU and one required OU, it might be needed to check this checkbox for the profile validation to work.

Only use it in such a special case if nothing else work. This option may be removed in the future.

Maximum Number of Failed Login Attempts

By choosing a maximum number of failed login attempts the status of a user will change to GENERATED in case a wrong password is entered more than the specified number of times. Note that what is called a "password" in the admin web is often called an "enrollment code" in the public web. The Use option must be selected for the end entities to use this feature. If Modifiable is selected, the specified number can be changed for a particular end entity at the creation time of the end entity or later by editing it.

Custom Certificate Extension Data

By checking Use for custom certificate extension data in the end entity profile, a text area is provided when adding or editing an end entity for supplying custom certificate extension data.

Extension data is entered in the text area in the same format as for Java properties files, that is typically, key=value with one entry on each line. The extension data accepted and/or required depends on the custom extensions chosen in the certificate profile as 'Used Custom Certificate Extensions' and how these are configured.

For example, custom extensions of type BasicCertificateExtension configured with the property dynamic=true accept custom extension data in the form 'OID.value=value' where OID is the OID of the configured extension and value is the value to put in the extension in the configured encoding.

For more information on available extensions and configuration, see Custom Certificate Extensions.

The following displays an example configuration of a certificate extension taking dynamic value in RAW hax encoded format:

If the request (Extension Data) contains extensions which cannot match any configured Custom Certificate Extension in EJBCA, issuance will be rejected.

Number of Allowed Requests

By selecting Use for number of allowed requests you enable the possibility to request several certificates in a row, without the user status being set to generated. Normally after a username/password pair has been used to generate a certificate, the users status is set from 'new' to 'generated'. This makes the password invalid, thus implementing a one-time password scheme. By selecting a number higher than one for 'number of allowed requests' the user can request several certificates before the status is set to 'generated'. This makes it possible to enroll for several certificates directly, for example one authentication and one signature certificate.

The 'number of allowed requests' in the End Entity Profile will set the default, and maximum value available when adding or editing a new end entity. When editing an existing end entity and setting the status to new, from a non-new status, the 'number of allowed requests' will automatically be altered to the default value for the profile. If the end entity profile used no longer uses the 'number of allowed requests' the request counter for the end entity will be removed when the end entity is edited.

Plugin Field Restrictions

Administrators can develop further custom user field restrictions using the FieldValidator as described in Customizing EJBCA.