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/pub-username.base64.txt

# 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 enabled via authentication.server.authorizedkeys.enabled and configured with authentication.server.authorizedkeys.file (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 (deprecated): Deephaven previously supported a dedicated dsakeys.txt file to map usernames to public keys. This file-based store is deprecated and disabled by default. Public keys are now managed in the ACL store (etcd or MySQL). See Deprecated filesystem-based public keystore.

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 in the ACL store using dhconfig acls publickeys import. See Private key login for details.

The private key file must be kept secure on the client machine.

How to create authentication keys

Deephaven uses its own key format. Use the generate-iris-keys utility to generate a Deephaven authentication keypair. The utility generates ECDSA keys using the secp256r1 curve.

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

This generates two files in the current directory:

pub-<keyname>.base64.txt — the public keypair file. Register this on the server.
priv-<keyname>.base64.txt — the private keypair file. Keep this secure on the client machine.

Alternatively, generate a keypair using the Python client:

from deephaven_enterprise.client.auth import AuthClient

(priv, pub) = AuthClient.generate_keypair("user_name")

with open("priv-user_name.base64.txt", "w") as f:
    f.write(priv)

with open("pub-user_name.base64.txt", "w") as f:
    f.write(pub)

After generating the keypair, register the public key on the server:

dhconfig acls publickeys import --file pub-user_name.base64.txt

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/priv-keyname.base64.txt

Verify permissions using:

ls -l /path/to/priv-keyname.base64.txt

The permissions should display as -rw------- or similar, indicating only owner read/write 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 AuthenticationClientManager.getDefault().challengeResponse(String privateKeyFile) within your Java application, providing the path to a private key file known to the authentication server.

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.