This page discusses how to secure communications between clients and Stardog.
- Steps to set up SSL
- 1. Create or acquire a certificate
- 2. Configure the Stardog server
- 3. Configure the Stardog client
- 4. (Optional) Enable SSL for data sources
- 5. Enable SSL on server startup
- 6. 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.
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
.crtfile 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 (
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.
-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.
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
.p12file 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.propertiesfile 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
# 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.
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
ServerOptionswhen creating the server. These values will override anything specified in
stardog.propertiesor via normal JVM args.
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
keytoolutility creates a new trust store named
my-truststore.jksand 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.
STARDOG_JAVA_ARGSenvironment 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
# replace with whatever server url you want export STARDOG_JAVA_ARGS=-Dstardog.default.cli.server=https://localhost:5820
For custom Java applications that use the Stardog client, the system properties
javax.net.ssl.trustStorePassword can be set programmatically or when the JVM is initialized.
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
Using that file, 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.
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.
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
--ssl-port options in the
server start command.
stardog-admin server start --enable-ssl --port 8081 --ssl-port 8082
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
stardog-admin server start --require-ssl --port 8080
When the Stardog service is managed by systemd, it is required to modify
/etc/systemd/system/stardog.service to pass in the
--require-ssl flags to the
server start command. Add the flag of your choosing to the
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.
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.