Enable SSL encryption

Eugenia Kuzina

ADPG supports SSL encryption of incoming traffic for all services in an ADPG cluster. To use this feature in an ADPG cluster, it is necessary to obtain certificates and enable SSL via ADCM UI.

When SSL is enabled, all services of an ADPG cluster use SSL encryption and the HTTPS protocol instead of HTTP.

IMPORTANT

  • It is strongly recommended to save certificate and key files outside the ADPG data directory (the default path is /pg_data1/adpg16), since the data directory name will be changed during a major upgrade.

  • It is necessary to generate SSL certificates with SAN (Subject Alternative Names). Short host names and fully qualified domain names (FQDN) should be present in the alt_names section of a certificate configuration file.

  • Keys protected with a passphrase are not supported.

  • When upgrading from ADPG v16.3.3 with enabled SSL, it is recommended to switch SSL off, then upgrade to ADPG 16.3.4 and use the Manage SSL cluster action to enable SSL.

Enable SSL via ADCM

To enable SSL, follow the steps below:

  1. On the Clusters page, run the Manage SSL action.

    Run the Manage SSL action
    Run the "Manage SSL" action

  2. In the window that opens, switch on the Enable SSL toggle button.

    The Run an action: Manage SSL window
    The "Run an action: Manage SSL" window

    SSL settings are displayed below the Enable SSL toggle button. Parameters highlighted in red are required.

    SSL parameters
    SSL parameters

  3. Specify SSL settings according to your environment. All paths to certificates and keys should be specified as absolute. It is not recommended to save certificate and key files in the ADPG data directory (the default path is /pg_data1/adpg16), since the data directory name will be changed during a major upgrade.  

    The table below lists SSL parameters available for editing. The File location column describes on which cluster hosts a file should be stored at the specified path.

    Parameter Description File location

    ADPG generic certificate

    Path to a generic ADPG certificate that meets the requirements for all ADPG services

    On each cluster host where the ADPG, Balancer, Etcd, or Monitoring services are installed

    ADPG generic certificate key

    Path to a generic ADPG certificate key that meets the requirements for all ADPG services. The permissions for the generic ADPG certificate key file should be set to 0644 — the file owner has read and write permissions, while the group and other users can only read the file. If the Balancer service (HAProxy) is used, the file name should end with the following extension: .crt.key, for example, generic.crt.key

    On each cluster host where the ADPG, Balancer, Etcd, or Monitoring services are installed

    Arenadata PostgreSQL certificate

    Path to a separate certificate with special rights for the ADPG service (PostgreSQL). It is equivalent to the ssl_cert_file parameter from the postgresql.conf file. The postgres user should have the owner permissions on the certificate file

    On each cluster host where the ADPG service is installed

    Arenadata PostgreSQL certificate key

    Path to a key of a separate certificate for the ADPG service (PostgreSQL). It is equivalent to the ssl_key_file parameter from the postgresql.conf file. The permissions for the PostgreSQL certificate key file should be set to 0600 — the file owner has read and write permissions, while the group and other users do not have any permissions. The postgres user should have the owner permissions on the certificate key file

    On each cluster host where the ADPG service is installed

    CA file

    Path to a file containing the SSL server certificate authority (CA) for verifying incoming connections. It is equivalent to the ssl_ca_file parameter from the postgresql.conf file

    On each cluster host where the ADPG, Balancer, Etcd, or Monitoring services are installed

    S3 backup CA file

    Path to a file containing the SSL server certificate authority (CA) for an S3 repository storage. Specify this parameter if backups are enabled and the Repo type parameter is set to s3

    On each cluster host where the ADPG service is installed

  4. After you specify SSL parameters, click Next.

    The Run an action: Manage SSL window with specified SSL settings
    The "Run an action: Manage SSL" window with specified SSL settings

  5. On the Confirmation tab, click Run to execute the Manage SSL action.

    The Confirmation tab
    The "Confirmation" tab

    After the Manage SSL action is executed, SSL settings are added to the SSL configuration section of the ADPG service configuration. It contains the following fields:

    • Enable SSL — a read-only field that is set to true if SSL is enabled.

    • postgresql.conf — a read-only field that contains SSL settings.

    • PG_HBA — a field to specify rules for SSL connections.

  6. After the Manage SSL action is finished, it is necessary to allow SSL connections for the ADPG server. To do this, open the Primary configuration tab of the ADPG service, expand the SSL configuration section in the Configuration tree, and click the PG_HBA field.

    The SSL configuration section
    The "SSL configuration" section

    Add a new record to allow SSL connections to the PG_HBA field of the SSL configuration section. For example:

    hostssl     all     all     0.0.0.0/0     cert
    The PG_HBA field
    The "PG_HBA" field

    This record allows all users (all) to utilize SSL connections (hostssl) to all databases (all) from all IPv4 addresses (0.0.0.0/0). Authentication is performed using SSL client certificates (cert). See Overview of PG_HBA configuration for details.

  7. Save the changes and run the Reconfigure & Restart action to apply new settings.

NOTE

The Manage SSL action overrides SSL parameters specified in the postgresql.conf and Custom postgresql.conf sections located in the Configuration tree of the ADPG service. Note that if you disable SSL using the Manage SSL action, the SSL settings from these sections will be applied. To avoid ambiguous situations, it is recommended to remove the SSL settings from these sections before you enable SSL via the Manage SSL cluster action.

Use client certificates

For a hostssl record in the PG_HBA section, you can add the clientcert=verify-ca or clientcert=verify-full authentication option.

For a hostssl entry with clientcert=verify-ca, the server verifies that the client’s certificate is signed by one of the trusted certificate authorities. If clientcert=verify-full is used, the server does not only verify the certificate chain, but it also checks whether the user name or its mapping matches cn (Common Name) of the provided certificate. Note that certificate chain validation is always ensured when the cert authentication method is used.

Intermediate certificates that chain up to existing root certificates can also be included in the file specified by the CA file parameter if you wish to avoid storing them on clients. Certificate Revocation List (CRL) entries are also checked if the ssl_crl_file or ssl_crl_dir parameter is set via ADCM in the postgresql.conf field.

The clientcert authentication option is available for all authentication methods, but only in PG_HBA records specified as hostssl. When clientcert is not used, the server verifies the client certificate against its CA file only if a client certificate is provided and the CA is configured.

There are two approaches to ensuring that users provide a certificate when logging in:

  • Use the cert authentication method for hostssl entries in the PG_HBA records. The certificate will be used for both authentication and security of the SSL connection. See Certificate authentication. (It is not necessary to specify any clientcert options explicitly when using the cert authentication method.) In this case, cn (Common Name) provided in the certificate is checked against the user name or an applicable mapping.

  • Use any authentication method for hostssl entries with the verification of client certificates by setting the clientcert authentication option to verify-ca or verify-full. The former option only enforces that the certificate is valid, while the latter also ensures that cn (Common Name) in the certificate matches the user name or an applicable mapping.

For information on how to set up certificates on the client, see SSL Support.

Found a mistake? Seleсt text and press Ctrl+Enter to report it