Nexus Certificate Manager
Nexus Certificate Manager
Breadcrumbs

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 an API request is signed using an officer certificate.

Prerequisites

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 two token procedures are created: One for PKCS#12 responses and one for PKCS#7 or X.509 DER/PEM certificate encoded responses, both from a PKCS#10 request. 

Create two new device token procedures and one new VRO token procedure for REST API devices, according to Create token procedure in Certificate Manager with the following settings: 

  1. For PKCS#12 responses from a PKCS#10 request: 

    1. Set Procedure name to Device Token Procedure P12.

    2. In Storage profile, select PKCS12.   

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

  2. For PKCS#7 or X.509 DER/PEM encoded certificate responses from a PKCS#10 request: 

    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. 

  3. For authority create VRO:

    1. Create a VRO 'api_vro.p12' using VRO Token Procedure

    2. Create an officer ‘testclient_officer' and assign the 'api_vro’ certificate to it.

    3. Copy the 'api_vro.p12' under \testtools\temp\api_vro.p12

Set REST API properties

To set the properties for the REST API: 

  1. Open api.properties for editing.

windows path

\Nexus\cm-gateway\conf\api.properties

linux path

/var/cm-gateway/conf/api.properties

  1. Modify the following properties: 

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

    2. Set the token procedures for the needed use cases. For example, set token procedures for handler.30 and handler.31 to the token procedures 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. 

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

  2. Save the file.  

Example: api.properties 
start = true

# Process PKCS10 request
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/pkcs10-to-pkcs12
handler.31.format = api/certificates-pkcs10-to-pkcs12
handler.31.tokenprocedure = Device Token Procedure P12

Restart Tomcat

Restart the Tomcat service. 

Verify REST API

Prepare test of REST API

Use testtools to verify the REST API located in build package “\Installation\clients\cm_clients_<version>\program_files\web\testtools\” : 

  1. Copy the file api_vro.p12 to /testtools/temp/.

  2. Copy the issuing CA, SystemCA.cer to /testtools/certs.

  3. Configure the REST API test client by editing /testtools/config/com.nexussafe.cm.test.app.APIClient.properties, and set:

    p12.keyToken.keyFile = temp/api_vro.p12
p12.keyToken.password = 1234


  4. To test that the client is working, execute the following command from the testtools directory:

    bin\testtools APICLIENT list-procedures

Create a sample CSR

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

  1. Run the following OpenSSL command:

    Bash
    openssl req -new -newkey rsa:2048 -nodes -keyout key.pem -out csr.p10 -subj "/CN=Test/O=Example/C=SE"

  2. This creates a CSR file, csr.p10, and a private key, key.pem, with sample data.

  3. Alternatively, if OpenSSL is not available, use Java keytool:

    Bash
    keytool -genkeypair -alias test -keyalg RSA -keysize 2048 -keystore keystore.jks -storepass changeit -dname "CN=Test, O=Example, C=SE"
keytool -certreq -alias test -keystore keystore.jks -storepass changeit -file csr.p10

Verify REST API with testtools

To verify the REST API: 

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

Example: Generate REST API request 
java –jar testtools.jar APIClient interactive

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

Example: Send CSR to CM 
pkcs10-pkcs7 csr.p10

  1. Save cert.cer.


Last updated: