TypeDB In-flight Encryption
Communication with a TypeDB server can be secured using TLS. TLS serves two purposes:
-
Encrypting connections to prevent eavesdropping
-
Authenticating the server’s identity by validating its certificate is signed by a trusted issuing authority.
To enable TLS, TypeDB must be configured with a private-key & certificate. The relevant fields in the config file are:
server:
...
encryption:
enabled: true
certificate: /path/to/certificate
certificate-key: /path/to/private-key
# Optional:
ca-certificate: /path/to/ca-certificate
Self-signed certificates for development
We start with a quick, non-mathematical refresher.
Public & private keys
A key-pair consists of a private & public key which together can be used for encrypted communication, and digital signatures.
For encrypted communication, a server sends over the "public" key to the client. The client uses this key to encrypt messages, which the server can decrypt using its private key.
For signatures, the private key is used to sign a message. This signature can be verified using the corresponding public key.
It is critical the private key remains confidential to prevent others from decrypting messages or forging signatures. |
Certificates
A server establishes its identity by sending over a certificate. A certificate contains a public-key, some metadata for the identity, and a signature. The authenticity of the certificate is verified by validating that it has been signed by some other certificate that we "trust".
Typically, an Operating System comes pre-loaded with certificates of few major certificate authorities (CA) that are trusted in the real world - such as Verisign. A user can choose to trust any certificate, including ones that they have created & signed themselves. The mkcert utility can be used to easily generate self-signed certificates.
Self-signed certificates with mkcert
On first use, mkcert
creates a fresh CA certificate & signing key for your machine.
It will use this to sign any certificates it generates.
To see the location of these files, run mkcert -CAROOT
.
You will see rootCA-key.pem
and rootCA.pem
at the location.
The following command generates a private-key.pem
and corresponding certificate.pem
,
valid for a server with hostname localhost
, or IP 127.0.0.1
mkcert -cert-file certificate.pem -key-file private-key.pem localhost 127.0.0.1
We now have 4 files:
-
rootCA-key.pem
: The private-keymkcert
uses to sign certificates. Onlymkcert
needs this. -
rootCA.pem
: The certificate generated from and (self) signed byrootCA-key.pem
. TypeDB drivers can use this to authenticate the server. -
private-key.pem
: The private-key for the server. To be configured asserver.encryption.certificate-key
-
certificate.pem
: The certificate for the server generated fromprivate-key.pem
, and signed byrootCA-key.pem
. To be configured asserver.encryption.certificate
Unless you have already run Note: the local CA is not installed in the system trust store. Run "mkcert -install" for certificates to be trusted automatically ⚠️ As the message suggests, you can add the |