Skip to content

gcs: Expose transparency-trust-list-base64 in security-context based on injected TTLs - #2991

Merged
Maksim An (anmaxvl) merged 1 commit into
microsoft:mainfrom
micromaomao:ttl-in-security-context
Nov 20, 2026
Merged

Maksim An (anmaxvl) merged 1 commit into
microsoft:mainfrom
micromaomao:ttl-in-security-context

Conversation

@micromaomao

Copy link
Copy Markdown
Member

In order to enable the application to provide with a relying party a full set of transparent endorsements, we also expose a "first party" TTL in the security context that we believe allows verification of the transparent UVM reference info and TCB reference info. Such a TTL will be delivered via the fragment injection mechanism like for TTLs for transparent fragments, and GCS identifies such a TTL via hard-coded issuer and subject strings. When such a TTL is injected, it is used to populate the transparency-trust-list-base64 file on next container start.

Using it as the content of transparency-trust-list-base64 is the only "special treatment" applied to such TTLs. GCS does not otherwise give it any more trust than allowed by the policy.

COSE signature and issuer certificate checks are applied to all injected TTLs, before this matching is done. A malformed or not-correctly-signed TTL would not be used for the security context file even if the COSE envelope header claims the correct issuer and subject.

Assisted-by: GitHub-Copilot

…on injected TTLs

In order to enable the application to provide with a relying party a full
set of transparent endorsements, we also expose a "first party" TTL in the
security context that we believe allows verification of the transparent
UVM reference info and TCB reference info.  Such a TTL will be delivered
via the fragment injection mechanism like for TTLs for transparent
fragments, and GCS identifies such a TTL via hard-coded issuer and subject
strings.  When such a TTL is injected, it is used to populate the
transparency-trust-list-base64 file on next container start.

Using it as the content of transparency-trust-list-base64 is the only
"special treatment" applied to such TTLs.  GCS does not otherwise give it
any more trust than allowed by the policy.

COSE signature and issuer certificate checks are applied to all injected
TTLs, before this matching is done.  A malformed or not-correctly-signed
TTL would not be used for the security context file even if the COSE
envelope header claims the correct issuer and subject.

Assisted-by: GitHub-Copilot
Signed-off-by: Tingmao Wang <tingmaowang@microsoft.com>

Copilot AI 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.

🟡 Changes recommended

The new first-party TTL selection and export path lacks regression coverage for matching, SVN ordering, invalid-input cache preservation, and export behavior after policy rejection or in TTL-only cases.

1 open issue
What changed in this PR

This PR exposes an injected first-party transparency trust list (TTL) in the container security context, allowing applications to provide it alongside reference information to relying parties without granting it additional policy trust.

Changes:

  • Defines the transparency-trust-list-base64 filename.
  • Caches validated TTLs matching designated issuer/subject pairs, retaining the highest received SVN.
  • Exports the cached COSE bytes as base64 when creating a container’s security context.
File Description
pkg/​securitypolicy/​securitypolicy.go Adds the TTL security-context filename constant.
pkg/​securitypolicy/​securitypolicy_options.go Adds TTL matching, synchronized caching, SVN ordering, and security-context export.

Review effort: Balanced

