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. The primary method for managing public keys is through the dhconfig tool.

Using dhconfig (recommended)

The dhconfig acls publickeys commands provide the recommended way to manage public keys:

# Import a public key for a user
dhconfig acls publickeys import --file /path/to/user_public_key.pub

# List registered public keys
dhconfig acls publickeys list
dhconfig acls publickeys list --name username --include-hash

# Delete a public key by hash
dhconfig acls publickeys delete --hash <hash>

This method stores keys in the ACL backing store (etcd or MySQL) and is the preferred approach for managing user authentication keys in modern Deephaven deployments.

Alternative methods

For legacy configurations or specific use cases, Deephaven also supports file-based key registration:

Authorized Keys File: A file-based mechanism configurable via the authentication.psk.authorizedKeysFiles property (see Authentication server configuration). This file associates usernames with their Deephaven-format public keys. This method is common for service accounts and automated tasks.
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 generate key pairs using the Deephaven generate-iris-keys utility. 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

Generate a Deephaven-format key pair using the generate-iris-keys utility:

/usr/illumon/latest/bin/generate-iris-keys username

This creates two files in the current directory:

pub-username.base64.txt — Public key (register with server)
priv-username.base64.txt — Private key (keep secure, give to user)

The utility generates ECDSA keys using the secp256r1 curve.

The public key must be registered on the server using dhconfig acls publickeys import. The private key file should be kept secure and used by your client application.

Note

Deephaven uses its own key format. Standard SSH keys (e.g., from ssh-keygen) are not supported.

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:

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