Skip to content

feat(docs): document hybrid post-quantum key wrapping support #343

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
marythought wants to merge 2 commits into
base: main
Choose a base branch
from
Open

feat(docs): document hybrid post-quantum key wrapping support #343

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
366c2a1
feat(docs): document hybrid post-quantum key wrapping support
marythought Jun 17, 2026
e3bf978
Merge branch 'main' into mary/DSPX-3309-hybrid-pqc-docs
marythought Jun 22, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 9 additions & 3 deletions code_samples/tdf/encrypt_options.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -567,6 +567,8 @@ When a TDF is created, the SDK generates a random symmetric Data Encryption Key

The default is `rsa:2048` — RSA with a 2048-bit key. EC (elliptic curve) algorithms such as `ec:secp256r1` offer equivalent security with smaller key material stored in the TDF manifest and faster wrap/unwrap operations.

Hybrid post-quantum algorithms combine a classical algorithm with a post-quantum KEM to protect against harvest-now-decrypt-later attacks. These are available in the Go and Java SDKs when the KAS has hybrid keys registered.

<Tabs>
<TabItem value="go" label="Go">

Expand All @@ -582,7 +584,7 @@ manifest, err := client.CreateTDF(buf, str,
)
```

Valid values: `ocrypto.RSA2048Key`, `ocrypto.EC256Key`, `ocrypto.EC384Key`, `ocrypto.EC521Key`.
Valid values: `ocrypto.RSA2048Key`, `ocrypto.EC256Key`, `ocrypto.EC384Key`, `ocrypto.EC521Key`, `ocrypto.HybridXWingKey`, `ocrypto.HybridSecp256r1MLKEM768Key`, `ocrypto.HybridSecp384r1MLKEM1024Key`.

</TabItem>
<TabItem value="java" label="Java">
Expand All @@ -597,7 +599,11 @@ Config.TDFConfig config = Config.newTDFConfig(
sdk.createTDF(inputStream, outputStream, config);
```

Valid values: `KeyType.RSA2048Key`, `KeyType.EC256Key`, `KeyType.EC384Key`, `KeyType.EC521Key`.
Valid values: `KeyType.RSA2048Key`, `KeyType.EC256Key`, `KeyType.EC384Key`, `KeyType.EC521Key`, `KeyType.HybridXWingKey`, `KeyType.HybridSecp256r1MLKEM768Key`, `KeyType.HybridSecp384r1MLKEM1024Key`.

