est.properties

This article is valid for Certificate Manager 8.4 and later.

The default request URL for EST is as follows. For more information, see EST URI configuration.

Request URL

http://<pgwy-host>:<port>/pgwy/est[/<handler>]

Relative paths specified below are relative the <configroot>.

About <configroot>

<configroot> corresponds to the following paths:

Windows <configroot>

%ALLUSERSPROFILE%/Nexus/cm-gateway/

Linux <configroot>

/var/cm-gateway/

Parameters

Parameter	Description
start	Controls if the EST servlet should start or not. start = false
filter	contains a filter for the handler part of the URL specified as a regular expression. If using the CoAP proxy, regular expressions in the filters are not supported.
format	contains the name of a format definition file. For regular EST the format definition files with the prefix est- should be used. For EST over CoAPs the files with the prefix estcoaps- should be used instead.
tokenprocedure	contains the description or id of a token procedure in the CM server.
ra.keyfile	is the token to sign the fullcmc responses. Not required if fullcmc is disabled.
ra.password	is the password to the keyfile. It is recommended to obfuscate sensitive data with .encrypted.
requiredRoRoles	optional, contains a space or comma separated list of required Registration Officer roles. This requires client authentication to be enabled in Tomcat, and verifies that the client certificate is an officer. If the role none is entered, the client certificate must be issued by CM but does not need to be an officer. "/cacerts" must not be protected behind client authentication, and therefore no default role should be set.
authtype	optional, enables HTTP Basic/Digest authentication by specificing the desired authentication type. May only be set for filters simpleenroll and simplereenroll. Example: handler.<n>.authtype = Basic handler.<n>.authtype = Digest
realm	required if authtype is set, may be empty. Determines which realm the login should occur on. Can only be set for filters simpleenroll and simplereenroll.
qop	optional, determines the quality of protection used with Digest authentication. Valid value is auth. If not specified then no Quality of Protection will be required.
idm.requestUrl	optional, request URI of IDM instance to register the request. May only be set with format est-simpleenroll-idm.
idm.tls.token	required if idm.requestUrl is set, file path to the PKCS#12 file to be used to authenticate to IDM.
idm.tls.password	required if idm.tls.token is set, password for the PKCS#12 token as specified in parameter idm.tls.token.

Define handlers

The parameter values in the default section are used by all handlers unless overridden in the handler section.

Example: default values for handlers

default.format = est-simpleenroll
default.tokenprocedure = TLS Client Token

Each EST endpoint requires its own handler.

Example: handlers

handler.0.filter = cacerts

handler.1.filter = simpleenroll
handler.1.format = est-simpleenroll
handler.1.requiredRoRoles = cert.issue

handler.2.filter = simplereenroll
handler.2.format = est-simplereenroll
handler.2.requiredRoRoles = none
# Controls if the client TLS certificate must match the latest issued certificate
# for the requested subject. Set to false as default.
# handler.2.allowRenewalWithOldCertificates = false

handler.3.filter = fullcmc
handler.3.format = est-fullcmc
handler.3.requiredRoRoles = cert.issue
# fullcmc responses require an RA token to be signed with
handler.3.ra.keyfile = protocol-gateway-ra.p12
handler.3.ra.password = abcd1234

handler.4.filter = serverkeygen
handler.4.format = est-serverkeygen
handler.4.requiredRoRoles = cert.issue
handler.4.tokenprocedure = TLS Client Token Generate Key

handler.5.filter = csrattrs
# Csrattrs requires a filepath relative to the PGWY config root to a file
# with the expected attributes
handler.5.filepath = est_csrattrs.txt

About CSR attributes

The endpoint /csrattrs requires a text file that defines what Object Identifiers (OIDs) that are required by the CA. The filepath is configured in est.properties and the syntax for the file is one OID per line. See example configuration above.

Note that requests that do not comply with the answer from /csrattrs might still be accepted.

About Server key generation configuration

To configure a token procedure that is compatible with /serverkeygen, make sure that the following requirements are satisfied:

The token procedure must have the storage type PKCS12 to enable key procedures. The PIN procedure can be "Enter PIN in client" since the PIN will not be used.
A Key procedure with Key management archive and format generate must be added.
A certificate procedure.

See example configuration above.

Example: Multiple CAs

Protocol Gateway supports multiple token procedures and thereby multiple CAs.

To support multiple CAs, subpaths can be added with different token procedures:

Example: Multiple CAs

#handler.20.filter = otherpath/cacerts
#handler.20.tokenprocedure = anotherTokenProcedure

The configuration in coap.properties must be adapted so that only the correct endpoints are exposed through the CoAP Proxy. For more information, see coap.properties.

Example: CoAP endpoints

CoAP endpoints should use the formats with estcoaps- prefixes. See also EST over CoAPs support in Certificate Manager and coap.properties.

Example: CoAP endpoints

#handler.21.filter = otherpath/sen
#handler.21.format = estcoaps-simpleenroll
#handler.21.tokenprocedure = anotherTokenProcedure
#handler.21.requiredRoRoles = cert.issue