Deploying Stardog Securely
This page discusses how to deploy Stardog securely by configuring SSL and Encryption at Rest.
Page Contents
SSL
To ensure that Stardog’s RBAC access control implementation will be effective, all non-administrator access to Stardog databases should occur over network (i.e., non-native) database connections. In other words, embedded Stardog access is inherently insecure and should be used accordingly.
To ensure the confidentiality of user authentication credentials when using remote connections, the Stardog server should only accept connections that are encrypted with SSL.
Configuring Stardog to use SSL
Stardog HTTP server includes native support for SSL. To enable Stardog to optionally support SSL connections, just pass --enable-ssl to the server start command. If you want to require the server to use SSL only, that is, to reject any non-SSL connections, then use --require-ssl.
When starting from the command line, Stardog will use the standard Java properties for specifying keystore information:
javax.net.ssl.keyStorePassword- the passwordjavax.net.ssl.keyStore- location of the keystorejavax.net.ssl.keyStoreType- type of keystore, defaults to JKS
These properties are checked first in stardog.properties; then in JVM args passed in from the command line, e.g. -Djavax.net.ssl.keyStorePassword=mypwd. If you’re creating a Server programmatically 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.
Configuring Stardog Client to use SSL
Stardog HTTP client supports SSL when the https: scheme is used in the database connection string. For example, the following invocation of the Stardog command line utility will initiate an SSL connection to a remote database:
$ stardog query execute https://stardog.example.org/sp2b_10k "ask { ?s ?p ?o }"
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. 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. The details of how a trust store is selected to initialize the trust manager are X509TrustManager.
The client can be directed to use a specific Java KeyStore file as a trust store by setting the javax.net.ssl.trustStore system property. To address the authentication error above, that trust store should contain the issuer of the server’s certificate. Standard Java tools can create such a file. The following invocation of the keytool utility creates a new trust store named my-truststore.jks and initializes it with the certificate in my-trusted-server.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.footnote: See the javax.net.ssl.trustStorePassword system property docs.
$ keytool -importcert -keystore my-truststore.jks -alias stardog-server -file my-trusted-server.crt
The following Stardog command line invocation uses the newly created truststore.
$ STARDOG_SERVER_JAVA_ARGS="-Djavax.net.ssl.trustStore=my-truststore.jks"
$ stardog query https://stardog.example.org/sp2b_10k "ask { ?s ?p ?o }"
For custom Java applications that use the Stardog client, the system property can be set programmatically or when the JVM is initialized.
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 my-trusted-server.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. The matching algorithm used is described in the Apache docs (See BrowserCompatHostnameVerifier)
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.
Encryption at Rest
This feature is Beta and is not ready to be used in production and is provided as a preview to gather feedback from users.
Stardog 7.4.1 contains a preview version of encryption at rest. This feature uses AES 256 bit encryption for writing data to disk. The encryption support requires the user’s environment to include the openssl libcrypto library. This library is available and tested for both Linux and OSX operating environments. See How to Install librycrypto for installation information. Windows is not currently supported.
Data Keys
When encryptions-at-rest is enabled customer data is written to disk only after it is encrypted by a data key. Data keys are AES 256 bit keys that are generated and managed by Stardog upon the users request. A new data key can be requested with the encryption new-key command in the following way:
$ stardog-admin encryption new-key <key name>
If a data key did not already exist encryption new-key will create one. If one did exist it will create a new one and mark it for use with future data. All previously encrypted data will be left as is and thus the old key will remain in the Stardog for use with the data that it encrypted.
At any time data encryption can be disabled with the following command:
$ stardog-admin encryption disable
Note that this will only stop data that is added in the future from being encrypted. All of the data that was previously added will remain encrypted by the key that was active at the time of its insertion into Stardog.
Encryption Password
While data keys are a secure means of encrypting the data that is inserted into Stardog the keys themselves are not encrypted and are thus they are secrets fully know to and managed by Stardog. To overcome this Stardog encourages users to associate a password with their encryption keys. This can be done with the following command:
$ stardog-admin encryption set-password
An encryption password can be changed and disabled at any time with the following commands:
$ stardog-admin encryption change-password
$ stardog-admin encryption remove-password
Stardog does not retain this password nor does it provide a means to reset it. If you use an encryption password you must remember it.
Example Session
Start encrypting data by adding a new key:
$ stardog-admin encryption new-key first-key
$ stardog-admin encryption list-keys
first-key : 34A6B1DD7C1EA00540C4C0B22A445D2A7C6CE46577BA670BEE942E1BEEB07031
At this point any incoming data will be encrypted with the key named first-key. However the key itself is not encrypted and thus we want to add an encryption password with the following command:
$ stardog-admin encryption set-password
Password:
Password:
Now the data keys are all encrypted and thus to access them we will require that same password. The -R option tells the stardog-admin command to ask for the password:
$ stardog-admin encryption list-keys -R
Current Password:
first-key : CE1991DC7F8AC3D25EFFE992CDEF91017E86175D408D39FEC0F7D3933DD4D4A1
Now we will add a new key:
$ stardog-admin encryption new-key next-key
Invalid argument: The passphrase did not unlock the database
In this case we get an error because we failed to provide the now needed password which we will do now with the -R option:
$ stardog-admin encryption new-key next-key -R
Current Password:
$ stardog-admin encryption list-keys -R
Current Password:
next-key : 0713B222DF761A53DB015DA6D5CE973B2879941C737201C499CB7E41BAE65FD3
first-key : CE1991DC7F8AC3D25EFFE992CDEF91017E86175D408D39FEC0F7D3933DD4D4A1
If we wish to now disable data encryption for all future writes we can do so with the following command:
$ stardog-admin encryption disable -R
Current Password:
$ stardog-admin encryption list-keys -R
Current Password:
Disable write :
next-key : 0713B222DF761A53DB015DA6D5CE973B2879941C737201C499CB7E41BAE65FD3
first-key : CE1991DC7F8AC3D25EFFE992CDEF91017E86175D408D39FEC0F7D3933DD4D4A1
Notice that Disable write is listed as the current key. This means that incoming data will not be encrypted.
Additional Security Notes
- network communications: The stardog-admin program communicates passwords and passphrases to the server via HTTP headers. These network communications are vulnerable to copy and replay. The use of SSL communications via
--require-sslis strongly recommended.
How to install libcrypto
OSX
$ brew install openssl
Debian
$ sudo apt-get install openssl
Fedora
$ sudo yum install openssl
Future encryption features
- encryption of temporary files created during large imports: Stardog often creates “spill files” when ingesting data in bulk. The files are temporary in nature. During the time the files exist on disk an outsider could copy files to gain access to the unprotected data. This vulnerability will be addressed.
- user configuration properties: the feature preview supports only one possible encryption library and only one of the library’s supported encryption algorithms. These parameters and others identified by users of the feature preview will become configurable properties in a future release.