Comment on lines +413 to +415
if len(s.transparencyTrustList) == 0 || s.transparencyTrustListSVN <= *svnFromCwt {
s.transparencyTrustList = append(s.transparencyTrustList[:0], raw...)
s.transparencyTrustListSVN = *svnFromCwt
// purely infromative, and we do not otherwise give such a TTL special
// privileges or use keys in it without first consulting the policy).
const (
firstPartyTTLIssuer = "did:x509:0:sha256:I__iuL25oXEVFdTP_aBLx_eT1RPHbCQ_ECBQfYZpt9s::eku:1.3.6.1.4.1.311.76.59.1.3"

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

how like are these to change in the future? Would we rather (e.g.) go embed and supply a JSON array with values at compile time?

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.

The same as the issuer for fragments and UVM endorsements. Hopefully not likely, because this value needs to be communicated to Relying Parties, who need to pin it and use to verify the TTLs we publish, it's not something we can change unilaterally without breaking RPs.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

Agree with Amaury, I think basically once this goes live we will not have an easy way to change it anymore (same for issuer of UVM endorsement etc)

@micromaomao

Copy link
Copy Markdown
Member Author

Tested injecting a TTL, it is added to security context correctly regardless of policy. A newer TTL with a higher SVN overrides the older one. I think this is ready to merge.

@achamayou

Copy link
Copy Markdown
Member

For reference, this should be the schema for a TTL payload:

; ─── Reused from RFC 9052 ────────────────────────────────────────────────
label  = int / tstr
values = any

COSE_Key = {
    1 => tstr / int,            ; kty
    ? 2 => bstr,                ; kid
    ? 3 => tstr / int,          ; alg
    ? 4 => [+ (tstr / int) ],   ; key_ops
    ? 5 => bstr,                ; Base IV
    * label => values           ; type-specific + extensions
}

COSE_KeySet = [+ COSE_Key]      ; SCRAPI-compatible

; ─── TTL-specific ────────────────────────────────────────────────────────
TransparencyTrustListPayload = { + tstr => LedgerEntry }
    ; keyed by the receipt's CWT `iss` (byte-for-byte; MST convention is an FQDN)
    ; the format version lives in the envelope's content type;
    ; the anti-rollback sequence lives in the envelope's CWT `svn` claim.

LedgerEntry = {
    ? 1 => COSE_KeySet,                      ; keys: SCRAPI-compatible; OPTIONAL, contains ≥ 1 key when present
    ? 2 => [* bstr],                         ; revoked_kids: kids the publisher has revoked; public keys are intentionally absent
    ? 3 => tstr,                             ; keys_path: URL-path suffix appended to the issuer-derived URL for online key fetch (§7.4)
    ? 4 => tstr,                             ; keys_path_profile: identifies non-default response format/profile at keys_path; default (absent) = SCRAPI (§7.4)
    ? 5 => bool,                             ; signer_attested: publisher claim that registration policy validates signer attestation (§3.3)
    ? 6 => bool,                             ; keys_authoritative: when true, listed `keys` are the only valid set for this entry; consumers MUST NOT consult any online source (§7.3/§7.4); default false
    * tstr => values,                        ; private extensions only; unknown uint labels reject (§5.3)
}

and the envelope:

TTL_content_type = "application/vnd.transparency-trust-list.v1+cose"
    ; the trailing `.v1` carries the spec version; future revisions bump to .v2, etc.

; Per RFC 9597. Carried at protected-header label 15 to bind to the signature.
TTL_CWT_Claims = {
    1 => tstr,                  ; iss: TTL publisher identity (REQUIRED)
    2 => tstr,                  ; sub: scope label (REQUIRED)
    "svn" => uint,              ; svn: strict-monotonic per (iss, sub); anti-rollback (REQUIRED)
    ? 4 => uint,                ; exp: epoch seconds; consumers reject expired TTLs
    ? 5 => uint,                ; nbf: epoch seconds; consumers reject not-yet-valid TTLs
    ? 6 => uint,                ; iat: epoch seconds (RECOMMENDED for diagnostics)
    ? 7 => bstr,                ; cti: unique TTL identifier (RECOMMENDED for diagnostics)
    * label => values
}

TTL_Protected_Header_Map = {
    1  => int / tstr,                        ; alg (REQUIRED)
    3  => TTL_content_type,                  ; content type (REQUIRED)
    15 => TTL_CWT_Claims,                    ; CWT Claims (REQUIRED)
    ? 4  => bstr,                            ; kid (raw-key identifier; see §5.2 envelope key identifier conventions)
    ? 33 => bstr / [ 2* bstr ],              ; x5chain (REQUIRED if signer uses x509; see §6.1)
    ? 34 => [ int / tstr, bstr ],            ; x5t (RFC 9360 §2 cert thumbprint; see §5.2 notes)
    * label => values
}

TTL_Unprotected_Header_Map = {
    * label => values
}

TransparencyTrustList = [
    protected   : bstr .cbor TTL_Protected_Header_Map,
    unprotected : TTL_Unprotected_Header_Map,
    payload     : bstr .cbor TransparencyTrustListPayload,
    signature   : bstr
]

TransparencyTrustList_Tagged = #6.18(TransparencyTrustList)

@anmaxvl
Maksim An (anmaxvl) merged commit af29fc3 into microsoft:main Nov 20, 2026
50 of 51 checks passed
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.

4 participants