fix(kds/TCBVersion): address backwards compatibility

- address backwards compatibility issues raised in the review
- revert changes to:
  - kds/kds_test.go
  - testing/fakekds.go

Signed-off-by: Jagannathan Raman <jraman567@gmail.com>

Author: jraman567

kds/kds.go

@@ -129,16 +129,20 @@ var (
 	}
 )
 
-// TCBVersion represents the SEV-SNP TCB_VERSION
-type TCBVersion struct {
+// TCBVersion is a 64-bit bitfield of different security patch levels of AMD firmware and microcode.
+// Deprecated: use TCBVersionStruct instead
+type TCBVersion uint64
+
+// TCBVersionStruct represents the SEV-SNP TCB_VERSION
+type TCBVersionStruct struct {
 	// Version identifies the version of this structure as defined in V[C,L]EK x509 certificate extensions
 	Version uint8
 	// TCB is a 64-bit bitfield of different security patch levels of AMD firmware and microcode.
 	TCB uint64
 }
 
 // String returns the version of the TCB in string format
-func (v TCBVersion) String() string {
+func (v TCBVersionStruct) String() string {
 	switch v.Version {
 	case TCBStructVersion0:
 		return fmt.Sprintf("Milan or Genoa TCB: 0x%x", v.TCB)
@@ -149,6 +153,16 @@ func (v TCBVersion) String() string {
 	}
 }
 
+// TCBVersionStructFromTCBVersion converts an object of type TCBVersion to TCBVersionStruct
+func TCBVersionStructFromTCBVersion(v TCBVersion) TCBVersionStruct {
+	return TCBVersionStruct{Version: TCBStructVersion0, TCB: uint64(v)}
+}
+
+// TCBVersionStructToTCBVersion converts an object of type TCBVersionStruct to TCBVersion
+func TCBVersionStructToTCBVersion(v TCBVersionStruct) uint64 {
+	return v.TCB
+}
+
 // Extensions represents the information stored in the KDS-specified x509 extensions of a V{C,L}EK
 // certificate.
 type Extensions struct {
@@ -158,9 +172,11 @@ type Extensions struct {
 	// Primary vs secondary is irrelevant to verification. The length of this
 	// field depends on the TCB version; 64 bytes for version 0 and
 	// 8 bytes for version 1
-	HWID       []byte
-	TCBVersion TCBVersion
-	CspID      string
+	HWID []byte
+	// Deprecated: use TCBVersionStruct instead
+	TCBVersion       TCBVersion
+	TCBVersionStruct TCBVersionStruct
+	CspID            string
 }
 
 func oidTokdsOID(id asn1.ObjectIdentifier) (kdsOID, error) {
@@ -250,10 +266,8 @@ type TCBParts struct {
 	FmcSpl uint8
 }
 
-// ComposeTCBParts returns an SEV-SNP TCB_VERSION from OID mapping values. The spl4-spl7 fields are
-// reserved, but the KDS specification designates them as 4 byte-sized fields.
-func ComposeTCBParts(parts TCBParts) (TCBVersion, error) {
-	tcbVersion := TCBVersion{}
+func composeTCBPartsToTCBVersionStruct(parts TCBParts) (TCBVersionStruct, error) {
+	tcbVersion := TCBVersionStruct{}
 	// Only UcodeSpl may be 0-255. All others must be 0-127.
 	check127 := func(name string, value uint8) error {
 		if value > 127 {
@@ -298,9 +312,26 @@ func ComposeTCBParts(parts TCBParts) (TCBVersion, error) {
 	return tcbVersion, nil
 }
 
-// DecomposeTCBVersion interprets the byte components of the AMD representation of the
-// platform security patch levels into a struct.
-func DecomposeTCBVersion(tcb TCBVersion) TCBParts {
+// ComposeTCBParts returns an SEV-SNP TCB_VERSION from OID mapping values. The spl4-spl7 fields are
+// reserved, but the KDS specification designates them as 4 byte-sized fields.
+// Deprecated: use ComposeTCBPartsToTCBVersionStruct instead
+func ComposeTCBParts(parts TCBParts) (TCBVersion, error) {
+	tcb, err := composeTCBPartsToTCBVersionStruct(parts)
+	if err != nil {
+		return TCBVersion(0), err
+	}
+
+	return TCBVersion(tcb.TCB), nil
+}
+
+// ComposeTCBPartsToTCBVersionStruct returns an SEV-SNP TCB_VERSION from OID mapping
+// values as a TCBVersionStruct. The spl4-spl7 fields are reserved, but the
+// KDS specification designates them as 4 byte-sized fields.
+func ComposeTCBPartsToTCBVersionStruct(parts TCBParts) (TCBVersionStruct, error) {
+	return composeTCBPartsToTCBVersionStruct(parts)
+}
+
+func decomposeTCBVersionStruct(tcb TCBVersionStruct) TCBParts {
 	switch tcb.Version {
 	case TCBStructVersion1:
 		return TCBParts{
@@ -326,6 +357,34 @@ func DecomposeTCBVersion(tcb TCBVersion) TCBParts {
 	}
 }
 
+// DecomposeTCBVersion interprets the byte components of the AMD representation of the
+// platform security patch levels into a struct.
+// Deprecated: use DecomposeTCBVersionStruct instead
+func DecomposeTCBVersion(tcb TCBVersion) TCBParts {
+	parts, _ := DecomposeTCBVersionStruct(tcb)
+	return parts
+}
+
+// DecomposeTCBVersionStruct accepts SEV-SNP TCB version as TCBVersion,
+// TCBVersionStruct or uint64 and  decodes various security patch
+// levels from them.
+func DecomposeTCBVersionStruct(t interface{}) (TCBParts, error) {
+	var tcb TCBVersionStruct
+
+	switch v := t.(type) {
+	case TCBVersionStruct:
+		tcb = v
+	case TCBVersion:
+		tcb = TCBVersionStructFromTCBVersion(v)
+	case uint64:
+		tcb = TCBVersionStruct{Version: TCBStructVersion0, TCB: v}
+	default:
+		return TCBParts{}, fmt.Errorf("unsupported TCB type: %v", t)
+	}
+
+	return decomposeTCBVersionStruct(tcb), nil
+}
+
 // TCBPartsLE returns true iff all TCB components of tcb0 are <= the corresponding tcb1 components.
 func TCBPartsLE(tcb0, tcb1 TCBParts) bool {
 	return (tcb0.UcodeSpl <= tcb1.UcodeSpl) &&
@@ -473,7 +532,7 @@ func kdsOidMapToExtensions(exts map[kdsOID]*pkix.Extension) (*Extensions, error)
 		}
 	}
 
-	tcb, err := ComposeTCBParts(TCBParts{
+	tcb, err := ComposeTCBPartsToTCBVersionStruct(TCBParts{
 		Version:  result.StructVersion,
 		BlSpl:    blspl,
 		SnpSpl:   snpspl,
@@ -488,7 +547,8 @@ func kdsOidMapToExtensions(exts map[kdsOID]*pkix.Extension) (*Extensions, error)
 	if err != nil {
 		return nil, err
 	}
-	result.TCBVersion = tcb
+	result.TCBVersion = TCBVersion(tcb.TCB)
+	result.TCBVersionStruct = tcb
 	return &result, nil
 }
 
@@ -603,10 +663,14 @@ func ProductCertChainURL(s abi.ReportSigner, productLine string) string {
 	return fmt.Sprintf("%s/cert_chain", productBaseURL(s, productLine))
 }
 
-// VCEKCertURL returns the AMD KDS URL for retrieving the VCEK on a given product
+// VCEKCertQuery returns the AMD KDS URL for retrieving the VCEK on a given product
 // at a given TCB version. The hwid is the CHIP_ID field in an attestation report.
-func VCEKCertURL(productLine string, hwid []byte, tcb TCBVersion) string {
-	parts := DecomposeTCBVersion(tcb)
+func VCEKCertQuery(productLine string, hwid []byte, tcb TCBVersionStruct) (string, error) {
+	parts, err := DecomposeTCBVersionStruct(tcb)
+	if err != nil {
+		return "", err
+	}
+
 	switch parts.Version {
 	case TCBStructVersion1:
 		hwidv1 := hwid[0:TCBHwIDLenVersion1]
@@ -618,7 +682,7 @@ func VCEKCertURL(productLine string, hwid []byte, tcb TCBVersion) string {
 			parts.SnpSpl,
 			parts.UcodeSpl,
 			parts.FmcSpl,
-		)
+		), nil
 	default:
 		return fmt.Sprintf("%s/%s?blSPL=%d&teeSPL=%d&snpSPL=%d&ucodeSPL=%d",
 			productBaseURL(abi.VcekReportSigner, productLine),
@@ -627,14 +691,26 @@ func VCEKCertURL(productLine string, hwid []byte, tcb TCBVersion) string {
 			parts.TeeSpl,
 			parts.SnpSpl,
 			parts.UcodeSpl,
-		)
+		), nil
 	}
 }
 
-// VLEKCertURL returns the GET URL for retrieving a VLEK certificate, but without the necessary
+// VCEKCertURL returns the AMD KDS URL for retrieving the VCEK on a given product
+// at a given TCB version. The hwid is the CHIP_ID field in an attestation report.
+// Deprecated: use VCEKCertQuery instead
+func VCEKCertURL(productLine string, hwid []byte, tcb TCBVersion) string {
+	url, _ := VCEKCertQuery(productLine, hwid, TCBVersionStructFromTCBVersion(tcb))
+	return url
+}
+
+// VLEKCertQuery returns the GET URL for retrieving a VLEK certificate, but without the necessary
 // CSP secret in the HTTP headers that makes the request validate to the KDS.
-func VLEKCertURL(productLine string, tcb TCBVersion) string {
-	parts := DecomposeTCBVersion(tcb)
+func VLEKCertQuery(productLine string, tcb TCBVersionStruct) (string, error) {
+	parts, err := DecomposeTCBVersionStruct(tcb)
+	if err != nil {
+		return "", err
+	}
+
 	switch parts.Version {
 	case TCBStructVersion1:
 		return fmt.Sprintf("%s/cert?blSPL=%d&teeSPL=%d&snpSPL=%d&ucodeSPL=%d&fmcSPL=%d",
@@ -644,18 +720,26 @@ func VLEKCertURL(productLine string, tcb TCBVersion) string {
 			parts.SnpSpl,
 			parts.UcodeSpl,
 			parts.FmcSpl,
-		)
+		), nil
 	default:
 		return fmt.Sprintf("%s/cert?blSPL=%d&teeSPL=%d&snpSPL=%d&ucodeSPL=%d",
 			productBaseURL(abi.VlekReportSigner, productLine),
 			parts.BlSpl,
 			parts.TeeSpl,
 			parts.SnpSpl,
 			parts.UcodeSpl,
-		)
+		), nil
 	}
 }
 
+// VLEKCertURL returns the GET URL for retrieving a VLEK certificate, but without the necessary
+// CSP secret in the HTTP headers that makes the request validate to the KDS.
+// Deprecated: use VLEKCertQuery instead
+func VLEKCertURL(productLine string, tcb TCBVersion) string {
+	url, _ := VLEKCertQuery(productLine, TCBVersionStructFromTCBVersion(tcb))
+	return url
+}
+
 // VCEKCert represents the attestation report components represented in a KDS VCEK certificate
 // request URL.
 type VCEKCert struct {
@@ -788,7 +872,7 @@ func parseTCBURL(u *url.URL, tcbVersion uint8) (uint64, error) {
 			setter(uint8(number))
 		}
 	}
-	tcb, err := ComposeTCBParts(parts)
+	tcb, err := ComposeTCBPartsToTCBVersionStruct(parts)
 	if err != nil {
 		return 0, fmt.Errorf("invalid AMD KDS TCB arguments: %v", err)
 	}

kds/kds_test.go

@@ -1,4 +1,4 @@
-// Copyright 2022-2025 Google LLC
+// Copyright 2022 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -40,7 +40,7 @@ func TestVCEKCertURL(t *testing.T) {
 	hwid := make([]byte, abi.ChipIDSize)
 	hwid[0] = 0xfe
 	hwid[abi.ChipIDSize-1] = 0xc0
-	got := VCEKCertURL("Milan", hwid, TCBVersion{Version: 0, TCB: 0})
+	got := VCEKCertURL("Milan", hwid, TCBVersion(0))
 	want := "https://kdsintf.amd.com/vcek/v1/Milan/fe0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000c0?blSPL=0&teeSPL=0&snpSPL=0&ucodeSPL=0"
 	if got != want {
 		t.Errorf("VCEKCertURL(\"Milan\", %v, 0) = %q, want %q", hwid, got, want)
@@ -139,7 +139,7 @@ func TestParseVCEKCertURL(t *testing.T) {
 	}{
 		{
 			name: "happy path",
-			url:  VCEKCertURL("Milan", hwid, TCBVersion{Version: 0, TCB: 0}),
+			url:  VCEKCertURL("Milan", hwid, TCBVersion(0)),
 			want: func() VCEKCert {
 				c := VCEKCertProduct("Milan")
 				c.HWID = hwid

testing/fakekds.go

@@ -1,4 +1,4 @@
-// Copyright 2022-2025 Google LLC
+// Copyright 2022 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -120,7 +120,7 @@ func FakeKDSFromSigner(signer *AmdSigner) (*FakeKDS, error) {
 		{
 			ChipId: signer.HWID[:],
 			TcbCerts: map[uint64][]byte{
-				signer.TCB.TCB: signer.Vcek.Raw,
+				uint64(signer.TCB): signer.Vcek.Raw,
 			},
 			Fms: abi.MaskedCpuid1EaxFromSevProduct(signer.Product),
 		},

tools/lib/report/report.go

@@ -122,7 +122,7 @@ func asBin(report *spb.Attestation) ([]byte, error) {
 }
 
 func tcbBreakdown(tcbVersion uint8, tcb uint64) string {
-	parts := kds.DecomposeTCBVersion(kds.TCBVersion{Version: tcbVersion, TCB: tcb})
+	parts, _ := kds.DecomposeTCBVersionStruct(kds.TCBVersionStruct{Version: tcbVersion, TCB: tcb})
 	switch tcbVersion {
 	case kds.TCBStructVersion1:
 		return fmt.Sprintf("0x%x:{ucode: %d, snp: %d, tee: %d, bl: %d, fmc: %d}",

validate/validate.go

@@ -240,6 +240,16 @@ func PolicyToOptions(policy *cpb.Policy) (*Options, error) {
 		return nil, fmt.Errorf("unknown product %q", policy.Product.Name)
 	}
 
+	minTCBParts, err := kds.DecomposeTCBVersionStruct(kds.TCBVersionStruct{Version: tcbVersion, TCB: policy.GetMinimumTcb()})
+	if err != nil {
+		return nil, err
+	}
+
+	minLaunchTCBParts, err := kds.DecomposeTCBVersionStruct(kds.TCBVersionStruct{Version: tcbVersion, TCB: policy.GetMinimumLaunchTcb()})
+	if err != nil {
+		return nil, err
+	}
+
 	opts := &Options{
 		MinimumGuestSvn:           policy.GetMinimumGuestSvn(),
 		GuestPolicy:               guestPolicy,
@@ -252,8 +262,8 @@ func PolicyToOptions(policy *cpb.Policy) (*Options, error) {
 		HostData:                  policy.GetHostData(),
 		ReportData:                policy.GetReportData(),
 		PlatformInfo:              platformInfo,
-		MinimumTCB:                kds.DecomposeTCBVersion(kds.TCBVersion{Version: tcbVersion, TCB: policy.GetMinimumTcb()}),
-		MinimumLaunchTCB:          kds.DecomposeTCBVersion(kds.TCBVersion{Version: tcbVersion, TCB: policy.GetMinimumLaunchTcb()}),
+		MinimumTCB:                minTCBParts,
+		MinimumLaunchTCB:          minLaunchTCBParts,
 		MinimumBuild:              uint8(policy.GetMinimumBuild()),
 		MinimumVersion:            minVersion,
 		RequireAuthorKey:          policy.GetRequireAuthorKey(),
@@ -372,32 +382,39 @@ type reportTcbDescriptions struct {
 	cert partDescription
 }
 
-func getReportTcbs(report *spb.Report, certTcb kds.TCBVersion) *reportTcbDescriptions {
+func getReportTcbs(report *spb.Report, certTcb kds.TCBVersionStruct) *reportTcbDescriptions {
 	fms := report.GetCpuid1EaxFms()
 	tcbVersion, err := kds.ProductLineToTCBVersion(kds.ProductLineFromFms(fms))
 	if err != nil {
 		fmt.Printf("error: defaulting to TCB version 0. failed to findTCB version %v", err)
 		tcbVersion = kds.TCBStructVersion0
 	}
+
+	reportedTCBParts, _ := kds.DecomposeTCBVersionStruct(kds.TCBVersionStruct{Version: tcbVersion, TCB: report.GetReportedTcb()})
+	currentTCBParts, _ := kds.DecomposeTCBVersionStruct(kds.TCBVersionStruct{Version: tcbVersion, TCB: report.GetCurrentTcb()})
+	committedTCBParts, _ := kds.DecomposeTCBVersionStruct(kds.TCBVersionStruct{Version: tcbVersion, TCB: report.GetCommittedTcb()})
+	launchTCBParts, _ := kds.DecomposeTCBVersionStruct(kds.TCBVersionStruct{Version: tcbVersion, TCB: report.GetLaunchTcb()})
+	certTCBParts, _ := kds.DecomposeTCBVersionStruct(certTcb)
+
 	return &reportTcbDescriptions{
 		reported: partDescription{
-			parts: kds.DecomposeTCBVersion(kds.TCBVersion{Version: tcbVersion, TCB: report.GetReportedTcb()}),
+			parts: reportedTCBParts,
 			desc:  "report's REPORTED_TCB",
 		},
 		current: partDescription{
-			parts: kds.DecomposeTCBVersion(kds.TCBVersion{Version: tcbVersion, TCB: report.GetCurrentTcb()}),
+			parts: currentTCBParts,
 			desc:  "report's CURRENT_TCB",
 		},
 		committed: partDescription{
-			parts: kds.DecomposeTCBVersion(kds.TCBVersion{Version: tcbVersion, TCB: report.GetCommittedTcb()}),
+			parts: committedTCBParts,
 			desc:  "report's COMMITTED_TCB",
 		},
 		launch: partDescription{
-			parts: kds.DecomposeTCBVersion(kds.TCBVersion{Version: tcbVersion, TCB: report.GetLaunchTcb()}),
+			parts: launchTCBParts,
 			desc:  "report's LAUNCH_TCB",
 		},
 		cert: partDescription{
-			parts: kds.DecomposeTCBVersion(certTcb),
+			parts: certTCBParts,
 			desc:  "TCB of the V[CL]EK certificate",
 		},
 	}
@@ -426,8 +443,8 @@ func getPolicyTcbs(options *Options) *policyTcbDescriptions {
 
 // tcbNeError return an error if the two TCBs are not equal
 func tcbNeError(left, right partDescription) error {
-	ltcb, _ := kds.ComposeTCBParts(left.parts)
-	rtcb, _ := kds.ComposeTCBParts(right.parts)
+	ltcb, _ := kds.ComposeTCBPartsToTCBVersionStruct(left.parts)
+	rtcb, _ := kds.ComposeTCBPartsToTCBVersionStruct(right.parts)
 	if ltcb == rtcb {
 		return nil
 	}
@@ -447,7 +464,7 @@ func tcbGtError(wantLower, wantHigher partDescription) error {
 // validateTcb returns an error if the TCB values present in the report and V[CL]EK certificate do not
 // obey expected relationships with respect to the given validation policy, or with respect to
 // internal consistency checks.
-func validateTcb(report *spb.Report, certTcb kds.TCBVersion, options *Options) error {
+func validateTcb(report *spb.Report, certTcb kds.TCBVersionStruct, options *Options) error {
 	reportTcbs := getReportTcbs(report, certTcb)
 	policyTcbs := getPolicyTcbs(options)
 
@@ -730,7 +747,7 @@ func SnpAttestation(attestation *spb.Attestation, options *Options) error {
 	if err := multierr.Combine(
 		validatePolicy(report.GetPolicy(), options.GuestPolicy),
 		validateVerbatimFields(report, options),
-		validateTcb(report, exts.TCBVersion, options),
+		validateTcb(report, exts.TCBVersionStruct, options),
 		validateVersion(report, options),
 		validatePlatformInfo(report.GetPlatformInfo(), options.PlatformInfo),
 		validateKeys(report, options)); err != nil {