Setting up TLS

All evitaDB APIs support the secure layer (HTTPS). The gRPC is completely based on the HTTP/2 protocol, which is binary and requires encryption. Because of this fact, all evitaDB external APIs work by default on secure protocol to keep the security uniform.

Used terms

certificate authority: the certificate authority is an entity that stores, signs, and issues digital certificates. A digital certificate certifies the ownership of a public key by the named subject of the certificate. This allows others (relying parties) to rely upon signatures or on assertions made about the private key that corresponds to the certified public key. A CA acts as a trusted third party—trusted both by the subject (owner) of the certificate and by the party relying upon the certificate. source
certificate: the certificate is an electronic document used to prove the validity of a public key, and it contains a public key along with a lot of additional information source
private key: the private key is a classified part of the public/private key pair - it must never leave the secured perimeter. An entity that proves itself with a private key is considered authentic - a private key is similar to an ID card see more
public key: the public key is the second part public/private key pair - it may be freely distributed and its ownership does not entitle to anything, it only serves to prove the authenticity of the private key see more

We don't want to make things complicated for developers and newcomers, but that doesn't mean that the default behavior is secure, because it can't be. The evitaDB server automatically generates a self-signed certificate authorityToggle Term Reference and issues the server certificate required for TLS. This certificate will not be trusted by the clients unless you force them to. Usually it's just a matter of toggling some switches and for development purposes it's good enough. For production environments, we strongly recommend issuing your own certificateToggle Term Reference using the Let's Encrypt authority, which can be automated and is part of all certificate trust chains these days.

If you are familiar with certificate handling, you can skip the entire create a certificate chapter and go to configuration or read about mTLS support for the gRPC protocol.

Creating a certificate

You need a certificateToggle Term Reference to prove your identity, whether you are a server or a client.

It is possible to divide certificates into two groups according to the certificate signature:

Certificates signed by a publicly trusted root certificate authority
Certificates signed by a private certification authority

Publicly trusted certificate authority

You can buy a certificateToggle Term Reference from commercial certificate authoritiesToggle Term Reference, or you can generate one for free using Let's Encrypt. You can find lots of information about this process on the web, so we won't duplicate it here. To generate a free server certificate, follow the instructions on the Certbot site.

Self-signed certificate authority

In this guide, we will focus on the second group: self-signed certificates. When using mTLS, it is necessary for the server to have access to a certificate authorityToggle Term Reference that trusts it, and for clients that prove their identity with a certificateToggle Term Reference issued by that authority to allow communication.

To generate a certificate, we will use the OpenSSL tool. It is pre-installed on many Linux distributions, as well as on newer versions of the MacOS system. On Windows operating systems, you will need to download and install the tool.

Creating certificate authority

To create certificate authorityToggle Term Reference execute following command:

It generates a certificateToggle Term Reference rootCA.crt and a private keyToggle Term Reference rootCA.key for the certificate authorityToggle Term Reference (after confirmation you have to enter a password).

