Example: Certificate Manager (CM) REST API configuration in Protocol Gateway

This article describes a configuration example of the Certificate Manager (CM) REST API in Protocol Gateway. 

Access to the Rest API requires use of TLS with certificate-based client authentication and a API request is signed using an officer certificate. 

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 REST API

Create certificate procedure for CM REST API devices

If a new certificate procedure is needed for REST API devices, then create one according to Create certificate procedure in Certificate Manager with the following settings: 

1. Set Issuing CA to Device Issuing CA.

2. Set Format to rfc5280. 

Create token procedures for CM REST API devices

Token procedures must be set up for the needed REST API use cases, in this example one for PKCS#7 responses and one for PKCS#12 responses. 

Create two new token procedures Ior REST API devices, according to Create token procedure in Certificate Manager with the following settings: 

1. For PKCS#12 responses: 

   1. Set Procedure name to Device Token Procedure.

   2. In Storage profile, select PKCS12.   

   3. In Issuer certificates, select to Store all or Do not store any. 

2. For PKCS#12 responses: 

   1. Set Procedure name to Device Token Procedure P10.

   2. In Storage profile, select PKCS10.   

   3. In Issuer certificates, select to Store all or Do not store any. 

Set REST API properties

To set the properties for the REST API: 

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

2. Modify the following properties: 

3. Enable the REST API by setting start to true. 

4. Set the token procedures for the needed use cases. For example, set token procedures for handler.30 and handler.31 to the token procedues that were created in the previous step.

For more information on how to configure verifications of certificate requests in .properties files, see Certificate request verifications in Protocol Gateway. 

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

6. Save the file.  

Example: api.properties

start = true

# Process PKCS10 request -> PKCS7 response
handler.30.filter = certificates/pkcs10
handler.30.format = api/certificates-pkcs10
handler.30.tokenprocedure = Device Token Procedure P10

# Process PKCS10 request -> PKCS12 response
handler.31.filter = certificates/pkcs12
handler.31.format = api/certificates-pkcs12
handler.31.tokenprocedure = Device Token Procedure

Restart Tomcat

Restart the Tomcat service. 

Verify REST API

Prepare test of REST API

To verify the REST API: 

1. Copy the file SO1.p12 to \Nexus\testclients\temp.

2. Copy the file SystemCA.cer to \Nexus\testclients\certs.

3. Configure the REST API test client: 

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

   2. Set p12.keyToken.keyFile to temp/SO1.p12.

   3. Set p12.keyToken.password to 1234. 

Create a sample CSR

To create a PKCS#10 certificate signing request (CSR):

1. Go to https://wtools.io/generate-csr-and-private-key. 

2. Enter sample data in the input fields. 

3. Click Generate. 
   A CSR is created. 

4. Copy the CSR content and paste it into a new file, for example csr.p10. 

Verify REST API with Test client

To verify the REST API: 

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

Example: Generate CMP request

java –jar testtools.jar APIClient interactive

1. Run the following command to send the CSR to CM:

Example: Generate CMP request

pkcs10-pkcs7 csr.p10

2. Save cert.cer.