:::note Hybrid PQC dependency
Hybrid key types require the optional `sdk-pqc-bc` module on the classpath. Add it as a runtime dependency — the default `non-fips` Maven profile includes it automatically via the `cmdline` module. See [opentdf/java-sdk#368](https://github.com/opentdf/java-sdk/pull/368) for details.
:::

</TabItem>
<TabItem value="js" label="JavaScript">
Expand All @@ -610,7 +616,7 @@ const tdf = await client.createTDF({
});
```

Valid values: `'rsa:2048'`, `'rsa:4096'`, `'ec:secp256r1'`, `'ec:secp384r1'`, `'ec:secp521r1'`.
Valid values: `'rsa:2048'`, `'rsa:4096'`, `'ec:secp256r1'`, `'ec:secp384r1'`, `'ec:secp521r1'`. Hybrid PQC algorithms are not yet supported in the JavaScript SDK.

</TabItem>
</Tabs>
Expand Down
2 changes: 2 additions & 0 deletions docs/appendix/matrix.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -61,6 +61,7 @@ Feature matrix for the different SDK versions.
| - ABAC[^112] | Stable | Stable | Stable |
| - Key Mapping[^140] | Stable | Stable | Stable |
| - Obligations[^150] | Stable | Planned | Stable |
| - Hybrid PQC[^160] | Stable | Unstable | Planned |

@gemini-code-assist gemini-code-assist Bot Jun 17, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The column separator | for the new Hybrid PQC row is misaligned by one character compared to the other rows in the table. Adding an extra space after [^160] will align the table columns perfectly for better readability in the raw markdown file.

| - Hybrid PQC[^160]         | Stable   | Unstable | Planned    |

| | | | |
| **Service APIs**[^105] | Stable | Stable | Stable |
| - Authorization[^120] | Stable | Stable | Stable |
Expand All @@ -78,6 +79,7 @@ Feature matrix for the different SDK versions.
[^130]: APIs for managing policy attributes [proto](https://github.com/opentdf/platform/blob/main/service/policy/attributes/attributes.proto).
[^140]: Key Mapping associates KAS keys with policy resources (namespaces, attribute definitions, values).
[^150]: Obligations are PDP-to-PEP directives that accompany access decisions (e.g. watermarking, audit logging).
[^160]: Hybrid post-quantum key wrapping (X-Wing, ECDH+ML-KEM) protects TDFs against harvest-now-decrypt-later attacks. Go support is built into the platform SDK; Java support requires the optional `sdk-pqc-bc` module.

## FAQ

Expand Down
2 changes: 1 addition & 1 deletion docs/components/key_access.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ The Key Access Server (KAS) manages the lifecycle of cryptographic keys and prov

KAS offers the following RPC methods:

- `PublicKey` - Retrieves a public key from KAS. It defaults to `rsa:2048` and uses the currently active default key. The key is returned in PEM format by default.
- `PublicKey` - Retrieves a public key from KAS. It defaults to `rsa:2048` and uses the currently active default key. The key is returned in PEM format by default. Supported algorithm families include RSA (`rsa:2048`, `rsa:4096`), EC (`ec:secp256r1`, `ec:secp384r1`, `ec:secp521r1`), and hybrid post-quantum (`hpqt:xwing`, `hpqt:secp256r1-mlkem768`, `hpqt:secp384r1-mlkem1024`).

```protobuf reference
https://github.com/opentdf/platform/blob/7dea6407322b5e625ee2810dfcf407c010d9996f/service/kas/kas.proto#L69-L75
Expand Down
4 changes: 2 additions & 2 deletions docs/sdks/tdf.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1347,7 +1347,7 @@ Java's `CreateTDF` returns a [`Manifest`](#manifest-object) directly. JavaScript
| Field | Go | Java | Required | Description |
|-------|-----|------|----------|-------------|
| URL | `URL string` | `String URL` | Required | The KAS endpoint URL. |
| Algorithm | `Algorithm string` | `String Algorithm` | Optional | Wrapping key algorithm (e.g. `"ec:secp256r1"`). Defaults to `"rsa:2048"` if empty. |
| Algorithm | `Algorithm string` | `String Algorithm` | Optional | Wrapping key algorithm (e.g. `"ec:secp256r1"`, `"hpqt:xwing"`). Defaults to `"rsa:2048"` if empty. See [Wrapping Key Algorithm](#wrapping-key-algorithm) for all supported values. |
| KID | `KID string` | `String KID` | Optional | Key identifier on the KAS, used when the KAS hosts multiple keys. |
| PublicKey | `PublicKey string` | `String PublicKey` | Optional | PEM-encoded public key. If empty, the SDK fetches it from the KAS. |
| Default | `Default bool` | — | Optional | If `true`, this KAS is used as the default for encrypt calls when no KAS is explicitly specified. |
Expand Down Expand Up @@ -1492,7 +1492,7 @@ The `Manifest` type is returned by [`CreateTDF`](#createtdf) and accessible via
| Field | Type | Description |
|-------|------|-------------|
| `KasURL` | `string` | URL of the KAS holding the key grant. |
| `KeyType` | `string` | Key access type (`"wrapped"` or `"remote"`). |
| `KeyType` | `string` | Key access type: `"wrapped"` (RSA), `"ec-wrapped"` (EC), `"hybrid-wrapped"` (hybrid PQC), or `"remote"`. |
| `SplitID` | `string` | Key split identifier. Entries sharing the same ID share a key segment; different IDs represent independent splits. |
| `KID` | `string` | Key identifier on the KAS, if set. |

Expand Down
Loading