# SSL Authentication on the GBDS API

## Introduction

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

## Certificates

SSL authentication using TLS requires mutual authentication, so the first step is generating the client and server certificates, which must have a valid format. The steps to allow authentication on both sides are explained below.

### Server Certificates

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

The public certification chains of the client and server certificates must be added to the *Truststore* to allow authentication.

### Client Certificates

A file *Keystore* and a file *Truststore* must be created on the client. These will be used for application authentication.

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

## API Configuration

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

{% hint style="warning" %}
When enabling SSL authentication in the GBDS API, TLS authentication will be required for any communication with the API port, and there will be no possibility of communication via HTTP.
{% endhint %}

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

**security.require-ssl**

> This parameter defines whether SSL is required for communication with the API. Its value must be set to `true` to enable SSL authentication.
>
> *value*: `true`

**server.ssl.protocol**

> This parameter defines the SSL protocol to be used in authentication. Its value must be set to `TLS`.
>
> *value*: `TLS`

**server.ssl.client-auth**

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

**server.ssl.key-store**

> This parameter defines the path to the *Keystore* file that will be used on the server.
>
> *value*: `/etc/griaule/keystore/<keystore>.pfx`

**server.ssl.key-store-password**

> This parameter defines the password to be used when accessing the *Keystore* file for certificate validation.
>
> *value*: `keystore password`

**server.ssl.trust-store**

> This parameter defines the path to the *Truststore* file that will be used on the server.
>
> *value*: `/etc/griaule/keystore/<trustore>.pfx`

**server.ssl.trust-store-password**

> This parameter defines the password to be used when accessing the *Truststore* file for certificate validation.
>
> *value*: `<truststore password>`