After running the commands in steps 1 and 2, you must enter a password - if you want an unencrypted certificate without a password, specify the `-nodes' parameter in the command.

Argument	Description
-x509	produces a x509 certificate - according to a standard that defines the format of digital certificates used in SSL/TLS connections
-newkey cipher:bits	determines the used cipher and its complexity, you can list all supported ciphers by command openssl ciphers
-days	determines the number of days the certificate is valid, when this period expires the certificate is considered invalid and the server and client will refuse to work with it
-keyout	file name where private keyToggle Term Reference is stored
-out	file name where certificateToggle Term Reference with public key is stored

Certificate signing request

Now you need to create a text file called domain.ext with the following content. You need to replace [domain] in DNS section with the name of the domain (or multiple domains) where your going to run the evitaDB server:

Then you need to create the certificate signing request domain.csr using following command:

It generates a private keyToggle Term Reference domain.key for the client and a request domain.csr to be signed by a certificate authorityToggle Term Reference (after confirmation you have to enter a password)

Now you are ready for the final step.

Issue signed certificate

Finally, you're ready to generate signed certificate which you can use for evitaDB server or any of the clients in case the mTLS is enabled.

Generate new certificateToggle Term Reference signed by the certificate authority represented by the rootCA.crt and its private keyToggle Term Reference rootCA.key using the following command:

You can repeat this command multiple times to generate different certificates both for server side and for each of the clients.

Do not use the same signed certificate for the server and the client! Do not use the same certificate for different clients! Each entity in the communication must be represented (identified) by a different certificate.

If you follow these recommendations, you'll be able to control the rejection of each client separately. If you issue a certificate for a third party client and your contract with them ends, you can easily delete their certificate from the list of allowed client certificates and effectively stop communicating with their client application.

Both the server and the client can be provided with:

certificate in the format .crt, .cer or .pem
private key in the format .key or .pem

Argument	Description
-CA	identifies the public part of the certificate authorityToggle Term Reference
-CAkey	identifies the private keyToggle Term Reference of the certificate authorityToggle Term Reference
-in	identifies the signing request controlling the operation
-days	determines the number of days the certificate is valid, when this period expires the certificate is considered invalid and the server and client will refuse to work with it
-extfile	identifies the file with the domain description
-out	file name where the generated certificateToggle Term Reference with public key is stored

Mutual TLS for gRPC

The gRPC API, and thus , also offers the possibility of authentication via mutual TLS, in which client and server verify their identities with the help of a certificate exchange.

The gRPC API is used by evitaDB drivers and is expected to be a system API requiring a higher level of security. On the other hand, GraphQL and REST APIs are usually used by end clients - maybe even directly from browsers or client applications. From our point of view, these types of APIs are consumer level APIs with different authentication requirements.

The mTLS can be controlled in the configuration file in the section api.endpoints.gRPC.mTLS. At the same place it is possible to configure the list of client certificates that are allowed to communicate with the gRPC server. The client that doesn't present itself with the accepted certificate will be rejected by the server.

The client needs to configure path to its certificateToggle Term Reference, private keyToggle Term Reference and optionally password to a private key in configuration.

We recommend the use of mTLS because it prevents a large number of attacks and thus emphasizes the security of the communication.

Examples of attacks prevented:

Default mTLS behaviour (not-secure)

The mTLS is enabled by default but in a way that is not secure and should be used only in development. When the evitaDB starts and generateAndUseSelfSigned is set to true (default), it generates three public/private key pairs:

certificate authorityToggle Term Reference in evitaDB-CA-selfSigned.crt and its private keyToggle Term Reference in evitaDB-CA-selfSigned.key files
server certificateToggle Term Reference in server.crt and its private keyToggle Term Reference in server.key files
client certificateToggle Term Reference in client.crt and its private keyToggle Term Reference in client.key files

The client.crt is automatically added to the list of trusted client certificates. Both client.crt and client.key are available for downloading using system endpoint. You'll see those when the evitaDB server starts:

When the gRPC client starts and has the following settings (all are defaults):

useGeneratedCertificate: true
mtlsEnabled: true

It automatically downloads the default client certificate along with private key and use it for communication. We are aware, that this is not secure and defies the logic of mTLS, but it allows us to test entire process and avoid problems in test/production environments.

If you need to verify that the client communicates with the server directly without any man-in-the-middle, you may check the fingerprints of the used certificate authorityToggle Term Reference both on the server side and the client.

Server side fingerprint

The fingerprint is written to the console output when the server starts - it looks like this:

Client side fingerprint

Client logs the fingerprint using configured logging library on INFO level in this form:

Recommended mTLS usage (secure)

For each of the gRPC client generate their own certificateToggle Term Reference using trusted certificate authorityToggle Term Reference (such as Let's Encrypt), or your own self-signed authority. Disable generateAndUseSelfSigned and configure server certificate and each of client certificates in configuration.

Author: Bc. Tomáš Pozler

Date updated: 1.3.2023

Documentation Source