Link Search Menu Expand Document
Start for Free

Encryption in Transit

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

Page Contents
  1. Steps to setup SSL
    1. 1. Create or acquire a certificate
    2. 2. Configure the Stardog server
    3. 3. Configure the Stardog client
      1. Java Applications
    4. 4. Enable SSL on server startup
      1. Optionally support SSL connections
      2. Require the server to use SSL only
      3. Configuring SSL when Stardog is controlled with systemctl
    5. 5. Test Stardog client and server connection

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 setup SSL

1. Create or acquire a certificate

  • If you already have a .crt file and private key, continue to step 2.
  • If you do not have a cerificate, 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 certificate signing request (CSR) information prompt to generate the private key and self-signed certification.

The -x509 option tells the req utility to create a self-signed cerificate. 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 then be imported into the a Keystore using Java’s keytool utility.

  1. Bundle the certificate and private key together using the following OpenSSL command to take a private key (key.pem) and a certificate (myCert.crt) and combine them into a PKCS12 file.

     openssl pkcs12 \
         -export \
         -in myCert.crt \
         -inkey key.pem \
         -out myPkcs.p12
    
  2. 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
    
  3. 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.

  1. 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.

  2. 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. Enable SSL on server startup

You must explicitly tell Stardog to startup with SSL. You have 2 options when starting up the server with ssl enabled. Have the server accept connections over HTTP and HTTPS or to have the server only accept connections over 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 server 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 in --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 the <stardog-installation-directory>/stardog-server.sh script in order to pass in the --enable-ssl or --require-ssl flags to the server start command.

For example:

${STARDOG_BIN}/stardog-admin server start --daemon --require-ssl --home ${STARDOG_HOME} --port ${PORT} "${@}"

5. 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 server url. For example, the following Stardog command will initiate an SSL connection:

stardog --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 Trustore 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.