-
Notifications
You must be signed in to change notification settings - Fork 5
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.
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
ADR: NanoTDF KAS resource locator path and key identifier #900
Comments
We should also support key splitting explicitly somehow |
Are we going to change the "L1L" magic number? |
@patmantru The "L1L" contains the version which will change if the specification is revised. A revision would include a binary format change, or perhaps even a reinterpretation of an existing field. see https://github.com/opentdf/spec/tree/main/schema/nanotdf#3311-magic-number--version |
@dmihalcik-virtru key splitting will not be covered by this ADR nor any ADR in foreseeable future |
@patmantru As a fun aside, L1L also results in a BASE64 encoding that starts with "TDF..." |
- define new `cryptoProvider` config structs to support rotation with different keys - this means the algorithm must be present - I'm using some heuristics to maintain backward compatibility of standard crypto configs, but hsm configs must be updated - Adds `kid` in response to kas_public_key - Adds `kid` in key access objects produced by SDK - Still no support in nanotdf, as we have not agreed on how/where to store the `kid` value in the header. See #900 New Config: ```yaml server: cryptoProvider: type: standard standard: keys: - kid: r1 alg: rsa:2048 private: kas-private.pem cert: kas-cert.pem - kid: r0 alg: rsa:2048 private: kas-private-old.pem cert: kas-cert-old.pem - kid: e1 alg: ec:secp256r1 private: kas-ec-private.pem cert: kas-ec-cert.pem services: kas: enabled: true keyring: - alg: rsa:2048 kid: r1 - alg: rsa:2048 kid: r0 legacy: true - alg: ec:secp256r1 kid: e1 ``` some notes: - `kid` values should be unique, preferably for the lifetime of the kas host domain name - `kid` values should short strings (I'd suggest maxing out at 44 characters) - `private` and `cert` indicate the location of private key and a certificate, if available - For `hsm` keys, these should be label values - For `standard` keys, these should be paths to PEM files relative to the current working directory - I've deprecated the `eccertid` for a new `keyring` parameter which describes how KAS will interpret the key. So we have two sections: `server.cryptoProvider` describes what keys are available, while `service.kas.keyring` describes how KAS uses those keys. - We don't have a 'rotate' script yet. To do this manually, update the init-temp-keys script to use a new name/label and rerun and add the new keys to the list, updating the `certid` fields to point to the new values To come: 1. nanoTDF support
@pflynn-virtru This might be another option. Have you considered leveraging the For example, if we keep the KAS hostname, port, and path in a NanoTDF or ZTDF, an administrator could never really tear down those records without risking breaking existing TDFs. This approach also allows the platform to dictate which KASs are trusted. Example: urn:kas:kas-1.virtru.com:kid:123 We should also consider using this format for ZTDF to address similar issues there. |
Two options exist: I have added issues with URL case. |
Would one of these approaches be better suited for situations where OpenTDF is deployed in a multi-KAS environment or handle situations where maybe IT wants to migrate obscure endpoints from |
One bit of experience I have is with Virtru's Secure Reader product. We offered the ability to tie policy with custom domains (CNAMEs) as the product aged we learned that customers wanted the ability to change those either due to a company rebrand, acquisition, or even an IT policy change that required domains to comply with a universal org policy. By binding emails directly with the company CNAME it meant that the company would have to hold that domain indefinitely or risk breaking access to old emails. I would encourage learning from this experience and make sure we reduce this risk. For instance, managing one domain indefinitely is much less burdensome than N domains (or subdomains) per deployed KAS. |
In this case I think going with a uri or urn approach would be better suited with the core platform holding the necessary information to connect to kas. Imagine if you needed to change the kas endpoint 5 times. I think a user would have to maintain a new cname record every time it's changed. |
This is my main concern. We’re shifting complexity to the infrastructure. For instance, if a port number other than 443 is used and then changed, does that mean those TDFs become inaccessible unless the infrastructure is constantly maintained? This could lead to significant challenges in ensuring continuous access to TDFs that were previously generated. The current solution feels brittle the more we dig into it. |
After the Architecture meeting the following has been decided:
Rough implementation impact:
|
Before I forget want to note this down. KAS is really an interface to the policy keys. There should be no reason I can't load the keys into another kas and decrypt my data as long as my entitlements match the resource attributes. We don't tie a key to a kas in anyway. |
Temporarily disable the decrypt command in tdf-roundtrips test due to a bug reported in issue #900. This change also modifies the paths of the r2 key pair to match the kas-private.pem and kas-cert.pem paths, eliminating the previously separate r2 keys.
@pflynn-virtru this is a really well written ADR and the back and forth discussion in an open forum like this between you, @strantalis and @jrschumacher is amazing. I will pile on and just say I agree with the comments from both Ryan and Sean. We need to be more flexible to infrastructure changes, particularly with something as important as accessing keys. |
This is prep for the incoming changes related to ADR below. Updated the constructor to mask the first byte with 0xF, ensuring only the first four bits are used for indexing the protocol. This prevents potential out-of-bounds errors when retrieving values from the NanoTDFType.Protocol enum. Issue: opentdf/platform#1203 Specification: opentdf/spec#40 ADR: opentdf/platform#900
NanoTDF will now have the KAS KID set in the KAS ResourceLocator Resolves #100 Specification: opentdf/spec#40 ADR: opentdf/platform#900
…#1222) - Adds `identifier` field to Resource Locator - Updates Protocol Enum with `identifier ` size Closes #1203 Issue: #1203 Specification: opentdf/spec#40 ADR: #900 --------- Co-authored-by: sujankota <sreddy@virtru.com> Co-authored-by: David Mihalcik <dmihalcik@virtru.com> Co-authored-by: Tyler Biscoe <biscoe@virtru.com>
NanoTDF KAS resource locator path and key identifier
Context
Problem
The NanoTDF specification requires enhancements to support key identifier and multiple ways to access KAS.
See https://github.com/opentdf/spec/tree/main/schema/nanotdf#3312-kas
Example body with protocol values:
How to access a KAS
/v2/rewrap
or/kas/v2/rewrap
or/rewrap
to URL from step 2 (varies by SDK)Which KAS key
As we introduce multiple KAS keys and perform key rotations, we need a key identifier
kid
used in creating the NanoTDF so a rewrap operation can use the same key.Policy Key Access
This section allows for an ephemeral key other than the Payload key to encrypt the policy.
See https://github.com/opentdf/spec/tree/main/schema/nanotdf#342323-optional-policy-key-access
Goal
kid
kid
or public keykid
on decryptionkid
on encryptionRelated
Included here because a possible version change to NanoTDF specification could influence this decision.
Decision
⚖️ Add or Use Key Identifier section
See #1199
See https://github.com/opentdf/spec/tree/main/schema/nanotdf#342323-optional-policy-key-access
Rationale: Only KAS needs to know the public key or
kid
. It has no impact on how to access KAS.Changes:
⚖️ Add Key Identifier to Policy
See #1197
Rationale: KAS presents multiple keys available to a client. The client determines which key based on the use case policy.
Changes:
kid
field with compute and format specificationExample attribute
urn:opentdf:kas:ec:secp256r1:43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8
urn:ietf:params:oauth:jwk-thumbprint:sha-256:NzbLsXh8uDCcd-6MNwXF4W_7noWXFZAfHkxZsRGC9Xs
⚖️ Add Key Identifier to KAS Resource Locator
See Specification opentdf/spec#40
See Implementation #1222
Rationale: KAS has multiple keys available to a client. The client determines which key based on the use case policy.
Changes:
kid
to a policy with default implementation in KAS and SDK⚖️ Resource Locator format: URN
Rationale: Introducing a URN type that includes both domain and identifier enhances the ability to uniquely and efficiently reference resources.
Changes:
urn:opentdf:kas:<domain>:<identifier>
.virtru.com:01edksqtx9cfzzt1y9sm57h3yq
<identifier>
in ULID 16 bytesurn
⚖️ Resource Locator format: URL query parameter
See #1190
virtru.com/api/kas?kid=435143a1b5fc8bb70a3aa9b10f6673a8
:
Decision
TBD
References
The text was updated successfully, but these errors were encountered: