CBOMProfiles /Use Cases ← Working group site
CHANGE PLANNING · WORKED USE CASE

PQC migration: from use case to profile

One use case is developed here, from the decision a consumer is trying to make through to two profile definitions. Both profiles are applied throughout to one real product: Keycloak 26.7.3, an open-source identity provider. The work follows the twelve steps set out in Method. It is the reference example for how the other use cases are worked up.

The decision being supported

An operator or enterprise architect is evaluating a product it did not build and cannot inspect. It must decide how and when that product can move to post-quantum cryptography. An inventory says which algorithms are in use. The migration decision also depends on questions about integration, enforcement and planning, asked of every exposed interface:

An inventory of algorithms cannot answer any of these questions. Knowing which algorithms an interface uses today leaves all of them unanswered. The questions concern what the interface is capable of, how that capability is enabled, and what enabling it costs in interoperability. A migration profile therefore has to require the facts those answers rest on.

For Keycloak the operator is typically an enterprise running it as the single sign-on service for its applications. Every relying party trusts the tokens Keycloak signs. Keycloak's migration therefore sets the timetable for many other systems as well as its own.

The black-box constraint

The defining constraint is that the consumer cannot see inside the product, and the vendor will not expose its internals. Everything the profile asks for therefore has to be declarable at the boundary: observable at an interface, or stated by the vendor as a property of the product it ships. Anything requiring disclosure of source, design or internal architecture is out of scope, and would not be supplied in any case.

the profile describes the boundary, not the box Keycloak 26.7.3 container image internals not disclosed and not required TLS, main listener (tls-https) OIDC token issuance (svc-oidc) SAML assertions (svc-saml) plain HTTP, no protection (svc-http) Admin API and realm keys (mgmt-admin) TLS, health and metrics (tls-mgmt) TLS to the database (int-db) TLS to the directory (int-ldap) TLS to identity providers (int-broker) token verification (svc-broker-tokens) TLS to the mail server (int-smtp) cluster transport int-cache realm keys, unwrapped sto-realm-keys service management interconnect peer storage no cryptography
The profile asks for information one interface at a time. An operator of Keycloak plans against the thirteen interfaces the product presents, because that is all it can verify and all the supplier will state. Each interface declares what it can negotiate, how that is enabled, and what it costs to change.

The profile is also built around interfaces rather than around the product as a whole. A single answer at product level, such as "this product supports ML-KEM", does not tell the operator what to do. A product may support a post-quantum key exchange on its service interface and not on its management interface, and the operator has to migrate both. Migration is planned and executed one interface at a time.

The worked product: Keycloak 26.7.3

Keycloak is a useful subject because its most important cryptography is not TLS. It is the signature on every token it issues, which every relying party verifies. That signature migrates on a different timetable from the TLS underneath it, and depends on a different standard. A migration profile must be able to tell the token signature and the TLS apart. A profile that could not would fail on products like this one.

Three more properties make it instructive. Its TLS key exchange comes from the Java runtime rather than from Keycloak, so what blocks post-quantum key exchange lies with the runtime's cryptographic provider, not with Keycloak. It generates the key for its own cluster transport, so the product, not the operator, fixes that key's type. And it stores its realm keys in its database without wrapping (encrypting) them, so the key storage has to be treated as an interface too.

The subject is the container image, quay.io/keycloak/keycloak:26.7.3, at its defaults. The image fixes the Java runtime, and with it the TLS capability. The ZIP distribution runs on whatever runtime the operator installs, so its TLS capability is a fact about a deployment and belongs in a separate document.

application layer carried by transport OIDC token issuance · svc-oidc SAML assertions · svc-saml Admin API · mgmt-admin HTTPS port 8443 TLS 1.2 / 1.3 tls-https Health and metrics HTTPS · port 9000 TLS · tls-mgmt Brokered token verification HTTPS · outbound TLS · int-broker Plain HTTP · port 8080 · svc-http no transport protection Solid boxes are interfaces. Dashed grey boxes are declared only to show what carries what. JDBC, LDAP, SMTP and JGroups ride their own TLS interfaces in the same way.
An interface is a logical cryptographic boundary, not a port. Signed tokens and the TLS that carries them are two interfaces, because they migrate on different timetables. A service counts as an interface when it applies cryptography of its own or has no transport protection. A service that only rides on TLS does not count.

This gives thirteen interfaces. The seven TLS interfaces all use the Java runtime's cryptographic providers. The four application-layer interfaces are implemented by Keycloak itself.

InterfaceTypeEndpoint roleProtocolWhat it protects
tls-httpsserviceserverTLS 1.2, 1.3The main listener, carrying OIDC, SAML and the Admin API. Certificate supplied by the operator
svc-oidcserviceserverOIDC 1.0ID and access tokens, signed RS256 with the realm key. Encryption off by default
svc-samlserviceserverSAML 2.0Assertions, signed RSA-SHA256 with the realm key
svc-httpserviceserverHTTPNothing. Off by default in production mode. Often used behind a TLS-terminating proxy
mgmt-adminmanagementserverAdmin RESTAdministration by bearer token. Also the surface that generates and imports realm keys
tls-mgmtmanagementserverTLS 1.2, 1.3Health and metrics on port 9000. Inherits the main listener's TLS settings by default
int-db, int-ldap, int-broker, int-smtpinterconnectclientTLS 1.2, 1.3Outbound connections to the database, the directory, external identity providers and the mail server
svc-broker-tokensinterconnectclientOIDC 1.0Verification of tokens issued by external identity providers
int-cachepeerpeerTLS 1.3, mutualCluster transport. RSA-2048 certificate generated by Keycloak, stored in the database, rotated every 30 days
sto-realm-keysstorage——Realm keys and the cluster key, held in the database without wrapping

From questions to attributes

Each planning question implies particular facts. Working from the question to the attribute keeps a profile focused on its purpose. Working from the fields a format happens to offer does not. The second column names the rule that requires each attribute. The third column gives the depth. "Inherited" marks a rule of the interface disclosure baseline. "Baseline" marks a rule of the migration profile, and "Extended" a rule of its extended depth. The column also gives the Keycloak case that shows why the fact matters.

