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 server certificateToggle Term Reference.
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 ReferencerootCA.crt and a private keyToggle Term ReferencerootCA.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 Referencedomain.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 ReferencerootCA.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
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
All the APIs - including gRPC, 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 mTLS can be controlled in the configuration file in the
section api.endpointDefaults.mTLS (or in a particular section for each protocol separately). 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, when the communication is allowed from public domain, at least until proper authentication
and authorization is implemented in evitaDB (see issue #25).
mTLS prevents a large number of attacks and thus emphasizes the security of the communication.
mTLS is not enabled by default. If you enable it, the necessary certificates will be generated automatically, but it's
still not secure and should only be used in development. When evitaDB is started and generateAndUseSelfSigned is
set to true (default), it generates two public/private key pairs:
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
Whenever at least one endpoint requires TLS, the public server certificate is served at /system/server.crt and
its URL is printed at start-up. This applies both to generated certificates and to the custom certificate configured
with certificate.custom.certificate when generateAndUseSelfSigned is false.
The client.crt is automatically added to the list of trusted client certificates. Only in generated mode are
client.crt and client.key available for downloading using the system endpoint. Their URLs are printed when
mTLS is enabled. You'll see those when the evitaDB server starts:
When the gRPC client starts and has the following settings:
useGeneratedCertificate: true (default)
mtlsEnabled: true (the default is false)
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. But this is good enough for local development environments and allow to test
the mTLS functionality.
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 server certificateToggle Term Reference both on the server side and the client.
If a client downloads the server certificate over plain HTTP, it must verify the downloaded certificate against
the fingerprint printed by the server at start-up before trusting it.
Server side fingerprint
The fingerprint is written to the console output when the server starts - it looks like this:
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. The public server certificate is served and advertised at
/system/server.crt; the custom certificate's filename does not create another download URL. Client certificates
and private keys are not distributed in this mode and must be configured on each client.
Yes, you can change the server certificate and valid client certificates without restarting the server. The server
periodically checks the timestamps of the last changes to the server certificate and the list of paths configured for
client certificates. If either of these files change, the server automatically reloads the new configuration.
This allows you to change the server certificate and client certificates without stopping the server.