Advanced topics

client auth

Usually, the server authenticates itself to the client using a certificate but the client does not offer a certificate to the server. However, there is a TLS variant called Mutal TLS (mTLS) where the client also offers a certificate to the server.

How to configure the server to require mTLS is outside the scope of this documentation but if the server requires a client certificate, the clients need to be configured with the location on the client file system of the client private key and certificate. MonetDB client libraries will accept settings clientkey=PATH and clientcert=PATH to provide this information. It is allowed to append the certificates to the key file, in that case clientcert can be omitted.

Note: MonetDB-Java currently does not allow mTLS. Mclient/libmapi and pymonetdb do.

hash auth

Usually you will either get a recognized CA to sign your server certificate, or you will copy a self-signed certificate to the client and configure it with cert=/path/to/cert. In some highly specific circumstances it can be convenient to not copy the certificate to the client but to include it's SHA256 hash in the monetdbs:// URL. This can be done as follows:

monetdbs://localhost:4301/demo?certhash=sha256:17d9931042c366d26

The client will then validate the server certificate against the given hash. This works as follows:

  • the client looks at the server's certificate. Note: it only looks at the certificate of the server itself, not at any of the CA certificates that sign it.

  • in particular, it looks at the DER encoding of the certificate.

  • it takes the SHA-256 hash and converts it to hex digits.

  • if the resulting hex digest starts with the digits given in the certhash= parameter, the certificate is considered valid. Otherwise, invalid.

To do this from the command line, run:

$ openssl x509 -outform der -in /tmp/certs/server1.crt | sha256sum

No unix domain sockets

Due to a design issue in MonetDB's MAPI protocol it is not possible to have the TLS proxy forward its connections to MonetDB's Unix domain sockets. This means MonetDB must be configured to listen on some TCP port.