HTTPS service

The HTTPS service lets clients securely access and manage a Vertica database with a REST API. This service listens on port 8443 and runs on all nodes.

Most HTTPS service endpoints require authentication, and only the dbadmin user can authenticate to the HTTPS service. The following endpoints serve documentation on the endpoints and do not require authentication (unless your TLSMODE is VERIFY_CA):

  • /swagger/ui
  • /swagger/{RESOURCE}
  • /api-docs/oas-3.0.0.json

This service encrypts communications with mutual TLS (mTLS). To configure mTLS, you must alter the server TLS configuration with a server certificate and a trusted Certificate Authority (CA). For mTLS authentication, each client request must include a certificate that is signed by the CA in the server TLS configuration and specifies the dbadmin user in the Common Name (CN). For additional details about these TLS components and Vertica, see TLS protocol.

Password authentication

The following command connects to the HTTPS service from outside the cluster with the username and password:

$ curl --insecure --user dbadmin:db-password

Certificate authentication

Client requests authenticate to the HTTPS service with a private key and certificate:

$ curl \
    --key path/to/client_key.key \
    --cert path/to/client_cert.pem \

When the Vertica server receives the request, it verifies that the client certificate is signed by a trusted CA and specifies the dbadmin user. To establish this workflow, you must complete the following:

  • Alter the server TLS configuration with a server certificate and a CA.
  • Generate a client certificate that is signed by the CA in the server TLS configuration. The client certificate SUBJECT must specify the dbadmin user.
  • Grant TLS access to the database.

Create a CA certificate

A CA is a trusted entity that signs and validates other certificates with its own certificate. The following example generates a self-signed root CA certificate:

  1. Generate or import a private key. The following command generates a new private key:

    => CREATE KEY ca_private_key TYPE 'RSA' LENGTH 4096;

  2. Generate the certificate with the following format. Sign the certificate the with the private key that you generated or imported in the previous step:

    => CREATE CA CERTIFICATE ca_certificate
    SUBJECT '/C=country_code/ST=state_or_province/L=locality/O=organization/OU=org_unit/CN=Vertica Root CA'
    VALID FOR days_valid
    EXTENSIONS 'authorityKeyIdentifier' = 'keyid:always,issuer', 'nsComment' = 'Vertica generated root CA cert'
    KEY ca_private_key;

    For example:

    SUBJECT '/C=US/ST=Massachusetts/L=Cambridge/O=OpenText/OU=Vertica/CN=Vertica Root CA'
    VALID FOR 3650
    EXTENSIONS 'nsComment' = 'Self-signed root CA cert'
    KEY SSCA_key;

Create the server certificate

The server private key and certificate verify the Vertica server's identity for clients:

  1. Generate the server private key:

    => CREATE KEY server_private_key TYPE 'RSA' LENGTH 2048;
  2. Generate the server certificate with the following format. Include the server_private_key, and sign it with the CA certificate:

    => CREATE CERTIFICATE server_certificate
    SUBJECT '/C=country_code/ST=state_or_province/L=locality/O=organization/OU=org_unit/CN=Vertica server certificate'
    SIGNED BY ca_certificate
    KEY server_private_key;

    For example:

    => CREATE CERTIFICATE server_certificate
    SUBJECT '/C=US/ST=Massachusetts/L=Burlington/O=OpenText/OU=Vertica/CN=Vertica server certificate'
    SIGNED BY ca_certificate
    KEY server_private_key;

Alter the TLS configuration

After you generate the server certificate, you must alter the server's default TLS configuration with the server certificate and its CA. When you change the server TLS configuration, the HTTPS service restarts, and the new keys and certificates are added to the catalog and distributed to the nodes in the cluster:

  1. Alter the default server configuration. Mutual TLS requires that you set TLSMODE to TRY_VERIFY or VERIFY_CA. If you use VERIFY_CA, all endpoints (including the documentation-related endpoints /swagger/ui, /swagger/{RESOURCE}, and /api-docs/oas-3.0.0.json) require authentication:

  2. Verify the changes on the TLS configuration object:

     => SELECT name, certificate, ca_certificate, mode FROM TLS_CONFIGURATIONS WHERE name='server';
       name  |    certificate     | ca_certificate |    mode
      server | server_certificate | ca_certificate | VERIFY_CA
     (1 row)

Create the client certificate

The client private key and certificate verifythe client's identity for requests. Generate a client private key and a client certificate that specifies the dbadmin user, and sign the client certificate with the same CA that signed the server certificate.

The following steps generate a client key and certificate, and then make them available to the client:

  1. Generate the client key:

       => CREATE KEY client_private_key TYPE 'RSA' LENGTH 2048;

  2. Generate the client certificate. Mutual TLS requires that the Common Name (CN) in the SUBJECT specifies a database username:

       => CREATE CERTIFICATE client_certificate
       SUBJECT '/C=US/ST=Massachusetts/L=Cambridge/O=OpenText/OU=Vertica/CN=dbadmin/'
       SIGNED BY ca_certificate
       EXTENSIONS 'nsComment' = 'Vertica client cert', 'extendedKeyUsage' = 'clientAuth'
       KEY client_private_key;

  3. On the client machine, export the client key and client certificate to the client filesystem. The following commands use the vsql client:

    $ vsql -At -c "SELECT key FROM cryptographic_keys WHERE name = 'client_private_key';" -o client_private_key.key
    $ vsql -At -c "SELECT certificate_text FROM certificates WHERE name = 'client_certificate';" -o client_cert.pem

    In the preceding command:

    • -A: enables unaligned output.
    • -t: prevents the command from outputting metadata, such as column names.
    • -c: instructs the shell to run one command and then exit.
    • -o: writes the query output to the specified filename.

    For details about all vsql command line options, see Command-line options

  4. Copy or move the client key and certificate to a location that your client recognizes.

    The following commands move the client key and certificate to the hidden directory ~/.client-creds, and then grants the file owner read and write permissions with chmod:

    $ mkdir ~/.client-creds
    $ mv client_private_key.key ~/.client-creds/client_key.key
    $ mv client_cert.pem ~/.client-creds/client_cert.pem
    $ chmod 600 ~/.client-creds/client_key.key ~/.client-creds/client_cert.pem

Create an authentication record

Next, you must create an authentication record in the database. An authentication record defines a set of authentication and the access methods for the database. You grant this record to a user or role to control how they authenticate to the database:

  1. Create the authentication record. The tls method requires that clients authenticate with a certificate whose Common Name (CN) specifies a database username:
       => CREATE AUTHENTICATION auth_record METHOD 'tls' HOST TLS '';
  2. Grant the authentication record to a user or to a role. The following example grants the authentication record to PUBLIC, the default role for all users:

After you grant the authentication record, the user or role can access HTTPS service endpoints.