Example: EST configuration in Protocol Gateway

This article describes a configuration example of the EST protocol in Protocol Gateway. 

The Enrollment over Secure Transport (EST) is a cryptographic protocol that describes an X.509 certificate management protocol targeting Public Key Infrastructure (PKI) clients that need to acquire key pairs, client certificates and associated Certification Authority (CA) certificates over https. Example of functions are initial certificate enrollment, certificate renewal, and CA rollover. EST is defined in RFC 7030.

Prerequisites

• Protocol Gateway must be installed. See Install Protocol Gateway.

• Initial configuration of Protocol Gateway must be done. See Initial configuration of Protocol Gateway.

• Tomcat must be configured for TLS client authentication. See Configure Tomcat for TLS client authentication in Protocol Gateway.

Configure EST in Protocol Gateway

Create EST certificate procedure

Create a certificate procedure for EST, see Create certificate procedure in Certificate Manager:

1. Set Procedure name to Protocol Gateway EST Certificate.  

2. In Issuing CA, select Device Issuing CA. 

3. In Certificate format, select estenroll. 

4. In Extended key usage, add TLS Server Authentication and TLS Client Authentication.  

Create EST token procedure

Create a token procedure for EST, see Create token procedure in Certificate Manager:

1. Set Procedure name to EST Registration and Enroll Procedure. 

2. In Storage profile, select PKCS10. 

3. In Certificate procedures, select the certificate procedure you just created, that is Protocol Gateway EST Certificate. 

4. In Input view, select GPIV 15 - Save and Search EST Enrollment Registrations. 

Create EST certificate procedure for simpleenroll

Clone the certificate procedure Protocol Gateway EST Certificate, and modify the new certificate procedure as follows: 

1. Set Procedure name to Protocol Gateway EST simpleenroll.  

2. In Certificate format, select rfc5280.   

Create EST token procedure for simpleenroll

Create a token procedure for EST, see Create token procedure in Certificate Manager:

1. Set Procedure name to EST simpleenroll Procedure. 

2. In Storage profile, select PKCS10. 

3. In Certificate procedures, select the certificate procedure you just created, that is Protocol Gateway EST simpleenroll. 

4. In Input view, select GPIV 15 - Save and Search EST Enrollment Registrations. 

Set EST properties

In this example, simpleenroll is configured to use basic authentication to receive the first certificate and then to use that certificate to request a renewal with simplereenroll.

The est.properties file contains the configuration parameters used by the EST servlet. For more information, see est.properties.

To set the properties for EST: 

1. Open \Nexus\cm-gateway\conf\est.properties for editing.

2. Modify the following properties: 

   1. Enable EST by setting start to true. 

   2. Set default.tokenprocedure to EST Registration and Enroll Procedure.

   3. Configure handler.1 and handler.2 as follows: 

      1. Comment out handler.1.requiredRoRoles.

      2. Set handler.1.authtype to Basic.

      3. Set handler.2.tokenprocedure to the simpleenroll procedure you have created, EST simpleenroll Procedure. 

      4. Set handler.2.requiredRoRoles to none. 
         For more information on how to configure verifications of certificate requests in .properties files, see Certificate request verifications in Protocol Gateway.

3. If needed, scramble sensitive parameters in the configuration file. See Scramble sensitive data in configuration files in Protocol Gateway.

4. Save the file.  

Example: est.properties

start = true
default.format = est-simpleenroll
default.tokenprocedure = EST Registration and Enroll Procedure

# Define handlers
# Each EST endpoint requires its own handler

handler.0.filter = cacerts

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

handler.2.filter = simplereenroll
handler.2.format = est-simplereenroll
handler.2.tokenprocedure = EST simplereenroll Procedure
handler.2.requiredRoRoles = none

Restart Tomcat

Restart the Tomcat service. 

Test EST protocol with Nexus test client

Configure EST test client

To configure the EST test client: 

1. Open the file com.nexussafe.cm.test.app.ESTClient.properties for editing: 

2. Comment out handlerInfo.0.port = 8444.

3. Configure PKCS#10:

   1. Set p10.subject to cn=EST 169676786786, with any serial number.  

   2. Set p10.dns to EST 169676786786, with the same serial number as above  

   3. Comment out p10.email.

Register demo EST device

Register a wildcard EST device for testing: 

1. In Registration Authority (RA) in Certificate Manager, go to the Order tab. 

2. In Procedure, select EST Registration and Enroll Procedure.

3. Register a wildcard FQDN, by entering the following details:

   1. In Commonname, enter *.

   2. In Username, enter test.

   3. In Realm, enter EST.

   4. In Password, select a password, that shall be used in the simpleenroll process later.  

   5. In Validity time (days), enter the number of days that the registration shall be valid. 

   6. In State, select Open.

Verify EST with Test client

To verify the EST setup with the EST Test client: 

1. In the command prompt, start an interactive session, by typing the command: 

   Example: Start EST Test client

   CODE

   java –jar testtools.jar ESTClientHttp interactive

2. Verify that the issuing CA certificates can be fetched, by using the cacerts command. The default URL https://cm.local:8443/pgwy/.well-known/est/cacerts, will be used by the EST client to obtain CA certificates. Protocol Gateway will automatically send the CA certificate for the token procedure set in default.tokenprocedure.

   1. Run the following command and verify that the response code is 200:

      CODE

      cacerts

      Note: Since Protocol Gateway is delivered as a web application, it is normally placed in the subpath /pgwy/ by Tomcat. This can be configured in Tomcat. FOr more information, see EST URI configuration

3. Verify that a certificate can be issued by the simpleenroll command. The simpleenroll process is configured with basic authentication, so we can request the first certificate. The URL https://cm.local:8443/pgwy/.well-known/est/simpleenroll will be used by an EST client to obtain a certificate from a P10 request. Run the following commands: 

   1. Turn off client authentication: 

      CODE

      toggleclientauth

   2. Set the password for basic authentication, to match the configured password in the registration: 

      CODE

      setbasicauthentication user:pass 

   3. Request a certificate, by using basic authentication: 

      CODE

      simpleenroll

   4. Verify that a certificate is issued. 

4. Verify that a certificate can be issued by the simplereenroll commands. The URL https://cm.local:8443/pgwy/.well-known/est/simplereenroll will be used by an EST client to renew its certificate. Protocol Gateway will check that the subject contained in the request is the same than the subject of the authentication certificate (in fact the same commonname). This means that to use this function, the clients require certificates with the extended key usage Client Authentication. Run the following commands: 

   1. Use the latest received certificate for authentication:

      CODE

      switchsslcredentials

   2. Turn client authentication back on: 

      CODE

      toggleclientauth

   3. Request a certificate, by using client authentication: 

      CODE

      simplereenroll

   4. Verify that a certificate is issued.
      If the hostame is not the same the error will be

      CODE

      Result: Could not verify that certificate request was for renewing an existing subject

Additional information