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.

Only the dbadmin user can authenticate to the HTTPS service.

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.

Important

During installation, the install_vertica script generates self-signed certificates in the /opt/vertica/config/https_certs directory. Vertica uses these certificates to bootstrap the HTTPS service on a new cluster—they are not suitable for production. Certificates in the TLS configuration supersede those in the /opt/vertica/config/https_certs directory.

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 https://10.20.30.40:8443/endpoint

Important

Due to security concerns, this request method is not recommended. For example, the command history can save the dbadmin password.

Certificate authentication

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

$ curl https://10.20.30.40:8443/endpoint \
    --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.

Note

To demonstrate a comprehensive setup, the following sections use a self-signed CA certificate that signs both the client and server certificates. In a production environment, you should replace the self-signed CA with a trusted CA.

For details about importing a CA certificate, see Generating TLS certificates and keys.

Create a CA certificate

Important

A self-signed CA certificate is convenient for development purposes, but you should always use a proper certificate authority in a production environment.

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:

Generate or import a private key. The following command generates a new private key:
```
      
=> CREATE KEY ca_private_key TYPE 'RSA' LENGTH 4096;
CREATE KEY
```

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;

Note

The CA certificate SUBJECT must be different from the SUBJECT of any certificate that it signs.

For example:

      
=> CREATE CA CERTIFICATE SSCA_cert
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:

Generate the server private key:

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

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;
CREATE CERTIFICATE

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;
CREATE CERTIFICATE

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:

Alter the default server configuration. Mutual TLS requires that you set TLSMODE to TRY_VERIFY or VERIFY_CA:

      
=> ALTER TLS CONFIGURATION server CERTIFICATE server_certificate ADD CA CERTIFICATES ca_certificate TLSMODE 'VERIFY_CA';

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 verify the 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:

Generate the client key:

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

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/emailAddress=example@example.com'
SIGNED BY ca_certificate
EXTENSIONS 'nsComment' = 'Vertica client cert', 'extendedKeyUsage' = 'clientAuth'
KEY client_private_key;
CREATE CERTIFICATE

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
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:

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 '0.0.0.0/0';
CREATE AUTHENTICATION
```
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:
```
      
=> GRANT AUTHENTICATION auth_record TO PUBLIC;
GRANT AUTHENTICATION
```

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

HTTPS service

Important

Password authentication

Important

Certificate authentication

Note

Create a CA certificate

Important

Note

Create the server certificate

Alter the TLS configuration

Create the client certificate

Create an authentication record

In this section