End Entities

An end entity is the owner of a certificate. It is the PKI participant for whom the digital certificate is issued. For example, if the certificate is a web server certificate, then its owner is a web server and subsequently the end entity is this web server. In case of an email certificate, the end entity is the person, to whom the email belongs. An entity can even be more "abstract"; e.g. a (micro)service or a process.

End entities are bound to a realm, meaning that a specific end entity exists and can be used only within the scope of its respective realm. A realm can have multiple end entities.

Purpose of end entities

End entities represent an entity outside the boundaries of the PKI. Such entities could be web servers or persons. Modelling end entities within the RA application provides the possibility to manage and work with such logical entities within the PKI system (instead of certificates). The advantage is that users possess a more natural than technical method to manage and view the PKI.

For example, a web server requests a certificate via ACME three times. Using end entities it is possible to represent this server as an entity with three certificates attached to it. Otherwise, there would be just three certificates within the PKI which are not related to this web server, and with the domain name as their sole common characteristic.

Using end entities this relation becomes explicit rather than implicit. In the RA it is mandatory to attach all actions and certificates to an end entity.

End entity alias

An end entity needs a certain, specified characteristic. For example, in the case of the previously mentioned web server, this characteristic could be the server domain name. Characteristics are called aliases. An alias is an identifier which is used to identify this end entity.

There are cases where it’s not possible to provide the alias of the end entity. Therefore, creating or assigning a certificate to it are not obvious procedures. A typical example is the request for a certificate by an end entity, via a protocol like ACME or EST. It is not possible to provide this type of information within the protocol (at least not in a standardized way). Since an end entity always requires a unique alias, a mechanism to create aliases for end entities in the system is necessary. This mechanism utilizes strategies. Each strategy provides a method to create an alias for the end entity. Different strategies are described in End Entity Alias Strategy.

The alias of an end entity is set via following methods and cannot be modified afterward:

  • Through manual setting; If the end entity’s alias is not yet set, following option is available in the details page of an end entity; to manually choose its strategy and the value to be set as an alias. This bypasses the automatic construction based on the strategy’s algorithm and accepts any value the user provides instead.

  • During Certificate Request Creation; Here the end entity and a policy are combined. The system constructs the alias from the strategy related to the policy If the alias does not exist, then an end entity is created. If the alias exists, then the certificate is attached to this end entity.

End entities are mandatory. An alias is used to identify an end entity. Strategies are used to create an alias.

End Entity Alias Strategy

RA Operators can choose among the following end entity alias strategies;

COMMON NAME

This strategy attempts to construct the alias using a common name from all the available input data. The first choice is always the common name field of the end entity itself. If no end entity is known during calculation (for example when searching for an end entity based on the alias), then a PKCS10 Request must be available and its subject common name field is used. If neither an end entity nor a PKCS10 Request are available, then this strategy cannot produce a result and the calculation ends with an error.

EMAIL

This strategy attempts to construct the alias using an email from all the available input data. The first choice is always the email field of the end entity itself. If no end entity is known during calculation (for example when searching for an end entity based on the alias), or it has no email, then a PKCS10 Request is analyzed. First, the email field of the PKCS10 subject is tested. If unavailable, the email field from the PKCS10 Subject Alternative Name (SAN) Extension is used. If nothing is found, then this strategy cannot produce a result and the calculation ends with an error.

PKCS10 SUBJECT CN

This strategy attempts to construct the alias from the PKCS10 Request subject common name field. If it is not found, then this strategy cannot produce a result and the calculation ends with an error.

PKCS10 SUBJECT EMAIL

This strategy attempts to construct the alias from the PKCS10 Request subject email field. If it is not found, then this strategy cannot produce a result and the calculation ends with an error.

PKCS10 SUBJECT SAN EMAIL

This strategy attempts to construct the alias from the PKCS10 Request Subject Alternative Name (SAN) Extension email field. If it is not found, then this strategy cannot produce a result and the calculation ends with an error.

PKCS10 SUBJECT

This strategy attempts to construct the alias from the complete PKCS10 Request subject in binary form. If it is not found, then this strategy cannot produce a result and the calculation ends with an error.

PKCS10 CN SAN SET

This strategy extracts all the common names from the PKCS10 Request subject along with all the domain names and ips from the PKCS10 Request Subject Alternative Name (SAN) extension and combines them in the following form; {"cns":["cn1", "cn2],"dns":["dn1.example.com", "dn2.example.com"],"ips":["192.168.0.1", "192.168.0.2"]}. If no PKCS10 Request is available, or none of the used values exist, then this strategy cannot produce a result and the calculation ends with an error.

END ENTITY DATA SET

This strategy attempts to construct the alias using all available input data. It is commonly used together with CMP and the CertTemplate. In the CertTemplate, additional data (apart from email, domain names etc.) are transferred and stored in the end entity as key-pair values.

View End Entities

Available end entities for a realm can be viewed and searched for in the End Entities page. An option to export selected rows as Comma Separated Values (CSV) is available via the Actions → Export selected as CSV, along with an option to Add password to the selected End Entities. There is also a filter an admin can use, to view archived end entities only. This filter can be triggered by pressing the Show Archived button in the Actions dropdown list.

Create End Entity

The New End Entity page can be reached via the side menu or via the Create… quick access button at the top right.

Here, some of the most common X.509 certificate components can be defined. For example; Common Name (CN), Country (C), E-Mail (E), Organisation (O), Organisational Unit (OU). Only Common Name (CN) is required, the rest are optional. Additionally, a list of domain names and a list of ip addresses can be provided, to be included in the Subject Alternative Name (SAN) extension. An optional External ID can be given to the created end entity. It can be used to store additional identification information. Lastly, the list Custom CA Parameters can be provided, to pass additional certificate template parameters (ident data) to MTG CARA (E.g., id.data=custom-data).

Modify End Entity

End entity modification is not supported.

Archive End Entity

A user can archive or unarchive a policy by entering the End Entities/Show tab. There, by pressing the end entity’s name, the user will be redirected to the end entity details page. By pressing Archive or Unarchive button the end entity will be archived or unarchived accordingly. Batch Archive and Batch Undo-Archive actions are also supported, by selecting the checkboxes of the desired end entities and choosing the Archive All Selected and Undo-Archive All Selected buttons in the Actions dropdown list. Upon end entity archiving, all child entities of the end entity will be archived too. Child entities of end entities are considered their certificates and certificate requests. Upon un-archiving, end entities' child entities are not affected. End entities associated with an active certificate can not be archived. Archived end entities, belonging to an archived realm can not be unarchived. Archived end entities can not be used for new operations.

Delete End Entity

A user can delete an archived end entity through the End Entity page, the Show Entities Table or the Administration/Archived Data Removal tab. In the End Entity page, after archiving the entity, a Delete button will appear. In the Show Entities Table, by pressing Actions→Show Archived, a table with the archived entities is visible. Here the end entities can be selected. Through Actions→Delete all selected they can be deleted. Furthermore, the user can delete one End Entity at a time by pressing the row actions button and then Delete End Entity. Finally, in the Choose entity to delete dropdown menu, the user can select End Entities. As an extra safeguard there is the option to restrict archived records to be deleted, using the date on which they were archived as filter. In the Choose date calendar, the user can select the date, to filer archived records prior to this date. Those can be deleted by selecting Delete. Upon deletion, all archived certificates, certificate requests and all end entity passwords linked to the deleted end entities will also be deleted.