abi

package
v0.0.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 21, 2025 License: Apache-2.0 Imports: 14 Imported by: 0

Documentation

Overview

Package abi encapsulates types and status codes from the AMD-SP (AKA PSP) device.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at 

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Index

Constants

View Source 
const (
	// AeadAes256Gcm is the SNP API value for the AES-256-GCM encryption algorithm.
	AeadAes256Gcm = 1

	// SignEcdsaP384Sha384 is the SNP API value for the ECC+SHA signing algorithm.
	SignEcdsaP384Sha384 = 1

	// EccP384 is the SNP API value for the P-384 ECC curve identifier.
	EccP384 = 2

	// ReportSize is the ABI-specified byte size of an SEV-SNP attestation report.
	ReportSize = 0x4A0

	// FamilyIDSize is the field size of FAMILY_ID in an SEV-SNP attestation report.
	FamilyIDSize = 16
	// ImageIDSize is the field size of IMAGE_ID in an SEV-SNP attestation report.
	ImageIDSize = 16
	// ReportDataSize is the field size of REPORT_DATA in an SEV-SNP attestation report.
	ReportDataSize = 64
	// MeasurementSize is the field size of MEASUREMENT in an SEV-SNP attestation report.
	MeasurementSize = 48
	// HostDataSize is the field size of HOST_DATA in an SEV-SNP attestation report.
	HostDataSize = 32
	// IDKeyDigestSize is the field size of ID_KEY_DIGEST in an SEV-SNP attestation report.
	IDKeyDigestSize = 48
	// AuthorKeyDigestSize is the field size of AUTHOR_KEY_DIGEST in an SEV-SNP attestation report.
	AuthorKeyDigestSize = 48
	// ReportIDSize is the field size of REPORT_ID in an SEV-SNP attestation report.
	ReportIDSize = 32
	// ReportIDMASize is the field size of REPORT_ID_MA in an SEV-SNP attestation report.
	ReportIDMASize = 32
	// ChipIDSize is the field size of CHIP_ID in an SEV-SNP attestation report.
	ChipIDSize = 64
	// SignatureSize is the field size of SIGNATURE in an SEV-SNP attestation report.
	SignatureSize = 512

	// EcdsaP384Sha384SignatureSize is the length in bytes of the ECDSA-P384-SHA384 signature format.
	EcdsaP384Sha384SignatureSize = ecdsaRSsize + ecdsaRSsize
	// EcsdaPublicKeySize is the length in bytes of the Curve, QX, QY elliptic curve public key
	// representation in the AMD SEV ABI.
	EcsdaPublicKeySize = 0x404

	// CertTableEntrySize is the ABI size of the certificate table entry struct.
	CertTableEntrySize = 24

	// GUIDSize is the byte length of a GUID's binary representation.
	GUIDSize = 16

	// VcekGUID is the Versioned Chip Endorsement Key GUID
	VcekGUID = "63da758d-e664-4564-adc5-f4b93be8accd"
	// VlekGUID is the Versioned Loaded Endorsement Key GUID
	VlekGUID = "a8074bc2-a25a-483e-aae6-39c045a0b8a1"
	// AskGUID is the AMD signing Key GUID. Used for the ASVK as well.
	AskGUID = "4ab7b379-bbac-4fe4-a02f-05aef327c782"
	// ArkGUID is the AMD Root Key GUID
	ArkGUID = "c0b406a4-a803-4952-9743-3fb6014cd0ae"
	// AsvkGUID may not be defined, but we'd like it to be, so that
	// a single machine can use both VCEK and VLEK report signing.
	AsvkGUID = "00000000-0000-0000-0000-000000000000"

	// ExtraPlatformInfoGUID represents more information about the machine collecting an attestation
	// report than just the report to help interpret the attestation report.
	ExtraPlatformInfoGUID = "ecae0c0f-9502-43b1-afa2-0ae2e0d565b6"
	// ExtraPlatformInfoV0Size is the minimum size for an ExtraPlatformInfo blob.
	ExtraPlatformInfoV0Size = 8

	// CpuidProductMask keeps only the SevProduct-relevant bits from the CPUID(1).EAX result.
	CpuidProductMask = 0x0fff0fff

	// ReportVersion2 is set by the SNP API specification
	// https://web.archive.org/web/20231222054111if_/http://www.amd.com/content/dam/amd/en/documents/epyc-technical-docs/specifications/56860.pdf
	ReportVersion2 = 2
	// MinSupportedReportVersion is the lowest attestation report version that this library supports.
	MinSupportedReportVersion = 2

	// ReportVersion3 is set by the SNP API specification
	// https://www.amd.com/system/files/TechDocs/56860.pdf
	ReportVersion3 = 3
	// MaxSupportedReportVersion is the highest attestation report version that this library supports.
	MaxSupportedReportVersion = 5
)
View Source 
const (
	// Success denotes successful completion of a firmware command.
	Success SevFirmwareStatus = 0
	// InvalidPlatformState is the code for the platform to be in the wrong state for a given command.
	InvalidPlatformState = 1
	// InvalidGuestState is the code for the guest to be in the wrong state for a given command.
	InvalidGuestState = 2
	// Platform owner error unexpected by guest command.
	// invalidConfig = 3
	// InvalidLength is the code for a provided buffer size is too small to complete the command.
	InvalidLength = 4
	// Platform owner error unexpected by guest command.
	// alreadyOwned = 5
	// Platform owner error unexpected by guest command.
	// invalidCertificate = 6
	// PolicyFailure is the code for when the guest policy disallows the command.
	PolicyFailure = 7
	// Inactive is the code for when a command is sent for a guest, but the guest is inactive.
	Inactive = 8
	// InvalidAddress is the code for when a provided address is invalid.
	InvalidAddress = 9
	// User error expected at launch, unexpected here.
	// badSignature = 10
	// User error expected at launch, unexpected here.
	// badMeasurement = 11
	// Kernel error, unexpected.
	// asidOwned = 12
	// Kernel error, unexpected.
	// invalidAsid = 13
	// Kernel error, unexpected.
	// wbinvdRequired = 14
	// Kernel error, unexpected.
	// dfFlushRequired = 15
	// Kernel error, unexpected.
	// invalidGuest = 16
	// InvalidCommand is the code for when the command code is invalid.
	InvalidCommand = 17
	// Kernel error, unexpected.
	// active = 18
	// HwErrorPlatform is the code for when the hardware failed but it's okay to update its buffers.
	HwErrorPlatform = 19
	// HwErrorUnsafe is the code for when the hardware failed and it's unsafe to update its buffers.
	HwErrorUnsafe = 20
	// Unsupported is for an unsupported feature.
	Unsupported = 21
	// InvalidParam is the code for an invalid parameter in a command.
	InvalidParam = 22
	// ResourceLimit is the code for when the firmware has reached a resource limit and can't complete the command.
	ResourceLimit = 23
	// SecureDataInvalid is the code for when a hardware integrity check has failed.
	SecureDataInvalid = 24
	// InvalidPageSize indicates an RMP error with the recorded page size.
	InvalidPageSize = 25
	// InvalidPageState indicates an RMP error with the recorded page state.
	InvalidPageState = 26
	// InvalidMdataEntry indicates an RMP error with the recorded metadata.
	InvalidMdataEntry = 27
	// InvalidPageOwner indicates an RMP error with ASID mismatch between accessors.
	InvalidPageOwner = 28
	// AeadOflow indicates that firmware memory capacity is reached in the AEAD cryptographic algorithm.
	AeadOflow = 29
)

