Why do we need a $gtmcrypt_config file?

GT.M ships with a reference implementation of an encryption plugin which uses OpenSSL to perform various operations for Database Encryption, TLS replication and/or TLS-enabled sockets. The environment variable $gtmcrypt_config points to the configuration file that GT.M should use to set certain OpenSSL options. This configuration file must be in the structure of the libconfig configuration file. For more information on the structure of the libconfig configuration file, refer to http://hyperrealm.github.io/libconfig/libconfig_manual.html#Configuration-Files.

GT.M Database Encryption, TLS replication, and TLS sockets are not prerequisites for each other. You can use these GT.M features together or selectively in your environment depending on the $gtmcrypt_config file for a given process. The $gtmcrypt_config file may contain 2 groups -database and tls. Database Encryption uses the database group of the $gtmcrypt_config file. The database group should contain a list of database files and their corresponding key files. TLS replication and TLS sockets use the tls group of the $gtmcrypt_config file. The tls group contains information such as the location of the root certificate authority, leaf-level certificates with the corresponding private key files, and other TLS configuration options. Under the tls group, you can use the same tlsid or separate tlsids (with a different set of certificates and options) for TLS replication and TLS sockets depending on what establishes better security for your application. In your $gtmcrypt_config file, you do not need to add a database group if you are not using Database Encryption or a tls group if you are not using either TLS replication or TLS sockets.

Here is a sample $gtmcrypt_config file:

/* Database group */
 
database: {
      keys: (
            {
                  dat: "/tmp/mumps.dat";  /* Encrypted database file. */
                  key: "/tmp/mumps.key";  /* Encrypted symmetric key. */
            },
            {
                  dat: "/tmp/a.dat";
                  key: "/tmp/a.key";
            },
            ...
      );
}
 
/* TLS group */
 
tls: {
      /* Certificate Authority (CA) verify depth provides an upper limit on the number of CAs to look up for verifying a given
       * certificate. The depth count is described as ''level 0:peer certificate'', ''level 1: CA certificate'',
       * ''level 2: higher level CA certificate'', and so on. The default verification depth is 9.
       */
      verify-depth: 7;
 
      /* CAfile: points to a file, in PEM format, describing the trusted CAs. The file can contain several CA certificates identified by:
       * -----BEGIN CERTIFICATE-----
       * ... (CA certificate in base64 encoding) ...
       * -----END CERTIFICATE-----
       * sequences.
       */
      CAfile: "/home/jdoe/current/tls/certs/CA/gtmCA.crt";
 
      /* CApath: points to a directory containing CA certificates in PEM format. The files each contain one CA certificate. The files are
       * looked up by the CA subject name hash value, which must hence be available. If more than once certificate with the same
       * name hash value exists, the extension must be different (e.g. 9d66eef0.0, 9d66eef0.1 etc). The directory is typically
       * created by the OpenSSL tool 'c_rehash'.
       */
      CApath: "/home/jdoe/current/tls/certs/CA/";
      
      /* crl: points to a file containing list of revoked certificates. This file is created by the openssl utility. */
      crl: "/home/jdoe/current/tls/revocation.crl";
 
      /* Timeout (in seconds) for a given session. If a connection disconnects and resumes within this time interval, the session 
       * is reused to speed up the TLS handshake. A value of 0 forces sessions to not be reused. The default value is 1 hour.
       */
      session-timeout: 600;
 
      /* ssl-options: specifies OpenSSL options to be set or cleared. */
      ssl-options: "SSL_OP_NO_SSLv2:SSL_OP_NO_SSLv3";
  
      /* List of alphanumeric TLS configuration identifiers (the "tlsid" used by GT.M processes) which must begin with a letter.
       * Each configuration consists of name/value pairs for specific options like certificate, key and format.
       */
      PRODUCTION: {
            /* Format of the certificate and private key pair. Currently, the GT.M TLS plug-in only supports PEM format. */
            format: "PEM";
            /* Path to the certificate. */
            cert: "/home/jdoe/current/tls/certs/Malvern.crt";
            /* Path to the private key. If the private key is protected by a passphrase, an obfuscated version of the password
             * should be specified in the environment variable which takes the form gtmtls_passwd_<identifier>. For instance,
             * for the below key, the environment variable should be 'gtmtls_passwd_PRODUCTION'.
             * Currently, the GT.M TLS plug-in only supports RSA private keys.
             */
            key: "/home/jdoe/current/tls/certs/Malvern.key";
            /* Global options can be overridden here */
      };
 
      DEVELOPMENT: {
            format: "PEM";
            cert: "/home/jdoe/current/tls/certs/BrynMawr.crt";
            key: "/home/jdoe/current/tls/certs/BrynMawr.key";
      };
};

As this $gtmcrypt_config file contains both the database and tls groups, you need to set the gtm_passwd and gtmtls_passwd_<tlsid> environment variables using the maskpass utility. For more information on these environment variables, refer to “Environment Variables”. Note that in this $gtmcrypt_config file, verify-depth, CAfile, CApath, etc are OpenSSL options and PRODUCTION and DEVELOPMENT are 2 different tlsids which can be used for TLS replication and/or TLS sockets. By default the GT.M reference implementation plugin disables SSLv2, SSLv3, TLSv1, and TLSv1.1. You can selectively enable those protocols as needed (with ssl-options: !SSL_OP_NO_SSLv2:!SSL_OP_NO_SSLv3:!SSL_OP_NO_TLSv1:!SSL_OP_NO_TLSv1_1). Please note that OpenSSL, as compiled by the platform vendor, may also disable protocols.