What the consumer needs to knowAttribute that supplies itDepth, and the Keycloak case
1 · Cryptographic surface and boundary
Which interface are we talking about, and what role does it play?interfaceType (interface-disclosure#I7)Inherited. The token interface and its TLS carrier are separate entries
Who controls cipher-suite negotiation at this interface?endpointRoles (interface-disclosure#I6)Inherited. A server controls what it offers, and a client follows. Keycloak is a server on all inbound interfaces, a client on all outbound ones, and a peer on the cluster transport
What protocol, and which versions can it speak?protocol (interface-disclosure#I1), protocolVersionsSupported (pqc-migration#I1)Baseline. The cluster transport speaks TLS 1.3 only
Where is data stored at rest, and is that declared?storage interfaces, or a stated absence (pqc-migration-extended#P1)Extended. The key store in the database
How much should we trust this record?lifecycleStage (interface-disclosure#I8)Inherited. One stage for the whole record: implemented, the image as shipped. Where Keycloak does not fix a value, such as the server certificate, the record says deployment-defined and points to the guide where the operator sets it
2 · Current algorithms and quantum-safe capability
What does the interface use now?keyExchange, authentication (interface-disclosure#I3, #I5)Inherited. X25519 on TLS, RS256 on tokens, and none for token encryption
What could it use?keyExchangeSupported, authenticationSupported (pqc-migration#I2, #I3)Baseline. The JDK 21 groups on TLS. The JOSE algorithms on tokens, none of them post-quantum
Are stored keys exposed at rest as well as traffic?keyWrapping (interface-disclosure#I10), keyWrappingSupported (pqc-migration#I12)keyWrapping is inherited from the interface disclosure baseline (new in its v0.8). keyWrappingSupported is new in pqc-migration v0.7. Realm keys are stored unwrapped
3 · Enablement route and deployment cost
How do we switch it on, and from which product version?enablementMethod, minimumProductVersion (pqc-migration#I4, #I5)Baseline. not-available on every Keycloak interface today
Is this a software change or a hardware one, and which component supplies it?providerLocation (pqc-migration#I6), implementationPurl (interface-disclosure#I9)Baseline. Software throughout. The provider is the JDK or Keycloak itself
4 · Operator enforcement
Can the operator require post-quantum algorithms and refuse a classical fallback?negotiationControl (pqc-migration#I8, SHOULD)Baseline. On TLS, the JVM property jdk.tls.namedGroups sets the groups. On tokens, the signature algorithm is set per realm and per client
5 · Integration friction
What is likely to break when the capability is enabled?integrationConstraints (pqc-migration#I9, SHOULD)Baseline. ML-DSA-signed tokens exceed the 4 KB browser cookie limit
6 · Blockers and roadmap
If it cannot do this yet, what is stopping it, and who can change that?capabilityStatus, blockedBy, roadmapRef (pqc-migration#G1.1 to #G1.3, one entry per purpose)Baseline. Four different blockers across thirteen interfaces
7 · Module validation and compliance
Can the validated module we are obliged to use do it?moduleValidationScheme, moduleValidationRef (pqc-migration#I10, #I11), validatedModeAvailability (pqc-migration#G1.4)Baseline, new in v0.7. Keycloak's validated mode is an opt-in Bouncy Castle FIPS module
Is the overall product certified under a formal security scheme?productCertificationScheme (pqc-migration-extended#P2)Extended. Common Criteria or EUCC evaluated configuration
8 · Key management and ecosystem dependencies
Can the product create, import and hold the new key types?keyManagementFunction, keyOperations, keyTypesSupported, keyTypes, keyStoreLocation (pqc-migration-extended#I1 to #I4, #I7)Extended. The Admin API cannot generate an ML-DSA key
Which surface manages this interface's key?keyStoreRef (pqc-migration-extended#I8)Extended. Tokens: the Admin API. TLS: files, out of band. Cluster: the product itself
What else in the ecosystem has to move first?externalDependencies (pqc-migration-extended#I9)Extended. The certificate authority, the directory, external identity providers

Two profiles, two depths

Keywords follow BCP 14. Both profiles are product-independent: no rule names a product, a vendor or an interface instance. Attribute names follow the conventions in Method: keyExchange and authentication denote what the interface uses now, and the Supported suffix denotes what it is able to use.

The questions split into two groups. The first is about the interface: what it does, what it could do, and what stands in the way. The second is about what surrounds the interface and has to move with it or before it: the surface that must create the new key, the store that must hold it, and the services it depends on. A supplier can usually answer the first group today. Many suppliers cannot yet answer the second. Putting both groups in one profile would set the minimum requirement so high that few suppliers could meet it. The use case is therefore served by a family of two profiles, ordered by depth: the extended profile asks for everything the baseline asks for, plus the second group of questions (decision 0019).

ProfileExtendsAdds
Baseline
pkic.example.pqc-migration v0.8
Interface disclosure baseline v0.9Capability, enablement and blockers per interface and per purpose; module validation; key wrapping on storage; pointers to the support lifecycle (R1) and the supplier's roadmap (R2), both SHOULD. Accepts product records at the stage implemented only. Makes one inherited rule stricter.
Extended
pkic.example.pqc-migration-extended v0.1
The baseline aboveKey management surfaces, key-store references, external dependencies, the obligation to declare storage, product certification. Tightens validated-mode availability to MUST.

Both profiles serve the same consumer and the same decision. The extended profile therefore goes deeper into the same use case. It is not a branch serving a different purpose. Extension is monotonic: a CBOM conforming to the extended profile also conforms to the baseline, and to the interface profiles beneath it. Rule ids are local to the profile that declares them and are cited with that profile's tag as a prefix, so pqc-migration#I1 and interface-disclosure#I1 are different rules. See Profile for the scheme.

Baseline: product-level rules

#RequirementLevelNote
interface-disclosure#P1Declare at least one cryptographic interfaceMUSTInherited.
interface-disclosure#P2Declare at least one interface of type management, or state why there is noneMUSTInherited. Keycloak's is the Admin API.
interface-disclosure#P3Identify the subject the document describesMUSTInherited. For Keycloak, the Package URL of the container image.
interface-disclosure#P4State the completeness of the interface setMUSTInherited. all-external, all or partial. If a partial list looks complete, the plan built from it has gaps that nobody notices.
interface-disclosure#P5Declare the subject typeMUSTInherited, and narrowed to product.
interface-disclosure#P6Declare one lifecycle stage for the documentMUSTInherited, and narrowed to implemented. The Keycloak record carries it natively, as the lifecycle phase build.
interface-disclosure#R1 to #R6Point to the SBOM, the vulnerability statements, the advisory sources, the security contact, configuration guidance and design intentMUST to MAYInherited. Upstream Keycloak publishes no VEX statements, so the record states not-published under R2.
pqc-migration#R1Point to the support lifecycle of the productSHOULDThe Keycloak record states that none is published.
pqc-migration#R2Point to the supplier's post-quantum roadmapSHOULDThe Keycloak record points to keycloak-pqc-roadmap.json, which names target releases and dependencies that the record itself, stating only status and blocker, does not.
pqc-migration#P1Identify the cryptographic providers the product usesSHOULDLets a consumer reason about update paths shared across interfaces: the JDK serves all seven of Keycloak's TLS interfaces.

Baseline: per-interface rules added here

These rules apply to every declared interface, alongside the inherited interface-disclosure#I1 to #I11. A storage interface describes data at rest, not a communication channel. The channel rules (protocol, version, key exchange, authentication, endpoint roles) therefore do not apply to it. On storage, the inherited keyWrapping (interface-disclosure#I10) takes the place of key exchange, and I12 below asks for its capability counterpart.

#AttributeLevelValues and purpose
I1protocolVersionsSupportedMUSTAll versions the interface can negotiate. Post-quantum key exchange is unavailable on older versions of some protocols. Not on storage.
I2keyExchangeSupportedMUSTThe full set the interface can negotiate, including hybrid constructions. Not on storage.
I3authenticationSupportedMUSTAuthentication migrates separately from key exchange and usually later. Not on storage.
I4enablementMethodMUSTalready-enabled · configuration · software-update · hardware-change · licence · not-available. Separates the cheap changes from the expensive ones.
I5minimumProductVersionconditional MUSTWhere enablementMethod is software-update.
I6providerLocationMUSTsoftware · hsm · tee · unspecified.
I7coexistenceMUSTsimultaneous · exclusive · unknown. An exclusive interface forces a coordinated cutover with every counterparty.
I8negotiationControlSHOULDWhether post-quantum can be required and a classical fallback refused.
I9integrationConstraintsSHOULDKnown effects of enabling the capability: size limits, intermediaries, performance.
I10moduleValidationSchemeMUSTfips-140-2 · fips-140-3 · iso-19790 · national-crypto-approval · none. The validation of the module implementing the interface. This is the fact that a certification blocker (G1.2) rests on. New in v0.7.
I11moduleValidationRefconditional MUSTThe certificate reference, where a scheme other than none is declared. New in v0.7.
I12keyWrappingSupportedconditional MUSTOn a storage interface: the wrapping algorithms the storage path can use, or none. New in v0.7.
G1.1capabilityStatusMUSTPer cryptographic purpose. available · committed · planned · under-evaluation · not-planned. Each value states a level of commitment, not a date.
G1.2blockedByconditional MUSTWhere the purpose's status is not available. provider · product · hardware · standard · certification.
G1.3roadmapRefMAYReference to a roadmap entry carrying the target release. Interfaces sharing a blocker reference the same entry.
G1.4validatedModeAvailabilitySHOULDWhere the purpose's capability is available: in-validated-mode · outside-validated-mode-only · no-validated-mode. In regulated settings, a capability commonly ships before the module implementing it is validated. New in v0.7.

Group rule G1: capability, one entry per cryptographic purpose

Group rule G1 is keyed to the cryptographic purpose vocabulary. The vocabulary has seven values: key-establishment, encryption, entity-authentication, data-integrity, non-repudiation, key-protection and key-derivation. Its key coverage is all-purposes, so every interface carries an entry for all seven, not only for the three purposes the profile's scope takes in depth (C13). The extended profile takes a fourth, key-protection, in depth. Each entry has the four members G1.1 to G1.4 listed above. Group members are evaluated inside each entry, so a conditional guard such as the one on blockedBy refers to that entry's own capabilityStatus. A guard may be removed (tightening) but never added or narrowed.

Extended: rules added at the second depth

#Attribute or ruleLevelApplies to, and purpose
P1Declare at least one storage interface, or state why there is noneMUSTStored ciphertext is exposed by a shorter route than captured traffic, and a backup path is the interface most easily left out.
P2productCertificationSchemeSHOULDCommon Criteria, EUCC or a national scheme. Kept apart from module validation because it certifies a different object: enabling a new algorithm can take a product outside its evaluated configuration.
I1keyManagementFunctionMUSTManagement interfaces: whether they manage keys at all. Keycloak's health port does not.
I2keyOperationsMUSTSurfaces that manage keys: generate, import, export, request-certificate, rotate and so on.
I3keyTypesSupportedMUSTThe key types the surface can generate or import. This rule catches an interface that can use a new algorithm when the product cannot create the key for it.
I4keyTypesMUSTThe key types held now: the population the migration has to replace.
I5, I6keyStoreFormatsSupported, keyStoreFormatsSHOULDContainer formats, where a format cannot carry a new key type.
I7keyStoreLocationMUSTSoftware, HSM, TEE, TPM, OS keyring or external vault: whether the new key type waits on hardware.
I8keyStoreRefSHOULDEvery other interface: the management interface that manages its keys, or out-of-band, product-managed or none.
I9externalDependenciesMUSTServices the interface's cryptography depends on at run time: certificate authority, revocation responder, directory, identity provider, HSM, key vault, time source, or none. These are what the operator must migrate first.
I10enablementSettingSHOULDWhere enablement is by configuration: the setting that enables it.
pqc-migration#G1.4validatedModeAvailabilityMUSTTightened from SHOULD. At the extended depth the consumer is deciding the order of actual changes, so it needs this fact.

The one inherited rule the baseline makes stricter

Inherited ruleBaselineHere
I9 implementationPurlMUST, may be withheldMUST, may not be withheld

Migration planning depends on knowing which library implements an interface, since that determines whether an update exists and when it arrived. If a vendor withholds it, the consumer cannot plan the order of the work. This is the only inherited rule the baseline profile changes. Raising the level is permitted because it makes the rule stricter.

Conditional rules

Several rules apply only when another attribute has a particular value. A profile is not limited to a flat list of mandatory fields. A requirement can depend on the value of another attribute. I5 obliges a producer claiming that a capability needs a software update to say which version provides it. I11 asks for a certificate reference only where a validation scheme is declared, and I12 asks for wrapping algorithms only on a storage interface. Inside the capability group, G1.2 asks for a blocker only where a purpose is not available, and G1.4 asks about validated mode only where it is. Making these rules unconditional would not help. Requiring a version or a certificate from every interface produces noise. Requiring none leaves the useful case unstated.

Availability, and why it is not a date on an interface

An earlier draft of this profile put a plannedAvailability date on each interface. That is the obvious design, but it does not work, because of how interfaces gain capability.

Interfaces do not gain capability independently. A product with six TLS interfaces built on one cryptographic provider gains post-quantum key exchange on all six at the moment that provider is updated and the product integrates it. A date on each interface duplicates one underlying event six times, and the six copies drift apart as they are maintained. Availability is therefore a property of the change that delivers the capability, such as the provider update. The interfaces inherit it from that change.

What a planner needs first is therefore not the date but the obstacle, because the obstacle determines whether any date is credible and who is able to move it.

blockedByWhat has to happenWho can move itPredictability
providerA dependency is upgraded to a version offering the algorithm.The vendor, by taking the upgrade.Reasonable
productThe product's own code must change to expose or negotiate it.The vendor, in a named release.Reasonable
hardwareA module, firmware or platform must support the algorithm.The vendor together with the module supplier.Poor
standardNo specification yet defines the algorithm for this protocol.Nobody, until the standards process concludes.None
certificationA validated implementation is required, for example under a scheme such as FIPS.An external laboratory or scheme.Externally determined

The most important distinction is the fourth row, standard. An interface blocked on a protocol standard cannot be given a credible date by any vendor, and a consumer who understands that stops waiting and considers compensating controls instead. Recording it as "planned, date to follow" alongside a case that really is scheduled for the next release mixes up two situations that call for opposite responses.

Keycloak shows four of the five on one product. TLS key exchange is blocked by the provider: hybrid ML-KEM groups ship in JDK 27 and are enabled there by default, with backports to earlier releases announced, so the timing depends on the Java runtime's releases, not Keycloak's. Token signing is blocked by a standard: an ML-DSA signature provider is committed upstream, but the JSON Web Key representation it needs is still an Internet-Draft. The cluster transport is blocked by the product, because Keycloak generates its RSA-2048 key itself. And whether the capability will be usable in validated mode is a certification question for the Bouncy Castle FIPS module.

Where a date or release is offered, the profile keeps it out of the interface and out of the CBOM. Target release and date sit in a roadmap entry that interfaces reference through roadmapRef, so that interfaces sharing a blocker point at one entry. There are two reasons. First, a CBOM revision is a fixed record of one point in time. A date that slips either goes stale inside a document that looks authoritative, or forces the CBOM to be republished when nothing about the product has changed. Second, roadmap data has a different owner and changes at a different pace from the rest of the document. This is the same argument that the Governance section makes for keeping artifacts with separate lifecycles apart.

A target release is also preferable to a calendar date. Releases are the vendor's own unit of change, and the statement "this lands in 9.x" survives slippage in a way that a date does not.

Keycloak under the baseline

The table compares two interfaces of the product record: the TLS listener and the token service it carries. The record describes the image as shipped. Keycloak does not choose the server certificate, so the record states deployment-defined for the listener's authentication and points to the guide where the operator sets it (rule interface-disclosure#R5). The values are read from cbom-keycloak-product.cdx.json.

Attributetls-httpssvc-oidc
Inherited from the interface disclosure baseline
interfaceTypeserviceservice
endpointRolesclient, serverissuer, relying-party
protocol / protocolVersionTLS / 1.3OIDC / 1.0
keyExchangeX25519none (token encryption is off by default)
encryptionAES-256-GCMnone
authenticationdeployment-defined (the operator supplies the certificate)RS256
implementationPurlpkg:rpm/redhat/java-21-openjdk-headless?arch=x86_64&distro=rhel-9pkg:maven/org.keycloak/keycloak-services@26.7.3
defaultStateenabledenabled
lifecycleStageimplemented, declared once for the record in metadata.lifecycles (phase build)the same
Per-interface rules of the migration profile
protocolVersionsSupported (I1)1.2, 1.31.0
keyExchangeSupported (I2)x25519, secp256r1, secp384r1, secp521r1, x448, ffdhe2048RSA-OAEP, RSA-OAEP-256, ECDH-ES
authenticationSupported (I3)RSA-PSS, RSA PKCS#1, ECDSA P-256 and P-384, and Ed25519 signature schemesthe RS, PS, ES and HS families, and EdDSA
enablementMethod (I4)not-availablenot-available
minimumProductVersion (I5)not required, because the method is not software-updatenot required
providerLocation (I6)softwaresoftware
coexistence (I7)simultaneoussimultaneous
negotiationControl (I8)Named groups are set by the JVM property jdk.tls.namedGroupsThe signature algorithm is set per realm and per client
integrationConstraints (I9)The server certificate and key are operator-supplied filesML-DSA-65 tokens exceed the 4 KB browser cookie limit. Relying parties must accept the AKP key type, which is still an Internet-Draft
moduleValidationScheme (I10)none in default modenone in default mode
Group rule G1, the two purposes taken in depth
key-establishmentplanned, blocked by provider, roadmap JEP 527under-evaluation, blocked by standard
entity-authenticationunder-evaluation, blocked by standardcommitted, blocked by standard, roadmap Keycloak issue 43690

Capability, per purpose

Capability is stated per cryptographic purpose. Every interface carries one G1 entry for each of the seven purposes, and each entry has the members G1.1 to G1.4. The purposes of one interface migrate on different timetables, so they are answered separately. Across Keycloak, the two purposes that matter most look like this.

Interfaceskey-establishment entryentity-authentication entry
Six of the seven JDK TLS interfacesplanned, blocked by provider, roadmap: JEP 527under-evaluation, blocked by standard
int-cache, the seventh, shown apart because its entity authentication differsplanned, blocked by providerunder-evaluation, blocked by product: the key type is fixed
svc-oidc, mgmt-adminunder-evaluation, blocked by standardcommitted, blocked by standard, roadmap: Keycloak issue 43690
svc-samlunder-evaluation, blocked by standardunder-evaluation, blocked by standard
svc-http, sto-realm-keysnot-planned, blocked by productnot-planned, blocked by product

The other five purposes carry a status as well. On the TLS interfaces, encryption, data integrity and key derivation are available, and each says whether it works in validated mode. Key protection is not-planned everywhere. This repeats the storage finding: nothing wraps Keycloak's keys at rest. A deferred purpose owes only a status and, where it is not available, a blocker. That costs a producer almost nothing, and it keeps a shallower depth from becoming a permanent floor.

Most of these values are the same across interfaces because they are properties of the library that implements the interfaces. The document states them once, on that library, and an interface states only what differs. The cluster transport inherits the JDK's entries and overrides entity authentication. SAML inherits the Keycloak library's entries and overrides two purposes. Rules are evaluated on the values that result after inheritance and overrides.

A purpose is different from an operation. The purpose vocabulary is useful because it records that difference. CycloneDX already records operations: a certificate signature carries cryptoFunctions: ["sign", "verify"], and so would a firmware signature on the same product. The certificate signature serves entity authentication and migrates when the PKI does. The firmware signature must still verify years after it was written. The operation is the same, but the migration timescale and the work are different. See Terms for the four-part test an entry has to pass, and decision 0010 for the reasoning.

What a planner concludes

Without seeing inside the product, an operator reading the baseline document can conclude the following. No Keycloak interface can be made quantum-safe by configuration today. TLS key exchange arrives with the Java runtime, so the action is to track the runtime in the image and to test hybrid groups against the directory, the database and the mail server, which must support them too. Token signing will take the longest. It waits on a standard, so pressing the supplier for a date will achieve little. The time is better spent finding relying parties that reject unknown key types and flows that keep tokens in cookies. The cluster transport depends on a change in the product. Plain HTTP behind a proxy carries tokens in clear on the internal hop and should be closed first, because no post-quantum work protects traffic that is not encrypted at all. An inventory of the algorithms in use today yields none of these conclusions.

Keycloak under the extended profile

The baseline says what each interface could do. The extended profile asks whether the product around it can support the change. For Keycloak the answer is concentrated in one place: the Admin API, which generates and holds the realm keys every token interface signs with.

AttributeKeycloak
keyManagementFunction on mgmt-adminkeys-and-certificates
keyOperationsgenerate, import, export (public keys and certificates only), rotate, delete
keyTypesSupportedRSA-2048 and 4096, ECDSA P-256 to P-521, Ed25519, Ed448, HMAC, AES. No ML-DSA.
keyTypesRSA-2048, HMAC-SHA512, AES-128: the defaults of a new realm
keyStoreLocationsoftware
keyManagementFunction on tls-mgmtnone
keyStoreRefsvc-oidc, svc-saml: the Admin API. tls-https and the outbound TLS: out-of-band, because the keys arrive as files. int-cache: product-managed.
externalDependenciestls-https: certificate-authority. int-ldap: directory. int-broker and svc-broker-tokens: identity-provider. Token services: none.
Storagesto-realm-keys declared, with keyWrapping none
productCertificationSchemenone for the upstream project (to be verified)

The extended document adds three conclusions to the baseline's. When ML-DSA signing lands, the key management surface must be able to generate the key as well, and today it cannot. Every baseline rule passes, and yet the operator could not migrate. pqc-migration-extended#I3 exists to catch this case. TLS migration cannot start until the operator's certificate authority can issue the new certificates, and the directory and identity providers have to follow. And the realm keys that sign every token sit unwrapped in the database, so a database backup is as sensitive as the signing service itself.

What the profiles deliberately exclude

The profile deliberately leaves out three kinds of information.

It carries no readiness or posture verdict. Whether a declared algorithm set counts as quantum-safe is a judgement against criteria still under revision, so an external policy computes it from these facts at the time of asking and dates the result. Policy Evaluation sets out the reasoning, which is also why pqcPosture was dropped from the baseline profile.

Maturity scores are excluded on the same grounds. Collapsing different attributes into one number has a further drawback. It tends to hide whichever attribute is actually blocking the migration.

Internal implementation is out of scope, so no source references, design detail or component structure are requested. This exclusion follows directly from the black-box constraint. It is not a compromise made to accommodate vendors. A vendor asked to expose internals will decline, and a profile nobody satisfies achieves nothing.

The profile also omits an encryptionSupported attribute. The encryption attribute from the interface disclosure baseline is inherited and still required, so an interface states the bulk algorithm it uses. What this profile does not add is an encryptionSupported counterpart. Symmetric encryption at adequate key lengths is not the pressing concern in a post-quantum migration, and the interfaces needing work are identified by their key exchange and authentication. A profile combining migration with a broader agility objective would add it.

The extended profile leaves out four more things. Cipher suite lists repeat what the separate key exchange, authentication and encryption attributes already state, and they cannot carry TLS 1.3 key exchange. Port numbers are deployment facts. Secret hygiene, such as how a database password is supplied, is not a migration fact. And individual keys are not identified: the profile describes the stores and what they can hold. The methodology now has a way to identify a key across tools, by its public-key fingerprint or by its role and location, and a later depth could use it.

Expressing it in a CBOM

The attributes do not depend on any format. The example documents use CycloneDX 2.0, and the full mapping is in Formats. A CycloneDX 1.7 form of the product record, legacy/cbom-keycloak-product-1.7.cdx.json, carries the same facts and receives the same verdicts, flagged as legacy. The converter cdx17_to_20.py turns a 1.6 or 1.7 CBOM into 2.0.

The token interface (svc-oidc) and the library that provides it, in outline. The capability entries are stated once on the library and inherited by every interface it provides:

"metadata": { "lifecycles": [{ "phase": "build" }] },
"inventories": [{
  "subject": { "type": "container", "name": "Keycloak", "version": "26.7.3", ... },
  "components": [
    {
      "type": "service",
      "bom-ref": "service:svc-oidc",
      "name": "OIDC and OAuth 2.0 token issuance (JOSE)",
      "endpoints": ["https://{hostname}/realms/{realm}/protocol/openid-connect"],
      "properties": [
        { "name": "pkic:profile:interfaceType", "value": "service" },
        { "name": "pkic:profile:protocol", "value": "OIDC" },
        { "name": "pkic:profile:protocolVersion", "value": "1.0" },
        { "name": "pkic:profile:endpointRole:issuer", "value": "endpoint:keycloak" },
        { "name": "pkic:profile:endpointRole:relying-party", "value": "endpoint:client-application" },
        { "name": "pkic:profile:keyExchange", "value": "none" },
        { "name": "pkic:profile:encryption", "value": "none" },
        { "name": "pkic:profile:defaultState", "value": "enabled" }
      ]
    },
    {
      "type": "library",
      "bom-ref": "lib:keycloak-services",
      "name": "Keycloak services",
      "identifiers": [{ "party": "party:document-author",
        "identities": [{ "scheme": "purl",
                         "value": "pkg:maven/org.keycloak/keycloak-services@26.7.3" }] }],
      "properties": [
        /* Group G1: key establishment */
        { "name": "pkic:profile:capabilityByPurpose:key-establishment:capabilityStatus", "value": "under-evaluation" },
        { "name": "pkic:profile:capabilityByPurpose:key-establishment:blockedBy", "value": "standard" },
        /* Group G1: entity authentication (token signing) */
        { "name": "pkic:profile:capabilityByPurpose:entity-authentication:capabilityStatus", "value": "committed" },
        { "name": "pkic:profile:capabilityByPurpose:entity-authentication:blockedBy", "value": "standard" },
        { "name": "pkic:profile:capabilityByPurpose:entity-authentication:roadmapRef",
          "value": "https://github.com/keycloak/keycloak/issues/43690" }
      ]
    }
  ]
}],
"dependencies": [
  { "ref": "service:svc-oidc",
    "dependsOn": ["service:https-main", "crypto:algo:rs256", "crypto:key:realm-rsa"] },
  { "ref": "service:https-main", "dependsOn": ["crypto:protocol:tls-https"] },
  { "ref": "lib:keycloak-services", "provides": ["service:svc-oidc", "service:svc-saml",
                                                  "service:mgmt-admin", "service:svc-broker-tokens"] }
]

Where an attribute is unavailable, the four disclosure outcomes apply. none is a value, not a marker: it states that no algorithm is applied for that job, as with Keycloak's unencrypted tokens.

The example documents

The Keycloak product record makes the use case testable. The two failing migration examples each differ from it in one place, so each fails exactly one rule. The design record is different: it changes the stage of every interface and fails many rules. All are published under Files, and the verdicts come from the reference validator.

DocumentVerdict
cbom-keycloak-product.cdx.jsonConforms to both depths, to the interface disclosure baseline and interface enumeration beneath them, and to procurement
cbom-keycloak-product-fail-pqc-I12.cdx.jsonFails pqc-migration#I12 only: the storage interface omits its key-wrapping capability
cbom-keycloak-product-fail-ext-I3.cdx.jsonFails pqc-migration-extended#I3 only: the Admin API omits the key types it can generate
cbom-keycloak-product-intended.cdx.jsonA design record for Keycloak 27.0. Fails baseline I8 on every interface, and I3 to I5 where it repeats build-time literals; conforms to interface enumeration

The rules files are profile-pqc-migration.rules.json and profile-pqc-migration-extended.rules.json. The readiness-gap policy reads the same product record, joined to an operator's deployment records, and finds token signing not-capable and Keycloak's own TLS not-capable. Its result is result-readiness-gap-sso-prod.json.

Recorded decisions

Several choices in these profiles were made against the more obvious alternative. Each is written up as a decision record in the repository, with the options considered, the rationale and what reversing it would involve. The records are authoritative. The summaries below are only for orientation.

RecordDecisionAspect
0002 Capability is stated as facts. The profile requires the algorithm sets an interface supports and does not ask whether they amount to being quantum-safe. That judgement is made by an external policy at the time of asking, for the reasons given in Policy Evaluation. 3.3
0007 Availability is expressed as a status and a blocker. Dates and target releases sit in a referenced roadmap entry, away from the interface. 3.10
0010 Capability is stated per cryptographic purpose. Capability status, blocker, roadmap reference and validated-mode availability are the four members of a purpose-keyed group rule (G1). An interface carries one entry for each of the seven purposes in the vocabulary, rather than one attribute per mechanism. 3.7
0019 Adoption is staged by a family of profiles ordered by depth. The baseline and extended profiles are two depths of one family. 3.9
0022 The two depths, and how they meet a real product. Module validation and storage in the baseline; key management and dependencies in the extended profile; an interface is a logical boundary; application protocols are CycloneDX services; native fields first; implementation facts inherited from the providing library. 3.9

The rules above also depend on decisions taken elsewhere in the methodology: 0004 for what this profile is permitted to change in the baseline it extends, and 0005 for the Supported suffix. The full index is in decisions/.

Open questions for the working group

These are also carried in the open questions register, which collects the unresolved items from every section and maps each to the methodology aspect that tracks it.

PKIC CBOM Profiles Working Group · draft for comment.