Skip to content

Multiple holder key management - #799

Open
md4096 wants to merge 11 commits into
a-sit-plus:developfrom
md4096:feature/multiple-holderkeys-1
Open

md4096 wants to merge 11 commits into
a-sit-plus:developfrom
md4096:feature/multiple-holderkeys-1

Conversation

@md4096

@md4096 md4096 commented Nov 12, 2026

Copy link
Copy Markdown
Collaborator

A holder can now bind each credential to its own key instead of one key for all.

  • HolderKeyResolver: finds the key a credential is bound to. HolderAgent and VerifiablePresentationFactory get resolver-based constructors, and presentations are signed with the credential's own key.
  • StoreEntry.holderKey() / isHolderBound(): define holder binding: cnf for SD-JWT VC, deviceKey for mdoc, a did:key in sub for VC-JWT. DCQL matching uses this definition; SD-JWT and mdoc validation share the key extraction. VC-JWT validation keeps its existing sub matching.
  • ProofKeySupplier: proof creators ask for a key for every credential request, including retries, allowing the supplier to allocate a fresh key each time. KeyAttestationInput.keys carries the keys to attest, and ProofCreator.createProof reports the key it used. Cancelling a proof signature ends the credential request instead of trying the next proof creator.
  • expectedHolderKeys: a received credential must be bound to one of its request's proof keys. With a resolver and no proof keys the check is blocked, never "any known key". A single-key holder without proof keys continues to expect its one key.
  • Deprecations: Holder.keyMaterial, CredentialValidationContext.expectedHolderKey, the VerifiablePresentationFactory(keyMaterial, …) constructor, and the keyMaterial constructors of OpenId4VpKtorHolder, DcApiHolder and Iso180137AnnexCHolder. Single-key constructors keep working.

Breaking

  • Constructor and copy signatures change, and new componentN functions are added, on CredentialValidationContext, ReceivedCredential.Decoded, CredentialRequest.Plain and .Encrypted, and KeyAttestationInput. Existing component positions remain unchanged.
  • A VC-JWT whose sub is not a did:key no longer counts as holder-bound in DCQL matching.
  • Presenting a credential whose holder key cannot be resolved now fails. A single VC-JWT presentation also fails if its credentials are bound to different keys or to none.

CHANGELOG.md and ARCHITECTURE.md are updated.


Written by Claude under close supervision.

@md4096 md4096 self-assigned this Nov 12, 2026
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 12, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ❌ Failed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-13T15:36:21.028805Z a74f6b2 Manual request
🔒 Security Review ❌ Failed 2026-11-12T11:45:15.285129Z
We couldn’t complete this review. Comment @codex security review to try again.
9572b15 PR opened
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector

This comment was marked as outdated.

@chatgpt-codex-connector

This comment was marked as outdated.

@md4096
md4096 requested a review from nodh November 12, 2026 11:45
@md4096

md4096 commented Nov 12, 2026

Copy link
Copy Markdown
Collaborator Author

Rebase in progress

@md4096
md4096 force-pushed the feature/multiple-holderkeys-1 branch from 9572b15 to a74f6b2 Compare November 12, 2026 12:07
@asitplus

This comment was marked as outdated.

claude[bot]

This comment was marked as outdated.

@asitplus

This comment was marked as outdated.

@chatgpt-codex-connector

This comment was marked as outdated.

@nodh

nodh commented Nov 13, 2026

Copy link
Copy Markdown
Member

@codex review

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a74f6b28f7

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".


/** The key of the intact credential, `null` if it isn't intact or isn't holder-bound. */
private fun CredentialValidationResult.boundKey(): CryptoPublicKey? = when (val credential = unacceptedCredential) {
is ValidatedCredential.VcJwt -> credential.credential.holderKey()

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P1 Badge Preserve thumbprint-bound VC-JWTs during storage

When a VC-JWT uses the expected holder key's JWK thumbprint in sub, evaluateVcJwt still passes holder binding (and the added validator test explicitly preserves that behavior), but this branch calls holderKey(), which returns a key only for did:key subjects. The prepared object's holderKey is therefore null, so storeAccepted() fails in requireHolder() even for the correct single-key holder; before this commit these accepted credentials were stored, and CHANGELOG.md limits the thumbprint break to DCQL matching. Carry the matched expected key through preparation instead.

AGENTS.md reference: AGENTS.md:L14-L15

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

reads worth fixing ... @md4096?

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

Yes, i will add that

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

Fixed in 19bdab8

@nodh nodh left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Looking great overall, just some detailed questions to build up understanding on my side.

val rawDisclosure = """["$salt", "family_name", "Musterfrau"]"""
.encodeToByteArray().encodeToString(Base64UrlStrict)
// Bound to the holder key, which signs the KB-JWT
val cnf = ConfirmationClaim(jsonWebKey = it.holderKeyMaterial.jsonWebKey)

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Why has this been added here? In general, a presentation without KB-JWT may be fine, when no credential holder key binding is requested.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

The follow-up PR includes the presentation without a KB-JWT

}
}

"SD-JWT VC: a cnf without a key by value is holder-bound, without a holder key" - { fixture ->

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Would love to see a test case for "SD-JWT VC without KB-JWT is not holder-bound"

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

The follow-up PR includes this test case

Comment thread CHANGELOG.md Outdated
key, and one with a resolver blocks the check
- Deprecate `CredentialValidationContext.expectedHolderKey`, use `expectedHolderKeys`
- Add `KeyAttestationInput.keys`, the keys to attest
- BREAKING: New parameters change `copy` and `componentN` of the data classes `CredentialValidationContext`,

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

That's just cluttering the changelog here, please trim it down

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

Fixed with a68195b

* the `credentialSubject` and no key binding, and only a `did:key` lets the key be derived from it. Any other `sub` is
* not a key binding.
*/
internal fun VerifiableCredentialJws.isHolderBound(): Boolean = subject?.startsWith(DID_KEY_PREFIX) == true

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

That's fine for me, but should be noted as a limitation in an existing markdown file (Readme? Architecture?)

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

Added to the ARCHITECTURE.md with a1e7d4b

VerifiablePresentationFactory(keyMaterial = keyMaterial),
class HolderAgent private constructor(
/** `null` for a holder with a [HolderKeyResolver]. */
private val singleKey: KeyMaterial?,

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Do we really need that nullable property, or can we migrate to the HolderKeyResolver to be used exclusively?

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

This can be removed if we choose to introduce a breaking change without a fallback for the deprecated keyMaterial accessor

@nodh nodh Nov 19, 2026 •

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Looks like we're reading keyMaterial only inside HolderAgent.kt, so I'm fine with a breaking change here, with a message in @Deprecated explaining this, maybe even ReplaceWith for a simple case?

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

Discussed offline, deprecation added to HolderAgent constructor.
a8f8006

)
if (validCredentials.any { it.holderKey()?.equalsCryptographically(keyMaterial.publicKey) != true })
throw PresentationException("A credential is not bound to the key of the presentation")
return with(

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

I know that the with construct has been here before, but since we're refactoring this, can we get rid of that?

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

Fixed with ddd5e46

@nodh nodh added this to the 10.0 milestone Nov 16, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants