Encryption in Transit

This page discusses how to secure communications between clients and Stardog.

Page Contents

Steps to set up SSL

All network traffic between clients and Stardog can be performed over either HTTP or HTTPS protocols. To ensure the confidentiality of user authentication credentials when using remote connections, it is highly recommended to configure the Stardog server to only accept connections that are encrypted with SSL.

Steps to set up SSL

1. Create or acquire a certificate

Our recommendation is to acquire a certificate from a trusted Certificate Authority (CA). As an example, you can get one from Let’s Encrypt. Using a self-signed certificate is not recommended for production.

If you already have a .crt file and private key, continue to step 2.
If you do not have a certificate, you may execute the following OpenSSL command to generate a self-signed certificate (myCert.crt) and a 4096-bit private key (key.pem):

openssl req -x509 -newkey rsa:4096 -keyout key.pem -out myCert.crt -days 365 -nodes

Answer the information prompt for the certificate signing request (CSR) to generate the private key and self-signed certificate.

The -x509 option tells the req utility to create a self-signed certificate. The -days 365 option specifies that the certificate will be valid for 365 days.

There are many other ways to generate a self-signed certificate. The above command is just an example.

2. Configure the Stardog server

The Stardog server ultimately needs a Keystore to enable SSL. Continuing with the example command in the above step, we combine our private key (key.pem) and certificate (myCert.crt) into a PCKS12 file to be imported into a Keystore using Java’s keytool utility.

Bundle the certificate (myCert.crt) and private key (key.pem) into a PKCS12 file using the following OpenSSL command:
```
 openssl pkcs12 \
     -export \
     -in myCert.crt \
     -inkey key.pem \
     -out myPkcs.p12
```

Import the .p12 file into a Keystore (my-keystore.jks) using Java’s keytool utility:

 keytool -importkeystore -destkeystore my-keystore.jks -srckeystore myPkcs.p12 -srcstoretype PKCS12

Set the following server settings in the stardog.properties file to specify Keystore information:
```
 # location of the keystore
 javax.net.ssl.keyStore=/path/to/my-keystore.jks
 # the keystore password
 javax.net.ssl.keyStorePassword=changeit
```
If your Keystore type is not jks, you should specify the following additional setting in your stardog.properties:
```
 # substitute in whichever Keystore type you have
 javax.net.ssl.keyStoreType=pkcs12
```
All the above properties are checked first in stardog.properties; then in JVM args passed in from the command line, e.g. -Djavax.net.ssl.keyStorePassword=mypwd:
```
 export STARDOG_SERVER_JAVA_ARGS="-Djavax.net.ssl.keyStore=/path/to/my-keystore.jks -Djavax.net.ssl.keyStorePassword=changeit" 
```
If you’re creating a Server programmatically with Java via ServerBuilder, you can specify values for these properties using the appropriate ServerOptions when creating the server. These values will override anything specified in stardog.properties or via normal JVM args.

3. Configure the Stardog client

The Stardog client uses standard Java security components to access a store of trusted certificates. By default, it trusts a list of certificates installed with the Java runtime environment, but it can be configured to use a custom trust store. The Stardog client uses an X509TrustManager.

Generate a separate Truststore that imports only the certificate using Java’s keytool:
```
 keytool -import -file myCert.crt -keystore my-truststore.jks
```
The above invocation of the keytool utility creates a new trust store named my-truststore.jks and initializes it with the certificate in myCert.crt. The tool will prompt for a passphrase to associate with the trust store. This is not used to encrypt its contents but can be used to ensure its integrity.
Set the STARDOG_JAVA_ARGS environment variable to set the Truststore up in the Stardog CLI environment:
```
 export STARDOG_JAVA_ARGS="-Djavax.net.ssl.trustStore=/path/to/my-truststore.jks -Djavax.net.ssl.trustStorePassword=changeit"
```
When connecting to the Stardog server with the Stardog and Stardog Admin CLI client, it is assumed you are using the default server http://localhost:5820. You may specify a different default server by adding the following JVM argument to the STARDOG_JAVA_ARGS environment variable:
```
 # replace with whatever server url you want
 export STARDOG_JAVA_ARGS=-Dstardog.default.cli.server=https://localhost:5820
```

Java Applications

For custom Java applications that use the Stardog client, the system properties javax.net.ssl.trustStore and javax.net.ssl.trustStorePassword can be set programmatically or when the JVM is initialized.

4. (Optional) Enable SSL for data sources

