Securing Heimdall

Best Practices

Please follow the following best practices:

  • Lock down access by creating an ACL or Security Group to block access from the Internet;
  • Create a read-only user for use by developers who need to view logs for monitoring;
  • Set the admin password to a secure password;
  • If you wish to have logs strip the actual SQL queries, in the VDB, you can set the vdb setting of "paranoia" to true;
  • With proxy authentication disabled for Postgres and SQL Server, password passthrough is enabled, so the Database takes care of password authentication. This is not supported for MySQL, as the password is required to be hashed. If authentication is disabled, then for MySQL, it will simply use the data source's configured username and password for authentication.;
  • Lock down the interface with HTTPS;
  • Set a limited-acccess user for the data source configuration, with access to the "heimdall" schema/database for replication lag detection;
  • Enable TLS as desired on the back-end for database access.

Password Storage

Heimdall, in some cases needs to store passwords in a variety of formats for different purposes. Each case is documented here:

  1. All configuration information is kept in /opt/heimdall/config, accessible only to root, including password information;
  2. By default, for Postgres and SQL Server, VDB authentication is set to "passthrough" which means that individual user's credentials are not stored on Heimdall at all;
  3. For MySQL, due to the nature of authentication, individual user's credentials must be configured in effectively plaintext. These are stored in the vdb configuration file, and used to both authenticate the user into the proxy, and then to authenticate the user into the database;
  4. For all configurations, an alternative to storing a user's vdb password is to configure SQL based authentication, in which case the passwords will be stored in a database table instead;
  5. For GUI authentication, passwords are stored in Salted SHA format, compatible with OpenLDAP, i.e. automation could be configured to copy the same credential format between the two systems.
  6. One additional cleartext password is stored in the Data source configuration tab, which is used to authenticate health checks and for performing replication lag detection. No access to actual data is necessary for this user's login.

NOTE: In AWS, it is possible to configure Heimdall to store the entire configuration in an AWS Secret. Please see the AWS Environment page for details on the hdSecretKey option. Using this ensures all passwords in the configuration are also stored encrypted and not on the EBS volume of the server.

Password Rotation

For the GUI passwords, rotation can simply be done via the user's tab. For Database password authentication, there are several categories: 1. In the case of Active directory authenticated users, credentials will be cached on a success for up to five minutes. On a failure however, the credentials will be re-queried against Active directory, and will be updated if success occurs. This ensures that as soon as AD is updated, the proxy will also be updated; 2. In the case of passthrough authentication, connections are established with the user's credentials on connect, so again, as soon as the password is changed, the credentials will be reflected; 3. If the proxy is using "proxy authentication" then the credentials are stored against the VDB configuration itself. To perform a rotation, you can add a new user/password combination without removing the old one. During this period, both will be acceptable. Then, once the application and database is updated to use the new credentials, then original password can be removed from the proxy. This allows the issue of timing the password changes betweeen the application and database to ignore the proxy, since it will accept both at the same time.

Supported Encryption

Heimdall allows TLS security to be enabled on each VDB, and to be made required as well. In the case of Postgres and MySQL, TLS 1.3 will be used by default if the client supports it, while TLS 1.3 will be used for SQL Server, as SQL Server itself does not use TLS 1.3 yet, and all driver libraries will need to be updated for this to work.

For back-end connectivity, as we use the vendor JDBC drivers to connect to the database, we support all connectivity options that these drivers support for encryption. Please see the vendor JDBC driver help pages for specific details.

Enabling HTTPS for Management Server

To enable HTTPS, on the Linux command line, do the following (this will generate a self-signed certificate):

keytool -genkey -alias tomcat -storetype PKCS12 -keyalg RSA -keysize 2048 -keystore /opt/heimdall/keystore.p12 -validity 3650

Enter keystore password: <use "heimdall">
 Re-enter new password:
 What is your first and last name?
 [Unknown]:
 What is the name of your organizational unit?
 [Unknown]:
 What is the name of your organization?
 [Unknown]:
 What is the name of your City or Locality?
 [Unknown]:
 What is the name of your State or Province?
 [Unknown]:
 What is the two-letter country code for this unit?
 [Unknown]:
 Is CN=Unknown, OU=Unknown, O=Unknown, L=Unknown, ST=Unknown, C=Unknown correct?
 [no]: yes

