> For the complete documentation index, see [llms.txt](https://docs.oceanenterprise.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.oceanenterprise.io/infrastructure/signer-server-installation-and-configuration/key-generation-and-management-in-openbao-secrets-vault.md).

# Key Generation & Management in OpenBao Secrets Vault

The Signer Server uses the OpenBao secrets vault to store the web3 private keys of an entity in a dataspace.  

This section describes how web3 private keys are generated, imported, inspected, and removed within the OpenBao vault included in the Signer Server component.

### OpenBao main components

At deployment time, the OpenBao Docker image builds the [`vault-plugin-secp256k1`](https://github.com/pelipas/vault-plugin-secp256k1) plugin (registered as `secpsign`), which enables two secrets engines:

| **Mount**  | **Type**          | **Purpose**                                                          |
| ---------- | ----------------- | -------------------------------------------------------------------- |
| `ethereum` | `secpsign` plugin | Stores private keys; derives and returns the Ethereum address; signs |
| `secret`   | `kv-v2`           | Stores the wallet-ID → address mapping consumed by the Signer Server |

Three state files live in the `openbao-keys` Docker volume, mounted at `/vault/keys` (and mounted read-only into `signer-server`):

| **Path**                                | **Content**                                                                      |
| --------------------------------------- | -------------------------------------------------------------------------------- |
| `/vault/keys/addresses.json`            | `{"<wallet_id>": "<address>"}` — authoritative wallet-ID map                     |
| `/vault/keys/private_key_registry.json` | `{"<sha256_of_key>": {"id": <int>, "address": "<address>"}}` — idempotency index |
| `/vault/keys/init.json`, `root_token`   | Unseal keys and root token written on first initialisation (mode `600`)          |

> **Note**: The private keys file used for adding or deleting private keys to/from the secrets vault resides in `openbao/secrets/private_keys.`

The registry indexes keys by **SHA-256 hash of the normalised key**, never by the key itself. This is what makes imports idempotent and what allows logs to reference a specific key (`key_hash=…`) without ever printing it.

```mermaid
flowchart LR
    GEN["Key generation<br/>(cast / openssl / MetaMask)"] --> FILE["secrets/private_keys"]
    FILE --> MA["manage-accounts.sh import"]
    MA --> ETH["ethereum/accounts<br/>(secpsign plugin)"]
    ETH -->|returns address| MA
    MA --> KV["secret/wallets/by-id/&lt;id&gt;"]
    MA --> REG["addresses.json<br/>private_key_registry.json"]
    KV --> SS["signer-server"]
    REG --> SS
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.oceanenterprise.io/infrastructure/signer-server-installation-and-configuration/key-generation-and-management-in-openbao-secrets-vault.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.