Unexported errors are not expected to leave the kernel.

View Source 
const (
	GUID_HEADER_ENTRY_SIZE = 24
)

Variables

View Source 
var SERVICES_MANIFEST_GUID = uuid.MustParse("63849ebb-3d92-4670-a1ff-58f9c94b87bb")

GUID as specified in Table 12 of the SVSM specification

View Source 
var SVSM_ATTEST_VTPM_GUID = uuid.MustParse("c476f1eb-0123-45a5-9641-b4e7dde5bfe3")

vTPM service attestation GUID found in Section 8.3.1 of the SVSM specification

Functions

func AmdBigInt 

func AmdBigInt(b []byte) *big.Int

AmdBigInt returns a given AMD format little endian big integer as a big.Int.

func ComposeSignerInfo 

func ComposeSignerInfo(signerInfo SignerInfo) uint32

ComposeSignerInfo returns the uint32 value expected to populate the attestation report byte range 0x48:0x4C.

func DefaultSevProduct 

func DefaultSevProduct() *pb.SevProduct

DefaultSevProduct returns the initial product version for a commercially available AMD SEV-SNP chip.

func EcdsaPublicKeyToBytes 

func EcdsaPublicKeyToBytes(key *ecdsa.PublicKey) ([]byte, error)

EcdsaPublicKeyToBytes returns the AMD SEV ABI format of the ECDSA P-384 curve public key.

func ExtendPlatformCertTable 

func ExtendPlatformCertTable(data []byte, info *ExtraPlatformInfo) ([]byte, error)

ExtendPlatformCertTable is a convenience function for parsing a CertTable, adding the ExtraPlatformInfoGUID entry, and returning the marshaled extended table.

func ExtendedPlatformCertTable 

func ExtendedPlatformCertTable(data []byte) ([]byte, error)

ExtendedPlatformCertTable is a convenience function for parsing a CertTable, adding the ExtraPlatformInfoGUID entry, and returning the marshaled extended table.

func FmsFromCpuid1Eax 

func FmsFromCpuid1Eax(eax uint32) (byte, byte, byte)

FmsFromCpuid1Eax returns the family, model, stepping (FMS) values extracted from a CPUID_1_EAX value.

func FmsToCpuid1Eax 

func FmsToCpuid1Eax(family, model, stepping byte) uint32

FmsToCpuid1Eax returns the masked CPUID_1_EAX value that represents the given family, model, stepping (FMS) values.

func LittleEndianToUUID added in v0.0.1 

func LittleEndianToUUID(data []byte) (uuid.UUID, error)

func MaskedCpuid1EaxFromSevProduct 

func MaskedCpuid1EaxFromSevProduct(product *pb.SevProduct) uint32

MaskedCpuid1EaxFromSevProduct returns the Cpuid1Eax value expected from the given product when masked with CpuidProductMask.

func ReportCertsAndManifestToProto 

func ReportCertsAndManifestToProto(data []uint8) (*pb.Attestation, error)

func ReportCertsToProto 

func ReportCertsToProto(data []uint8) (*pb.Attestation, error)

ReportCertsToProto creates a pb.Attestation from the report and certificate table represented in data. The report is expected to take exactly abi.ReportSize bytes, followed by the certificate table.

func ReportSignerInfo 

func ReportSignerInfo(data []byte) (uint32, error)

ReportSignerInfo returns the signer info component of a SEV-SNP raw report.

func ReportToAbiBytes 

func ReportToAbiBytes(r *pb.Report) ([]byte, error)

ReportToAbiBytes translates the report back into its little-endian ABI format.

func ReportToProto 

func ReportToProto(data []uint8) (*pb.Report, error)

ReportToProto creates a pb.Report from the little-endian AMD SEV-SNP attestation report byte array in SEV SNP ABI format for ATTESTATION_REPORT.

func ReportToSignatureDER 

func ReportToSignatureDER(report []byte) ([]byte, error)

ReportToSignatureDER returns the signature component of an attestation report in DER format for use in x509 verification.

func SetSignature 

func SetSignature(r, s *big.Int, report []byte) error

SetSignature sets the signature component the SnpAttestationReport with the specified representation of the R, S components of an ECDSA signature. Useful for testing.

func SevProduct 

func SevProduct() *pb.SevProduct

SevProduct returns the SEV product enum for the CPU that runs this function. Ought to be called from the client, not the verifier.

func SevProductFromCpuid1Eax 

func SevProductFromCpuid1Eax(eax uint32) *pb.SevProduct

SevProductFromCpuid1Eax returns the SevProduct that is represented by cpuid(1).eax.

func SignatureAlgo 

func SignatureAlgo(report []byte) uint32

SignatureAlgo returns the SignatureAlgo field of a raw SEV-SNP attestation report.

func SignedComponent 

func SignedComponent(report []byte) []byte

SignedComponent returns the bytes of the SnpAttestationReport that are signed by the AMD-SP.

func SnpPolicyToBytes 

func SnpPolicyToBytes(policy SnpPolicy) uint64

SnpPolicyToBytes translates a structural representation of a valid SNP policy to its ABI format.

func UUIDToLittleEndian added in v0.0.1 

func UUIDToLittleEndian(u uuid.UUID) []byte

Helper functions for converting UUIDs to and from little-endian format.

func ValidateReportFormat 

func ValidateReportFormat(r []byte) error

ValidateReportFormat returns an error if the provided buffer violates structural expectations of attestation report data.

Types

type AskCert 

type AskCert struct {
	Version      uint32
	KeyID        uuid.UUID
	CertifyingID uuid.UUID // Equals KeyID if self-signed.
	KeyUsage     uint32    // Table 111: 00 == Root signing key, 0x13 == SEV signing key.
	PubExpSize   uint32    // Must be 2048 or 4096
	ModulusSize  uint32    // Must be 2048 or 4096
	PubExp       []byte
	Modulus      []byte
	Signature    []byte
}

AskCert is the SEV format for AMD signing key certificates.

func ParseAskCert 

func ParseAskCert(data []byte) (*AskCert, int, error)

ParseAskCert returns a struct representation of the AMD certificate format from a byte array.

type CertTable 

type CertTable struct {
	Entries []CertTableEntry
}

CertTable represents each (GUID, Blob) pair of certificates returned by an extended guest request.

func CertsFromProto 

func CertsFromProto(chain *pb.CertificateChain) *CertTable

CertsFromProto returns the CertTable represented in the given certificate chain.

func (*CertTable) GetByGUIDString 

func (c *CertTable) GetByGUIDString(guid string) ([]byte, error)

GetByGUIDString returns the raw bytes for a certificate that matches a key identified by the given GUID string.

func (*CertTable) GetSizeInBytes 

func (c *CertTable) GetSizeInBytes() uint32

func (*CertTable) Marshal 

func (c *CertTable) Marshal() []byte

Marshal returns the CertTable in its GUID Table ABI format.

func (*CertTable) Proto 

func (c *CertTable) Proto() *pb.CertificateChain

Proto returns the certificate chain represented in an extended guest request's data pages. The GHCB specification allows any number of entries in the pages, so missing certificates aren't an error. If certificates are missing, you can choose to fetch them yourself by calling verify.GetAttestationFromReport.

func (*CertTable) Unmarshal 

func (c *CertTable) Unmarshal(certs []byte) error

Unmarshal populates the certTable with the (GUID, Blob) pairs represented in the given bytes. The format of the bytes is specified by the SEV SNP API for extended guest requests.

type CertTableEntry 

type CertTableEntry struct {
	GUID    uuid.UUID
	RawCert []byte
}

CertTableEntry represents both the GUID and whole Certificate contents denoted by the CertTableHeaderEntry ABI struct.

type CertTableHeaderEntry 

type CertTableHeaderEntry struct {
	// GUID is one of VcekGUID, AskGUID, or ArkGUID to identify which key an offset/length corresponds
	// to.
	GUID uuid.UUID
	// Offset is the offset into the data pages passed to the extended get_report where the specified
	// key's certificate resides.
	Offset uint32
	// Length is the length of the certificate within the data pages.
	Length uint32
}