Once done, restart the Heimdall server, and port 8443 will be used for HTTPS.

Please see the man page for keytool for importing in an existing SSL certificate if desired.

VDB Proxy TLS Support

TLS is a way of providing a safe connection between Heimdall server and client application while using proxy. By default Heimdall server enables use of TLS and decision about activating it depends on client side.

The core of TLS in Heimdall server are private keys with certificates stored in a keystore. Changes made in keystore can cause change of behavior of TLS in proxy.

Certificate binding

Heimdall allows binding of certificates in two modes:

  • per-vdb: this type of private key with certificate is used only by one proxy defined in Heimdall server. Particular use certificate is stored in keystore, using alias same as lowercased name of proxy, for example: proxy "PostgreSQLProxy" would use certificate with alias "postgresqlproxy".
  • global: this type of private key with certificate is used by all proxies which don't have defined particular use certificate. In keystore can exist only one private key with certificate used as global use certificate. Global use certificate alias in keystore is "global_use_certificate". If global use certificate doesn't exist in keystore, it is going to be autogenerated by Heimdall server.

Default Configuration

By default, when TLS use is called from client side, user doesn't have to configure anything for TLS - Heimdall server will create a keystore and generate a global use certificate.

Created by Heimdall server keystore will have below properties:

  • keystore type will be JKS
  • keystore file name will be keystore.p12
  • password to keystore will be heimdall
  • keystore file will be placed in heimdall server/proxy directory

Generated by Heimdall server global use certificate will have below properties:

  • generated will be private key with certificate
  • generated pair will have alias tomcat (note--this matches the HTTPS certificate for the central manager)
  • generated pair password will be blank
  • algorithm used to generate key pair will be SHA-256 with RSA
  • key size will be 2048
  • global use certificate will have self-signed certificate with CN=Heimdall
  • certificate of global use certificate will be valid from day before the day of generating
  • certificate of global use certificate will expire after 10 years minus 1 day

User Configuration

Heimdall server accepts configuring keystore by user, but doesn't provide a functionality for doing this. In this situation suggested is using third-party applications (for example: KeyStore Explorer) to make changes in keystore used by Heimdall server.

Creating keystore

For the situation when user want to create or replace a keystore by himself for Heimdall server, then below restrictions should be met:

  • keystore type is JKS (may work with PKCS#12 type)
  • keystore file is named keystore.p12
  • password to keystore is heimdall
  • keystore file is stored in the same directory as Heimdall server

Managing certificates

The first thing to mention before managing certificates is that Heimdall server is using private keys with certificates (key pairs). Single keys or single certificates won't work with Heimdall Server.

All changes in key pairs should met below restrictions:

  • alias of key pair should match the restrictions defined for particular and global use certificates, other defined aliases won't be used by Heimdall Server
  • key pair password is blank
  • recommended is using key pair with algorithm SHAx with RSA/DSA (not guaranteed that all algorithms is going to work, because it depends on client application too)

Changes made in keystore may require reconnecting from client application to proxy, after this changes should be applied for TLS.

Example scenario of configuration

Simple scenario of creating keystore, and adding global use certificate to keystore: 1. Run application to manage keystore (for example: KeyStore Explorer). 2. Choose option to create new keystore. 3. As type of keystore select type JKS. 4. Save created keystore. 5. As password to keystore set heimdall. 6. As directory to save choose directory where Heimdall server is placed. 7. After saving, choose option for generating new key pair. 8. Set size of key size as 2048 and as algorithm choose SHA-512 with RSA. 9. Set name of key pair by configuring CN to value Heimdall. 10. Go further to find option to configure alias, as alias set value tomcat. 11. As password to key pair set blank value. 12. Key pair should be fully configured, save changes in keystore.

Extra informations

This section provides informations which didn't found place in other sections about TLS but may be helpful: - format for key pairs in Heimdall server is X509