diff --git a/code_samples/tdf/encrypt_options.mdx b/code_samples/tdf/encrypt_options.mdx index cbbffc39..a017f6d9 100644 --- a/code_samples/tdf/encrypt_options.mdx +++ b/code_samples/tdf/encrypt_options.mdx @@ -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. + @@ -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`. @@ -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. +::: @@ -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. diff --git a/docs/appendix/matrix.mdx b/docs/appendix/matrix.mdx index d4877059..84c5053b 100644 --- a/docs/appendix/matrix.mdx +++ b/docs/appendix/matrix.mdx @@ -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 | | | | | | | **Service APIs**[^105] | Stable | Stable | Stable | | - Authorization[^120] | Stable | Stable | Stable | @@ -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 diff --git a/docs/components/key_access.md b/docs/components/key_access.md index f7124037..9a52cbc0 100644 --- a/docs/components/key_access.md +++ b/docs/components/key_access.md @@ -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 diff --git a/docs/sdks/tdf.mdx b/docs/sdks/tdf.mdx index a0c04ae6..44d970dc 100644 --- a/docs/sdks/tdf.mdx +++ b/docs/sdks/tdf.mdx @@ -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. | @@ -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. |