ADR: add KAS grants to Namespaces (not just Attribute Definition & Values)

[jakedoublev]

Background

The OpenTDF Platform now supports a concept of key splits through platform policy "Grants" or assignments of specific KeyAccessServers (KASs) to Attribute Definitions and Attribute Values. This is useful to secure data of a specific attribute or attribute value (whichever level of specificity) with a narrowly-used key pair.

However, there are use cases where groups sharing a set of policy (perhaps imported from the same 3rd party source) may also desire to share a secret key to encrypt data of that policy. For this use case, organizations would utilize the same namespace in policy for attributes on their TDF'd data and need to ensure the TDFs are interoperable (and ultimately the ciphertext is decipherable) across the different platform instances in the strict sense that with no grants to definitions or values, attributes across platforms under the same namespace would utilize the same key, even if the platform instance itself or federated KASs are utilizing separate and unique default keys.

Key Grants Logic

The expected behavior of OpenTDF platform key splits follows a pattern of greatest to least specificity.

Namespace KAS Grant (proposed)	Attr Definition KAS Grant	Attr Value KAS Grant	Granted Data Encryption Key Utilized
yes	no	no	namespace
yes	yes	no	attr definition
no	yes	no	attr definition
yes	yes	yes	value
no	yes	yes	value
no	no	yes	value
no	no	no	default KAS/platform key

Out of scope

1. solutions for the mechanism of sharing a secret key
2. security tradeoffs of sharing a key
3. federating access DecisionRequests across idPs running alongside the federated platforms

Options

Chosen: Option 2: allow grants on namespaces

Option 1: the current use-case enablement state - the different platforms would use the same shared default key

This could be accomplished today via one of the following:

1. define a grant to every definition on shared policy namespaces with the key shared by the varied platforms' granted KASs
2. run a platform instance with only the shared policy namespace to avoid using the shared key for un-shared namespaces
3. define a grant to every definition for un-shared namespaces to avoid using the shared key for un-shared policy

🟩 : Good, because it accomplishes the use-case need 🟩 : Good, because it requires no code changes and is unblocked today 🟥 : Bad, because HIGH risk for misconfiguration leading to a data leak via encryption of un-shared policy with a shared key 🟥 : Bad, because it is known good practice that key use should always be narrow and specific to avoid mistaken data leaks

Option 2: allow grants on namespaces

We would add RPCs and db functionality in Policy to assign KAS Grants to Namespaces like we already have for Definitions and Values.

🟩 : Good, because it accomplishes the use-case need 🟩 : Good, because LOW risk of data leak due to misconfiguration comparatively 🟩 : Good, because it's easier to understand (devs and admins) with a clear specificity matrix 🟩 : Good, because the work ahead is clear due to the existing Definitions and Values Grants/Split functionality 🟥 : Bad, because it requires new code changes

[jrschumacher]

@jakedoublev if namespaces have KAS grants then I would propose that there is no default platform key, but every namespace MUST be created with a KAS

[jakedoublev]

@jakedoublev if namespaces have KAS grants then I would propose that there is no default platform key, but every namespace MUST be created with a KAS

I think that conflicts with some of https://github.com/opentdf/platform/issues/1221 but this work would unblock it as a path forward. cc @strantalis

[jrschumacher]

Yes, but if you share policy (i.e. namespace) without a specified KAS then the policy is meaningless. We need a common understanding of the KAS for sharing to take place.

[strantalis]

I think the other benefit for adding a kas to a namespace is now a pep developer doesn't need to worry about which endpoint they should put for a default kas when creating a ztdf. If they get no kas info back on the attribute definition or value the namespace is used.

[jakedoublev]

TBD: KASs can grant across namespaces to multiple, but namespaces must have a KAS on create?

[jrschumacher]

@jakedoublev I spoke with Arch about this, and it was proposed that the platform defines a default namespace which MUST have a KAS grant associated to it.

When considering policy that does not have a namespace grant, it was proposed that it would fall back to the default namespace's KAS.

[jakedoublev]

Discussion dump from Arch Office Hours (ADR to follow)

How to avoid PEP developers needing to think about defaults (namespaces/KASes). SDK/PEP just "encrypt" without extra work.

Default namespace - config or in policy db? if config, creates the default namespace from the config?

sdk error case? No KAS grant on an attribute value, def, or ns. Concerns:

• I encrypt with an attribute with no grants, now I end up with an unknown/unexpected KAS
• if defaulting a KAS and a namespace grant is later added, how to detect the fallback case was utilized
• some TDFs are created and not encrypted

No attribute scenario: key to encrypt must be known

Maybe: A Default(?) Namespace MUST HAVE a KAS grant. A Platform MUST HAVE a default namespace (and therefore transitively a default key). SDK MUST ERROR if an attribute is found to have no grants to values, definition, or namespace. SDK MUST USE default namespace's KAS grant if no attributes on TDF.

[jakedoublev]

Default KAS/Namespace discussion to continue in #1221, but this is being closed as Decided: Option 2: allow grants on namespaces