ADR: Enhancement to the KeyAccessServer Table

[jrschumacher]

Enhance Key Access Server Table

Context and Problem Statement

Currently, the Key Access Server (KAS) stores a jsonb representation of the public_key. This design presents a limitation, as it implies that a Key Access Server can have only a single public key associated with it. However, this is not the case.

In our proto definitions, we define the PublicKey field within the KeyAccessServer proto message:

platform/service/policy/objects.proto

Line 269 in 069f939

PublicKey public_key = 3;

The PublicKey message can take on one of the following forms:

platform/service/policy/objects.proto

Lines 302 to 318 in 069f939

	message PublicKey {
	// Deprecated
	reserved "local";
	reserved 2;
	oneof public_key {
	// kas public key url - optional since can also be retrieved via public key
	string remote = 1 [(buf.validate.field).cel = {
	id: "uri_format"
	message: "URI must be a valid URL (e.g., 'https://demo.com/') followed by additional segments. Each segment must start and end with an alphanumeric character, can contain hyphens, alphanumeric characters, and slashes."
	expression: "this.matches('^https://[a-zA-Z0-9]([a-zA-Z0-9\\\\-]{0,61}[a-zA-Z0-9])?(\\\\.[a-zA-Z0-9]([a-zA-Z0-9\\\\-]{0,61}[a-zA-Z0-9])?)*(/.*)?$')"
	}];
	// public key with additional information. Current preferred version
	KasPublicKeySet cached = 3;
	}
	}

This allows for either storing a reference to a remote public key or defining a public key via a KasPublicKeySet, which is essentially a repeated list of KasPublicKey entries:

platform/service/policy/objects.proto

Lines 284 to 295 in 069f939

	message KasPublicKey {
	// x509 ASN.1 content in PEM envelope, usually
	string pem = 1;
	// A unique string identifier for this key
	string kid = 2;
	// A known algorithm type with any additional parameters encoded.
	// To start, these may be `rsa:2048` for encrypting ZTDF files and
	// `ec:secp256r1` for nanoTDF, but more formats may be added as needed.
	KasPublicKeyAlgEnum alg = 3;
	}

Potential Issues:

1. Key Rotation Confusion: As an admin, I could list multiple RSA keys, including old rotated keys, which might create confusion about which key is active.
2. Lack of Key Selection Mechanism: There is currently no way for our SDK to identify which key should be used as the correct or active key.

Additionally, there is a mismatch between how we assign the KAS to a namespace, attribute, or attribute value. This assignment would work if the KAS were intended to operate with only a single key at a time. However, this does not align with how KAS was originally designed.

Proposed Solution:

Instead of associating a KAS directly with a namespace, attribute, or attribute value, we should use Grants to map a specific Key to the policy resources. This would better reflect the original design intent and allow for more flexible future key management.

Decision Drivers

• Support key rotations
• Ensure strict values
• Allow Key to namespace, attribute, or value mapping

Considered Options

• Store multiple keys within the public_key jsonb typed column
• Create an auxiliary table to store the keys with a many:1 relationship with the KeyAccessServer table

Decision Outcome

Chosen option: "{title of option}"

Store multiple keys within the public_key jsonb typed column

• 🟢 Existing table structure and no migration needed
• 🔴 With JSONB the data does not have a schema to conform to and data structure migrations are hard
• 🔴 No indication from a high-level which key is primary without decoding the JSONB
• 🔴 Row needs to be updated "frequently" to capture key rotations and identify the current key
• 🔴 After many key rotations the resulting data is quite large and filtering needs to be added to the service code

Create an auxiliary table to store the keys

erDiagram

    %% KeyAccessServer ||--|| PublicKey: "has current key"
    PublicKey }|--|| KeyAccessServer: "belongs to"

    XPublicKeyMap }|--|| PublicKey: "has many"
	X ||--|| XPublicKeyMap: "has one"

    X {
        uuid         id                      PK
    }

    XPublicKeyMap {
        uuid  X_id FK
        uuid  key_access_server_id FK
    }

	%% moving public_key out
    KeyAccessServer {
        uuid       id                PK
	text       name
        text       uri               UK
        jsonb      metadata
	date	created_on
	date	updated_on
    }

    

    PublicKey {
        uuid        id                      PK 
        boolean     is_active         
        boolean     was_mapped          
        uuid        key_access_server_id    FK
        varchar(36) key_id
        varchar(50) alg                     "algorithm"
        constraint  unique_key              UK  "enforces unique key_id and algorithm per KAS (key_access_server_id, key_id, alg)"
        constraint  unique_active_key       UK  "enforce only one active key per KAS per algorithm"
        text        public_key
        jsonb       metadata
    }