CertTableHeaderEntry defines an entry of the beginning of an extended attestation report which points to a specific key's certificate.

func ParseSnpCertTableHeader 

func ParseSnpCertTableHeader(certs []byte) ([]CertTableHeaderEntry, error)

ParseSnpCertTableHeader interprets the data pages from an extended guest request for certificate information.

func (*CertTableHeaderEntry) Unmarshal 

func (h *CertTableHeaderEntry) Unmarshal(data []byte) error

Unmarshal populates a CertTableHeaderEntry from its ABI representation.

func (*CertTableHeaderEntry) Write 

func (h *CertTableHeaderEntry) Write(data []byte) error

Write writes a CertTableHeaderEntry in its ABI representation to data.

type ExtraPlatformInfo 

type ExtraPlatformInfo struct {
	Size      uint32 // Size doubles as Version, following the Linux ABI expansion methodology.
	Cpuid1Eax uint32 // Provides product information
}

ExtraPlatformInfo represents environment information needed to interpret an attestation report when the VCEK certificate is not available in the auxblob.

func MakeExtraPlatformInfo 

func MakeExtraPlatformInfo() *ExtraPlatformInfo

MakeExtraPlatformInfo returns the representation of platform info needed on top of what an attestation report provides in order to interpret it with the help of the AMD KDS.

func ParseExtraPlatformInfo 

func ParseExtraPlatformInfo(data []byte) (*ExtraPlatformInfo, error)

ParseExtraPlatformInfo extracts an ExtraPlatformInfo from a blob if it matches expectations, or errors.

func (*ExtraPlatformInfo) Marshal 

func (i *ExtraPlatformInfo) Marshal() ([]byte, error)

Marshal returns ExtraPlatformInfo in its ABI format or errors.

type ReportSigner 

type ReportSigner uint8

ReportSigner represents which kind of key is expected to have signed the attestation report 

const (
	// VcekReportSigner is the SIGNING_KEY value for if the VCEK signed the attestation report.
	VcekReportSigner ReportSigner = iota
	// VlekReportSigner is the SIGNING_KEY value for if the VLEK signed the attestation report.
	VlekReportSigner

	// NoneReportSigner is the SIGNING_KEY value for if the attestation report is not signed.
	NoneReportSigner
)

func (ReportSigner) String 

func (k ReportSigner) String() string

String returns a ReportSigner string rendering.

type ServiceEntry added in v0.0.1 

type ServiceEntry struct {
	GUID uuid.UUID
	Data []byte
}

type ServicesManifest added in v0.0.1 

type ServicesManifest struct {
	Entries []ServiceEntry
}

ServicesManifest represents the services manifest table, as defined in Section 7.1, table 12 of the Secure VM Service Module for SEV-SNP Guests specification: https://www.amd.com/content/dam/amd/en/documents/epyc-technical-docs/specifications/58019.pdf

func ServicesManifestFromProto added in v0.0.1 

func ServicesManifestFromProto(servicesManifest *pb.ServicesManifest) (*ServicesManifest, error)

func (*ServicesManifest) GetEntry added in v0.0.1 

func (t *ServicesManifest) GetEntry(guid uuid.UUID) (ServiceEntry, error)

func (*ServicesManifest) Marshal added in v0.0.1 

func (t *ServicesManifest) Marshal() ([]byte, error)

func (*ServicesManifest) Proto added in v0.0.1 

func (t *ServicesManifest) Proto() *pb.ServicesManifest

func (*ServicesManifest) Unmarshal added in v0.0.1 

func (t *ServicesManifest) Unmarshal(data []byte) error

type SevFirmwareErr 

type SevFirmwareErr struct {
	Status SevFirmwareStatus
}

SevFirmwareErr is an error that interprets firmware status codes from the AMD secure processor.

func (*SevFirmwareErr) Error 

func (e *SevFirmwareErr) Error() string

type SevFirmwareStatus 

type SevFirmwareStatus int64

