> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bastion.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Wallet key management

> How Bastion derives wallet private keys on demand from a non-exportable root key in AWS KMS and CloudHSM, and signs inside AWS Nitro Enclaves.

## Overview

Wallet private keys are generated and managed exclusively within the Bastion signer service. These private keys never exit the secure boundary of the signer service.

***

## Key architecture

Bastion uses a hierarchical key derivation model:

| Layer                 | Location                   | Purpose                                       |
| --------------------- | -------------------------- | --------------------------------------------- |
| **Root Key**          | AWS KMS (CloudHSM-backed)  | Master key, non-exportable                    |
| **Enclave-Shard Key** | Secure Enclave (AWS Nitro) | Derived from root, used to derive wallet keys |
| **Wallet Keys**       | Secure Enclave (AWS Nitro) | Derived from per-shard key when needed        |

***

## Private key generation

Wallet private keys are generated using a deterministic secure algorithm:

* The secure root private key is maintained in AWS KMS backed by AWS CloudHSM and is **not exportable**
* Access to the root key is strictly limited to the Bastion signer service operating within the AWS Nitro Enclave boundary
* During boot, the signer service securely communicates with AWS KMS to restore a per-shard private key, stored in encrypted enclave memory
* User wallet private keys are derived from this per-shard private key using per-user metadata

This algorithm enables rapid yet secure generation of wallet private keys, creating them only when necessary.

***

## Private key retrieval

Wallet private keys are generated **on-demand** and never stored in persistent storage:

* Keys are created by the signer service within an AWS Nitro Enclave
* Nitro Enclaves are isolated, highly constrained compute environments that can only communicate via a secure virtual socket
* Enclaves are invisible to the host machine
* Nitro Enclaves provide cryptographic attestations, enabling verification of the software running within the enclave

All signer code is implemented in **Rust**, a programming language known for its safety and security. The code is cryptographically enforced as custom firmware.

***

## Key lifecycle

| Phase          | What Happens                                                             |
| -------------- | ------------------------------------------------------------------------ |
| **Generation** | Wallet key deterministically regenerated on-demand for signing           |
| **Usage**      | Key exists briefly in enclave memory, accessible only within the enclave |
| **Removal**    | Key removed from enclave memory immediately after signing                |

During the brief period that a private key exists in memory, it is only accessible within the Nitro Enclave and hidden from external inspection.

***

## KMS access control

AWS Nitro Enclave cryptographic attestation secures access to KMS keys:

1. Only secure and trusted Bastion signer software is authorized to interact with the HSM-backed root key
2. The encrypted per-shard private key can only be decrypted by secure and trusted Bastion signer software

This is complemented by AWS IAM and KMS key policies that strictly limit available operations, ensuring they can only be initiated from the Bastion signer running inside AWS Nitro Enclaves.

All AWS IAM and KMS key access is securely logged via AWS CloudTrail, with logs maintained in a separate, isolated AWS account.


## Related topics

- [Bastion platform overview](/guides/getting-started/bastion-platform-overview.md)
- [Crypto custody](/guides/concepts/custody.md)
- [Security architecture overview](/guides/security/overview.md)
- [Sandbox access and test API keys](/guides/getting-started/api-access-prerequisites.md)
- [Send crypto on-chain to any wallet address](/guides/quickstarts/send-crypto/on-chain.md)