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

# XKS architecture

> Diagram and explanation of AWS XKS architecture with CryptoHub, including flows and components.

The following diagram illustrates the high-level architecture of an AWS XKS integration with CryptoHub, including connectivity options, certificate requirements, and authentication flows.

```mermaid expandable lines wrap title="Mermaid" theme={null}
flowchart LR
  %% Archbee-compact XKS overview (no parentheses in labels)

  subgraph AWS["AWS Account (Region)"]
    KMS["AWS KMS (XKS)"]
  end

  subgraph Conn["Connectivity"]
    direction TB
    PUB["Public endpoint (FQDN)"]
    PL["AWS PrivateLink"]
  end

  subgraph Cust["Your Environment"]
    PROXY["XKS Proxy (you operate)"]
    HUB["CryptoHub"]:::hub
  end

  %% Main paths
  KMS -->|Public| PUB -->|TLS :443| PROXY
  KMS -->|Private| PL -->|TLS :443| PROXY
  PROXY -->|XKS API - policy and crypto ops| HUB

  %% Security notes for KMS <-> Proxy
  TLS_CERT["Server TLS"]:::note
  MTLS["mTLS (AWS client cert)"]:::optional
  SIGV4["SigV4: dedicated credential"]:::note
  TLS_VER["TLS >= 1.2, AES-GCM"]:::note

  TLS_CERT -.-> KMS
  TLS_CERT -.-> PROXY
  SIGV4 -.-> KMS
  SIGV4 -.-> PROXY
  TLS_VER -.-> KMS
  TLS_VER -.-> PROXY
  MTLS -.-> KMS

  %% Styles
  classDef note fill:#eef6ff,stroke:#2563eb,color:#1e3a8a;
  classDef optional fill:#fff7ed,stroke:#f59e0b,color:#7c2d12;
  classDef hub fill:#fee2e2,stroke:#dc2626,color:#7f1d1d,font-weight:bold;
```

## Component and flow explanation

The preceding diagram shows the full architecture for integrating **AWS KMS External Key Store (XKS)** with Futurex CryptoHub, highlighting both connectivity options and the security requirements for each link.

### AWS KMS (XKS)

AWS Key Management Service (KMS) is operating in *External Key Store* mode, which means cryptographic keys are not stored inside AWS. Instead, KMS requests encryption and decryption services from an external key manager—in this case, CryptoHub—by using an XKS Proxy that you operate.

### Connectivity options

You can connect AWS KMS to your XKS Proxy in the following ways:

* **Public Endpoint**
  * The proxy is reachable over the internet through a publicly resolvable FQDN.
  * A publicly trusted CA from AWS’s approved list must issue the server TLS certificate installed on the proxy.
  * The Common Name (CN) or Subject Alternative Name (SAN) of the certificate must exactly match the hostname you configure in AWS (XksProxyUriEndpoint).
  * A full certificate chain must be presented.
* **AWS PrivateLink**
  * The proxy is exposed as an **AWS VPC endpoint service**.
  * AWS PrivateLink uses a private DNS hostname you define, and your TLS certificate must match that private DNS name.
  * This option avoids exposure to the public internet but requires an AWS networking setup (VPC endpoint service, NLB, target groups, and health checks).

In either case, traffic between KMS and the proxy **must** be encrypted with TLS, and AWS only supports **IPv4 over TCP port 443**.

### Security for the KMS ⇄ Proxy Link

You can use the following methods for the KMS to proxy link:

#### Server TLS

Keep the following considerations in mind:

* A **public CA** from AWS’s trusted list must issue the TLS certificate.
* CN or SAN must match the endpoint (public or PrivateLink DNS name).
* Must present a **complete certificate chain**.
* Protocols: **TLS 1.2 or higher**.
* Cipher suites must be strong, such as the following options:
  * **TLS 1.3**: TLS\_AES\_256\_GCM\_SHA384, TLS\_CHACHA20\_POLY1305\_SHA256
  * **TLS 1.2**: TLS\_ECDHE\_RSA\_WITH\_AES\_256\_GCM\_SHA384, TLS\_ECDHE\_ECDSA\_WITH\_AES\_256\_GCM\_SHA384

#### Mutual TLS (Optional)

Keep the following considerations in mind:

* If enabled, AWS KMS presents a client TLS certificate.
* The CN for the client certificate is `cks.kms.<region>.amazonaws.com` (for example, `cks.kms.us-east-1.amazonaws.com`).
* The certificate chain terminates at an **Amazon Trust Services** CA.
* If you enable mTLS, you must configure your proxy to accept only these AWS-issued client certificates.

#### SigV4 Authentication

Keep the following considerations in mind:

* AWS Signature Version 4 signs every request from AWS KMS to your proxy.
* You must configure KMS with an **AccessKeyId** and **SecretAccessKey** pair that your proxy validates.
* This credential must be **dedicated to the XKS proxy**—do not reuse an IAM access key or any credential used for other purposes.
* Plan for credential rotation: update the proxy first, then update the external key store in KMS with the new pair.

#### TLS Requirements

Keep the following considerations in mind:

* Minimum protocol: **TLS 1.2**
* Only approved cipher suites are allowed (see the preceding server and mutual TLS sections).
* Only IPv4 is supported, and the port must be **443**.

### XKS Proxy (You Operate)

The proxy is a web service that:

* Implements the **XKS Proxy API**.
* Validates AWS SigV4 requests and, if enabled, the AWS client TLS certificate.
* Translates AWS KMS API calls into requests to your external key manager.
* Returns results to KMS, never exposing the raw key material.

Performance expectations:

* AWS recommends the proxy handle **\~1,800 requests/sec**.
* Target a maximum **250ms latency** for proxy responses, as delays directly affect AWS service encryption/decryption performance.

### CryptoHub

CryptoHub offers the following advantages

* Acts as the *External Key Manager* behind the proxy.
* Stores and protects your encryption keys inside a certified HSM.
* Enforces your organization’s key access and usage policies.
* Responds to the proxy requests for operations like **GenerateDataKey**, **Encrypt**, and **Decrypt**.

### Operational Notes

* **Availability**: If your proxy or CryptoHub is unavailable, AWS KMS cannot perform new encrypt/decrypt operations with external keys. Only AWS services that have cached a data key can continue until the cache expires.
* **Monitoring**: Use AWS CloudWatch metrics like XksProxyErrors to detect proxy failures.
* **Quotas**: KMS API request limits apply to XKS. Plan capacity accordingly.
* **Testing**: Before creating the external key store in AWS, validate your proxy with AWS’s **XKS Proxy Test Client** to ensure TLS, mTLS, SigV4, and API compatibility.