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

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.

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

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;
   
   

   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:

1. Generate the server private key:

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

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

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:

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

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

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

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 '0.0.0.0/0';
      CREATE AUTHENTICATION
      
   

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:

         
      => GRANT AUTHENTICATION auth_record TO PUBLIC;
      GRANT AUTHENTICATION
      
   

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