--- title: Deephaven public and private key authentication sidebar_label: Public and private keys --- 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`](../configuration/dhconfig/acls.md#publickeys) commands provide the recommended way to manage public keys: ```bash # 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 ``` 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: 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](../configuration/public-and-private-keys.md#authentication-server)) 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:** ```bash ssh-keygen -t ed25519 -f /path/to/your/deephaven_user_key -C "your_username@deephaven" ``` **Example using RSA (4096-bit):** ```bash 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 registered on the server using [`dhconfig acls publickeys import`](#using-dhconfig-recommended), or added to an Authorized Keys file as described under [Alternative methods](#alternative-methods). 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 ` This command restricts read/write access to the file owner. Verify permissions using: `ls -l ` 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. ## Related documentation - [Deephaven public and private key configuration](../configuration/public-and-private-keys.md) - [Hardening technical controls](./hardening-technical-controls.md) - [Authentication keys](../permissions/authentication-keys.md)