Deephaven public and private key authentication

This document outlines the various types of public and private keys used for authentication within the Deephaven platform. It explains their roles in securing different processes and user interactions, covering key file formats, relevant configuration properties, and key generation procedures.

Server-Side Public Key Registration

For a user to authenticate using a private key, their corresponding public key must be registered on the Deephaven server. There are primarily two mechanisms for this:

  1. Authorized Keys File (~/.ssh/authorized_keys or similar): This is a standard SSH mechanism. The file (often ~/.ssh/authorized_keys, but configurable via the authentication.psk.authorizedKeysFiles property as detailed in the Authentication server configuration) associates usernames with their public keys. Each line typically contains a public key (e.g., from an id_rsa.pub or id_ed25519.pub file). This method is common for service accounts and automated tasks.

  2. dsakeys.txt File: Deephaven can also use a dedicated file, conventionally named dsakeys.txt (typically located in a central configuration directory like /etc/deephaven/config/ or /etc/sysconfig/deephaven/auth/), to map usernames to their public keys. This file is often used in conjunction with certain Access Control List (ACL) providers, such as a file-based DbAclProvider. Each entry in dsakeys.txt links a user to their public key, enabling authentication. The format and management of this file are specific to the Deephaven configuration.

The server uses these registered public keys to verify the identity of clients presenting a corresponding private key.

User private keyfile

Users can authenticate to Deephaven using private key files stored on their client machines. This method provides an alternative to password-based authentication, offering a secure way to access the platform, especially for programmatic access or scripts. The corresponding public key must be registered on the server, either in an Authorized Keys file (as described under "Server-Side Public Key Registration") or within the configuration of the active Access Control List (ACL) provider (e.g., via the dsakeys.txt file if a file-based ACL provider is in use).

Users typically generate their private key files (e.g., id_rsa or id_ed25519) and corresponding public keys using tools like ssh-keygen. The private key must be kept secure on the client machine. Client applications or scripts can be configured to use this private key for authentication, often by specifying its path in a configuration setting (e.g., deephaven.client.privateKeyPath=/path/to/user/private_key).

How to create authentication keys

To generate a public/private key pair for authentication, you can use standard tools like ssh-keygen. It's recommended to use strong key algorithms such as Ed25519 or RSA.

Example using Ed25519:

ssh-keygen -t ed25519 -f /path/to/your/deephaven_user_key -C "your_username@deephaven"

Example using RSA (4096-bit):

ssh-keygen -t rsa -b 4096 -f /path/to/your/deephaven_user_key -C "your_username@deephaven"

This will create two files:

  • /path/to/your/deephaven_user_key (the private key)
  • /path/to/your/deephaven_user_key.pub (the public key)

The content of the .pub file needs to be added to the server's public key registration (e.g., an Authorized Keys file or dsakeys.txt as described under "Server-Side Public Key Registration"), associated with your username. The private key file should be kept secure and used by your client application.

Note on Deephaven-specific key utilities

While ssh-keygen is the standard tool for users to generate their personal authentication keys, Deephaven also includes utilities like generate-iris-keys. This utility is primarily designed for generating key pairs used by Deephaven services for secure inter-process communication (e.g., worker-to-application-server authentication). These are typically system-level keys and are not usually generated or managed directly by end-users for their own login purposes. For end-user authentication, ssh-keygen as described above is the recommended method.

Securing your private key

Always treat your private key file like a password; other users should not be allowed to read it:

chmod 600 <path/to/private/key/file>

This command restricts read/write access to the file owner. Verify permissions using:

ls -l <path/to/private/key/file>

The permissions should display as rw------- or similar, indicating only owner access.

Using keys for database authentication

To connect to a database server to run queries using key-based authentication, particularly for automated batch queries, you need to configure your client application appropriately. This method is preferred for non-interactive processes where entering a password or using SAML is not feasible. Best practices dictate that system batch jobs are run as a role user.

If you are writing your own batch queries or other non-interactive utilities, ensure your client authenticates before any database connection is made. The Deephaven database components typically use the AuthenticationClientManager.getDefault() instance. Authentication can be configured via:

  1. System Property: Setting the AuthenticationClientManager.defaultPrivateKeyFile Java system property. This must specify a private key file (generated as described above) whose public key is known to the authentication server. Authentication will be done automatically. This is the preferred choice for batch queries. Example: -DAuthenticationClientManager.defaultPrivateKeyFile=/path/to/batch_user_private_key.
  2. Programmatic Call: Calling AuthenticationManager.getDefault().challengeResponse(String privateKeyFile) within your Java application, providing the path to a private key file known to the authentication server.
  3. Client Configuration: For some client applications or scripts, you might set specific properties like deephaven.client.privateKeyPath=/path/to/batch_user_private_key and deephaven.client.username=batch_user before the client attempts to connect.

When using password-based authentication for interactive utilities, if you must implement a method to get the password from the user, do not store passwords in a file. If the password is typed in, ensure it is obscured (for example, by using java.io.Console.readPassword). However, key-based authentication is generally more secure for programmatic access.