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

Self-signed certificates

By default, the Tomcat certificate is created automatically with a blank password when the application is started if one doesn't exist. The heimdall.conf file contains a field called "tomcatPassword", it refers to the private key password in keystore.p12 file and can be freely changed. If the field has null value, a new one is created with a blank value. To create own Tomcat certificate, 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.

Certificate Import

In case you wanted to import your own SSL certificate, a keystore with the keypair with alias "tomcat" is required. Then, we can use keytool command to import our custom keystore to the keystore used by Heimdall (new_keystore.p12 is the keystore user wants to import): When prompted, use the destination password of 'heimdall'.

keytool -importkeystore -srckeystore new_keystore.p12 -destkeystore /opt/heimdall/keystore.p12 -srcalias tomcat -srckeypass <source_tomcat_keypair_password> -destalias tomcat

 Importing keystore new_keystore.p12 to keystore.p12...
 Enter destination keystore password: ******
 Enter source keystore password: ******
 Existing entry alias tomcat exists, overwrite? [no]:  yes
 Enter new alias name   (RETURN to cancel import for this entry):  tomcat

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 particular proxies defined in Heimdall server. To use this mode an appropriate configuration is required, which will be shown later.
  • global: this type of private key with certificate is used by all proxies which don't have defined particular use certificate in configuration. 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

Important: If a keystore is created with JDK 16 or higher, then you will not be able to use it with JDK lower than 16. The reason for that is JDK 16 uses more secure algorithms by default which are not supported by lower versions.

Reading keystore

For reading keystore we recommend using keytool utility.

Do not use gcr-viewer, cause currently it has a problem with reading certificates based on bouncycastle algorithms.

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.

For each vdb configuration it is possible to add data concerning certificates. The following fields must be added:

  • certificate - the certificate in PEM format, it may or may not have a header and a footer
  • certificateAlias - the alias refers to a certificate, preferably it should also refer to a specific vdb name
  • privateKey - the private key in PEM format, it may or may not have a header and a footer

If any of the above fields are left with null value, the certificate configuration will be overwritten by default by global_use_certificate.

Below is an example showing how to add certificate data to vdb configuration:

{
  "certificate": "MIICpjCCAY6gAwIBAgIIMtkhw8lTf9gwDQYJKoZIhvcNAQELBQAwEzERMA8GA1UEAxMISGVpbWRhbGwwHhcNMjEwOTE5MDgxOTQ1WhcNMzEwOTE5MDgxOTQ1WjATMREwDwYDVQQDEwhIZWltZGFsbDCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAIrSQBhUqK5azbMyPhgoFo2oJvP25RrO3y0IKZiE1ELjIAAnR80KROSA4kX6doUDtWDvTmasmJw5JaE+UUVPv+MpGo01qYooiDi7pb+e+DhE5bzKbkglQbm57ipv3JPHNwoLArtCTtTkkuyiZcyVd5GkkfEWnEqzRQ5r8JvHsTTX4fSf45ou1qqEvlDhHO2zUr8s6YEEl4rtoF2cNyiuz6A9Wg1ydRTS4Lvf6RBUEJuc99DQdWSdQ567ptEBI7yJxvRYTRdLpqakPNRVkEzOIQUU1KrQrmkswloO1Ojd/5klFA6c0xfl1DS3oy6LcPEFxf4cNIrinGCQcXjfh7PAg9cCAwEAATANBgkqhkiG9w0BAQsFAAOCAQEAASifK1xhA93AMDea9nKMA/FZ2aYIqlxFc57lIFeftG5zAmPtqbBXTL9VBnZ89gHAbWc7Dj0c/rkmHrxG2Zh16ofv8MY105IKfI65MNVXk/TUPUlzOe8/190msVUrIA8Kx34Ip4WtXVgoHUAf95u3wvZXQCN4x41eZOi0lzAYCXEmAdjhHO63vUnOr7A3i581pJH9NETEeysuyH2vtSoxpiC5c5q7RrXvYTARZc/n5eZFqrJSIohz9fqvsJ4oTAth9XvacENs0g7lJyALmpksGzs+NYe/LkGcqWFljjEAduK4e7wypRDB2eXevA3stIxuIfdLtNuO3EzxpcQsFH/hQg==",
  "certificateAlias": "global_use_certificate",
  "privateKey": "MIIEvAIBADANBgkqhkiG9w0BAQEFAASCBKYwggSiAgEAAoIBAQCK0kAYVKiuWs2zMj4YKBaNqCbz9uUazt8tCCmYhNRC4yAAJ0fNCkTkgOJF+naFA7Vg705mrJicOSWhPlFFT7/jKRqNNamKKIg4u6W/nvg4ROW8ym5IJUG5ue4qb9yTxzcKCwK7Qk7U5JLsomXMlXeRpJHxFpxKs0UOa/Cbx7E01+H0n+OaLtaqhL5Q4Rzts1K/LOmBBJeK7aBdnDcors+gPVoNcnUU0uC73+kQVBCbnPfQ0HVknUOeu6bRASO8icb0WE0XS6ampDzUVZBMziEFFNSq0K5pLMJaDtTo3f+ZJRQOnNMX5dQ0t6Mui3DxBcX+HDSK4pxgkHF434ezwIPXAgMBAAECggEAfbjmVWKulaEk8+pHtCbyLf6gsIfke3/pPOZMjZWWirEZtSnd7AMl23Ah/NBVcCeop45zCae8WpeizcIbZlNQbFE4e7Siw73riL3g4Yb+NC+phG4srGgZezO5T3OZZ7iezxijs6XcsRAFRAvbeAnRjPRnO9mHWFu86c+1y89xXHHZ3DNEYvxZ98UW1ZwuUO/iyke81A7ec+hpjKPMoBPeSdF1+EBgSoId8oAmbjCOA1dRpe2N4N6rYCtqq0P8mmeSnoJc9fMXLmNHrrBMu3e2qsUteVJUrrDl4F9uv4vlCszk9uwgc4Ced5jK2Qc1XidOS+WH6QgLe7XCUrHM07UISQKBgQD137/VpBXe4FNCb3LR6+ZSDJKGLFAEx8KCfRrERci//sYW6RYfoe7cdWPI0vR4D+O4HBYXSHz+W6Sy0dnse/cH58aBG+323bMPmxvXWIf8+q/uoYDAmnbgXLKLuX4mjAa+UNp6wB3QoEeImD5c14SHtTl8eyMSpaPlyblkY0I5lQKBgQCQidf9nQBZODsXT8DSV1E5brc4nBgUlNLsVwRvO8y8n/8EILS3kduH3Qb699YhNqzK3YD/ttMM+c4sWqICG58ZYBO3X0fOK1CnIILUOjgHCWYBihMH+s9qEbr0jU7t1VzBmOt/89CC1brLENr/YcK3I5lUw/PzE4Y07U4+ckmkuwKBgDJGu3pbICG/6yaFlYv5WdJjQb7v5rjjhBGctVF3F5Ky7RyYMu7q9OXdlzbkdBrs3Nqz24yNRQnaAXaTVKV3v869BSk3ZdR6Bvhk9i91qfD/7eO04JgBvdco/VV266XEMkjOTa6WBEK504bJ4s6nPzFkzEl5AHX6quX89szhQxR1AoGASUzesMtyZczSitvzWbjWhF3VpWvj+mwPG7R1l0OobPBnD9zWSVI7FwfMhnIxsd5cevUieoxpM+dr26qLBq6jXOcQmKpFbBUjbd5a+u4bg9YMWTOAu0dC8PPU8DjJkmvmAnhe1iD72Z4ygNEnfuRBL0dqd0Z47Qk1wpmmWJz1JAkCgYA3e8qU2uF+NUsYR0ZqfpFLcTm2R2COsjNIfbb6wv4v3zoVIFBnViVnxs2JcSdkNz1I/WeQx5HbVyFTZJPqLSwxQ6k63y2THu8sLbjfRkLERAEAU/SdqrjcyiqQd5r/Oa8xbzFvTBpnIWoJzyNSnaeGWNUgQgub8I1s4eVwS/Y3zQ=="
}

All changes in key pairs should meet 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 by default using global_use_certificate
  • 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 global_use_certificate.
  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