1. Introduction

The GBDS API provides SSL authentication for client and server connection using TLS protocol, enabling a new security layer. This manual covers the procedures for enabling SSL authentication in the GBDS API.

2. Certificates

SSL authentication using TLS requires mutual authentication, so the first step is the generation of both client and server certificates, which must have a valid format. The steps for allowing authentication at both sides are explained below.

2.1. Server-side Certificates

A Keystore file and a Truststore file must be created in the server and placed at /etc/griaule/keystore. Both files must be in PKCS12 (.pfx or .p12) format.

The public certification chain from client and server certificates must be added to the Truststore file to allow authentication.

2.2. Client-side Certificates

A Keystore file and a Truststore file must be created in the client. These will be used to authenticate the application.

The public certification chain that belongs to the server must be added to the Truststore of the client application.

3. API Configuration

Some configuration parameters must be edited or added to allow SSL authentication in the GBDS API. Once all the parameters are correctly set, the API service must be restarted to apply the changes in the configuration file.

Warning

Enabling SSL authentication in the GBDS API will require TLS authentication for any communication with the API port, with no possibility for HTTP communication

The API configuration file path is /etc/griaule/conf/gbsapi/gbdsapi.properties and the parameters to be changed are the following:

security.require-ssl

This parameter defines whether SSL is required for API communication. Its value must be set to true for enabling SSL authentication.

value: true

server.ssl.protocol

This parameter defines the SSL protocol to be used for authentication. Its value must be set to TLS.

value: TLS

server.ssl.client-auth

This parameter defines whether the client authentication is required for API communication. Its value must be set to need.

value: need

server.ssl.key-store

This parameter defines the path for the server Keystore file to be used.

value: /etc/griaule/keystore/<keystore>.pfx

server.ssl.key-store-password

This parameter defines the password to be used for accessing the Keystore file for certificate validation.

value: keystore password

server.ssl.trust-store

This parameter defines the path for the server Truststore file to be used.

value: /etc/griaule/keystore/<trustore>.pfx

server.ssl.trust-store-password

This parameter defines the password to be used for accessing the Truststore file for certificate validation.

value: <truststore password>