Loading

Updated from #1485 (comment)

• 🟢 Schema enforced solution to multiple keys
• 🟢 Ensure future migrations are simpler (not-NoSQL)
• 🟡 Requires an auto migration to move public keys
• 🔴 If public key json has many keys, a manual migration is required

References

[jakedoublev]

@jrschumacher is this statement accurate given your proposed schema?

"During a key rotation, a new key (row) is added to the KeyAccessServerKey table and the current_key (on one or multiple) KAS is updated to that new key. The old keys will persist within policy (un-utilized as non-current) and are not deleted upon rotation."

[jrschumacher]

That is my assumption. If we don't need to persist the keys then we really don't need a separate table.

It's also worth discussing how this would work for KASes managed by the platform and KASes managed remotely.

[strantalis]

@jrschumacher How will this work with RSA and ECC as a KAS might have P256, P384, etc..... If a KAS can only have 1 current key at a time.

Also what format are we expecting to be stored in the public_key row? It would be nice if we took this time to standardize that format or build it in a such a way to support JWK, ANS.1/DER or PEM.

[strantalis]

@jrschumacher I modified the ERD a little to add a composite unique key on the KeyAccessServerKeys table of UNIQUE(key_access_server_id, algorithm) and moved the relationship so Grants now has a many to one relationship to Keys

This will restrict a KAS to 1 key per algorithm going forward. So an admin can't define two RSA:4096 keys to the same KAS. It also allows the flexibility of letting the KAS manage multiple keys like ML-KEM, P-256, RSA, etc...

erDiagram

    %% KeyAccessServer ||--|| KeyAccessServerKey: "has current key"
    KeyAccessServerKey }|--|| KeyAccessServer: "belongs to"

    XKeyAccessGrant }|--|| KeyAccessServerKey: "has many"
	X ||--|| XKeyAccessGrant: "has one"

    X {
        uuid         id                      PK
    }

    XKeyAccessGrant {
        uuid  X_id FK
        uuid  key_access_server_id FK
    }

	%% moving public_key out
    KeyAccessServer {
        uuid       id                PK
		text       name
        text       uri               UK
        %% uuid       current_key_id    FK
        jsonb      metadata
		created_on date
		updated_on date
    }

    

    KeyAccessServerKey {
        uuid       id
        uuid       key_access_server_id  FK
        uuid       key_id
        vchar      algorithm  
        jsonb      public_key "ASN.1, PEM, JWK"
        jsonb      metadata
		date       created_on
		date       updated_on
        compIdx    comp_key UK "key_access_server_id + algorithm"
    }

Loading

[jrschumacher]

Looks great. I'm going to copy and update the main description.

[jakedoublev]

So today KAS Grants relate registered Key Access Servers to Attributes (namespaces, definitions, values). It looks like this diagram would relate grants from keys to attributes. Is this an accurate change, or should the diagram point a KAS -> 1+ keys, and a KAS -> 1+ grants and 1 grant -> 1 value?

[strantalis]

So today KAS Grants relate registered Key Access Servers to Attributes (namespaces, definitions, values). It looks like this diagram would relate grants from keys to attributes. Is this an accurate change, or should the diagram point a KAS -> 1+ keys, and a KAS -> 1+ grants and 1 grant -> 1 value?

I did flip it around because keys are what should be associated with a namespace, attribute, or value. A KAS can have multiple keys, with a constraint of 1 key per algorithm.

In theory, an admin could assign a set of keys belonging to one KAS to an attribute value, where you’d get an OR split between RSA, and ECC, for example.

Let me know if this makes sense.

[jrschumacher]

This ADR is complete and the work was captured in #1836