Document toolboxDocument toolbox

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

ParameterDescription
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.
formatcontains 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.
tokenprocedurecontains the description or id of a token procedure in the CM server.
ra.keyfileis the token to sign the fullcmc responses. Not required if fullcmc is disabled.
ra.passwordis the password to the keyfile. It is recommended to obfuscate sensitive data with .encrypted.
requiredRoRolesoptional, 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

realmrequired if authtype is set, may be empty. Determines which realm the login should occur on. Can only be set for filters simpleenroll and simplereenroll.
qopoptional, 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.requestUrloptional, request URI of IDM instance to register the request. May only be set with format est-simpleenroll-idm.
idm.tls.tokenrequired if idm.requestUrl is set, file path to the PKCS#12 file to be used to authenticate to IDM.
idm.tls.passwordrequired 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

Copyright 2024 Technology Nexus Secured Business Solutions AB. All rights reserved.
Contact Nexus | https://www.nexusgroup.com | Disclaimer | Terms & Conditions