This section only applies if you plan to add data sources over SSL. Doing so is not required to use SSL with Stardog.

If you plan to communicate with your data sources over SSL, you need Stardog to trust the certificates your data source is presenting to it. In other words, those certificates need to be in the Truststore you set up in step 3. You can see the certificates the data source presents with the following command:

openssl s_client -connect [data source URL]:[port] -showcerts

This will print the certificate chain the data source is presenting to your terminal. You can save this output to a file with:

openssl s_client -connect [data source URL]:[port] -showcerts | sudo tee /path/to/cert-bundle.crt

If the above openssl s_client command doesn’t work as written, try adding the -starttls flag with the protocol of the server you’re trying to connect to. For example, if you were trying to connect to a PostgreSQL server, the command would be openssl s_client -connect [data source URL]:[port] -showcerts -starttls postgres.

Using cert-bundle.crt, run this script to split the certificates in the certificate chain and import them into your Truststore. Make sure to edit the file paths and password to match what’s defined on your machine. If the certificates are already in the Truststore, a message will be printed to this effect; you can run the script a second time to confirm the certificates have been imported successfully.

Next, add your Truststore to the STARDOG_SERVER_JAVA_ARGS environment variable:

export STARDOG_SERVER_JAVA_ARGS="-Djavax.net.ssl.keyStore=/path/to/my-keystore.jks -Djavax.net.ssl.keyStorePassword=changeit -Djavax.net.ssl.trustStore=/path/to/my-truststore.jks -Djavax.net.ssl.trustStorePassword=changeit"

You should now be able to add a data source over SSL successfully.

5. Enable SSL on server startup

You must explicitly tell Stardog to start up with SSL. You have 2 options when doing so: have the server accept connections over both HTTP and HTTPS or only HTTPS.

Optionally support SSL connections

To enable Stardog to optionally support SSL connections, pass --enable-ssl to the server start command.

stardog-admin server start --enable-ssl

By default, the HTTP server will be accessible via port 5820, and the HTTPS server will be accessible via port 5821. If you need to modify the ports Stardog’s HTTP and HTTPS servers use, pass in new port numbers to the --port and --ssl-port options in the server start command.

stardog-admin server start --enable-ssl --port 8081 --ssl-port 8082

Require the server to use SSL only

If you want to require the server to use SSL only, that is, to reject any non-SSL connections, then pass --require-ssl to the server start command:

stardog-admin server start --require-ssl

By default, the HTTPS server will be accessible via port 5820. If you need to modify this port, specify a new port with the --port option:

stardog-admin server start --require-ssl --port 8080

Configuring SSL when Stardog is controlled with `systemctl`

When the Stardog service is managed by systemd, it is required to modify /etc/systemd/system/stardog.service to pass in the --enable-ssl or --require-ssl flags to the server start command. Add the flag of your choosing to the ExecStart line.

For example:

ExecStart = /opt/stardog/stardog-server.sh start --enable-ssl

You will need to run sudo systemctl daemon-reload after making this change.

It is not sufficient to modify the <stardog-installation-directory>/stardog-server.sh script, because changes to that will NOT persist after you upgrade Stardog.

6. Test Stardog client and server connection

Stardog’s HTTP client supports SSL when the https: scheme is used in the database connection string or in the server url. For example, the following Stardog command will initiate an SSL connection:

stardog-admin --server https://localhost:5820 server status

If the client is unable to authenticate to the server, then the connection will fail, and an error message like the following will be generated:

Error during connect.  Cause was SSLPeerUnverifiedException: peer not authenticated

The most common cause of this error is that the server presented a certificate that was not issued by an authority that the client trusts. Refer to Step 3 to ensure that the Truststore was created with the correct certificate. The Stardog client uses standard Java security components to access a store of trusted certificates.

The most common deployment approach requiring a custom trust store is when a self-signed certificate is presented by the Stardog server. For connections to succeed, the Stardog client must trust the self-signed certificate. To accomplish this with the examples given above, the self-signed certificate should be in the myCert.crt file in the keytool invocation.

A client may also fail to authenticate to the server if the hostname in the Stardog database connection string does not match a name contained in the server certificate. This will cause an error message like the following:

Error during connect.  Cause was SSLException: hostname in certificate didn't match

The client does not support connecting when there’s a mismatch; therefore, the only workarounds are to replace the server’s certificate or modify the connection string to use an alias for the same server that matches the certificate.

Steps to set up SSL