SevFirmwareStatus is the type of all AMD-SP firmware status codes, as documented in the SEV API https://www.amd.com/system/files/TechDocs/55766_SEV-KM_API_Specification.pdf 

const GuestRequestInvalidLength SevFirmwareStatus = 0x100000000

GuestRequestInvalidLength is set by the ccp driver and not the AMD-SP when an guest extended request provides too few pages for the firmware to populate with data.

type SignerInfo 

type SignerInfo struct {
	// SigningKey represents kind of key by which a report was signed.
	SigningKey ReportSigner
	// MaskChipKey is true if the host chose to enable CHIP_ID masking, to cause the report's CHIP_ID
	// to be all zeros.
	MaskChipKey bool
	// AuthorKeyEn is true if the VM is launched with an IDBLOCK that includes an author key.
	AuthorKeyEn bool
}

SignerInfo represents information about the signing circumstances for the attestation report.

func ParseSignerInfo 

func ParseSignerInfo(signerInfo uint32) (result SignerInfo, err error)

ParseSignerInfo interprets report[0x48:0x4c] into its component pieces and errors on non-zero mbz fields.

type SnpPlatformInfo 

type SnpPlatformInfo struct {
	// SMTEnabled represents if the platform that produced the attestation report has SMT enabled.
	SMTEnabled bool
	// TSMEEnabled represents if the platform that produced the attestation report has transparent
	// secure memory encryption (TSME) enabled.
	TSMEEnabled bool
	// ECCEnabled indicates that the platform is using error correcting codes for memory.
	// Present when EccMemReporting feature bit is set.
	ECCEnabled bool
	// RAPLDisabled indicates that the RAPL is disabled.
	RAPLDisabled bool
	// CiphertextHidingDRAMEnabled indicates cypher text hiding is enabled for DRAM.
	CiphertextHidingDRAMEnabled bool
	// AliasCheckComplete indicates that alias detection has completed since the last system reset and there are no aliasing addresses.
	// Mitigation for https://badram.eu/, see https://www.amd.com/en/resources/product-security/bulletin/amd-sb-3015.html#mitigation.
	AliasCheckComplete bool
}

SnpPlatformInfo represents an interpretation of the PLATFORM_INFO field of an attestation report.

func ParseSnpPlatformInfo 

func ParseSnpPlatformInfo(platformInfo uint64) (SnpPlatformInfo, error)

ParseSnpPlatformInfo returns an interpretation of the given platform info, or an error for unrecognized bits.

type SnpPolicy 

type SnpPolicy struct {
	// ABIMajor is the minimum SEV SNP ABI version needed to run the guest's minor version number.
	ABIMinor uint8
	// ABIMajor is the minimum SEV SNP ABI version needed to run the guest's major version number.
	ABIMajor uint8
	// SMT is true if symmetric multithreading is allowed.
	SMT bool
	// MigrateMA is true if the guest is allowed to have a migration agent.
	MigrateMA bool
	// Debug is true if the VM can be decrypted by the host for debugging purposes.
	Debug bool
	// SingleSocket is true if the guest may only be active on a single socket.
	SingleSocket bool
	// CXLAllowed is true if CLX can be populated with devices or memory.
	CXLAllowed bool
	// MemAES256XTS is true if AES-256-XTS is required for memory encryption.
	// If false, either AES-128-XEX or AES-256-XTS is allowed.
	MemAES256XTS bool
	// RAPLDis is true if Running Average Power Limit (RAPL) must be disabled.
	RAPLDis bool
	// CipherTextHidingDRAM is true if ciphertext hiding for the DRAM must be enabled.
	CipherTextHidingDRAM bool
}

SnpPolicy represents the bitmask guest policy that governs the VM's behavior from launch.

func ParseSnpPolicy 

func ParseSnpPolicy(guestPolicy uint64) (SnpPolicy, error)

ParseSnpPolicy interprets the SEV SNP API's guest policy bitmask into an SnpPolicy struct type.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.