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.

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 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. 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:
```
      
=> ALTER TLS CONFIGURATION server CERTIFICATE server_certificate ADD CA CERTIFICATES ca_certificate TLSMODE 'VERIFY_CA';
ALTER TLS CONFIGURATION
```

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 service endpoints.

Mutual TLS for cluster operations

When you configure a database for TLS/SSL security in mutual mode, incoming client requests verify the server certificate. Each client needs to present a certificate and private key so that the server can verify the client. For the server, this means validating that the client certificate was signed by a chain of CA certificates terminating in a trusted CA certificate, typically but not necessarily a root (self-signed) CA certificate. For the client, this means performing the same validation as the server for the server certificate and ensuring that the server certificate belongs to the intended server.

Important

Validating the server hostname is optional. It is based on your network topology, client usage, and security requirements.

Generate and set the certificate for the NMA or HTTPS service with hostname validation

When generating a server certificate where the client validates the server hostname, the certificate must be valid for the expected hostnames and IPs.

Vertica

=> CREATE CERTIFICATE certificate_usable_by_nma_and_https_service
SUBJECT '/C=US/ST=Massachusetts/L=Cambridge/O=OpenText/OU=Vertica/CN=Vertica server alt/emailAddress=doesntmatter@example.com'
SIGNED BY rootca
EXTENSIONS 'nsComment' = 'Vertica/NMA server cert with IP hostname', 'extendedKeyUsage' = 'serverAuth,clientAuth',
'subjectAltName' = 'IP.1:192.168.1.101,IP.2:192.168.1.102,IP.3:192.168.1.103,IP.4:192.168.1.104,DNS.1:mynode1.mydomain.com,DNS.2:mynode2.mydomain.com,DNS.3:mynode3.mydomain.com,DNS.4:mynode4.mydomain.com'

There are 4 IPs in this example, as it is a 4-node cluster. Generate the NMA certificate with 'serverAuth,clientAuth' as the extendedKeyUsage option when the server TLS configuration in Vertica is in VERIFY_CA mode or higher. Otherwise, use serverAuth.

Enable Mutual TLS for cluster operations

To enable mutual TLS for cluster operations:

Generate the server and client certificates. For more information, see Create the server certificate and Create the client certificate. To generate the server certificate, use the subjectAltName setting mentioned in Generate and set the certificate for the NMA or HTTPS service with hostname validation.
Either create a separate NMA client/server certificate or reuse the Vertica server certificate that is generated. Specify 'extendedKeyUsage' = 'serverAuth,clientAuth' when generating the certificate to allow NMA to present a certificate to Vertica.
Export the NMA certificate and key and the CA certificate to a location accessible to each node on the cluster.
For each node, point the NMA at the new certificate, key, and CA certificate. For more information, see Custom certificates.
Set the TLS mode environment variable for NMA before starting NMA as shown here.
```
export NMA_CLIENT_TLS_MODE=VERIFY_FULL
```
Restart the NMA on each node.
Export the CA certificate from Step 1 to a location accessible to the client.
Configure the server TLS CONFIGURATION object as mentioned above. Use VERIFY_CA for the TLS mode option.
For clients calling the API, use the exported client certificate, client key, and trusted CA certificate to perform mutual TLS.

TLSMode environment variable for SQL client connections

The environment variable NMA_CLIENT_TLS_MODE controls TLS mode for NMA SQL client connections. You must export the value on NMA startup. The TLS modes are:

enable # the default
verify_ca
verify_full

Each value specifies a different set of requirements that the Vertica server needs to connect with NMA for operations using the NMA as a SQL proxy. The Vertica server has requirements of the NMA certificate, but this is independent of the NMA requirements of the Vertica server certificate.

Enable – This is the current behavior. The system accepts Vertica server certificates with no validation.
verify_ca – This means the Vertica server certificate is signed by a trusted CA.
verify_full – This means the Vertica server certificate is signed by a trusted CA and validated for the expected hostname.

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

Mutual TLS for cluster operations

Important

Generate and set the certificate for the NMA or HTTPS service with hostname validation

Enable Mutual TLS for cluster operations

TLSMode environment variable for SQL client connections

In this section