abi

package
v0.12.1 Latest Latest
Warning

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

 Go to latest Published: Dec 10, 2024 License: Apache-2.0 Imports: 11 Imported by: 18

Documentation

Overview

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

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

	// ReportVersion3 is set by the SNP API specification
	// https://www.amd.com/system/files/TechDocs/56860.pdf
	ReportVersion3 = 3
)
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.

Variables

This section is empty.

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 added in v0.8.0 

func ComposeSignerInfo(signerInfo SignerInfo) uint32

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

func DefaultSevProduct added in v0.7.1 

func DefaultSevProduct() *pb.SevProduct

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

func EcdsaPublicKeyToBytes added in v0.2.4 

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

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

func ExtendPlatformCertTable added in v0.11.0 

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 added in v0.11.0 

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 added in v0.12.0 

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

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

func FmsToCpuid1Eax added in v0.12.0 

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 MaskedCpuid1EaxFromSevProduct added in v0.11.0 

func MaskedCpuid1EaxFromSevProduct(product *pb.SevProduct) uint32

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

func ReportCertsToProto added in v0.10.0 

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 added in v0.8.0 

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 added in v0.7.1 

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 added in v0.11.0 

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 ValidateReportFormat added in v0.2.2 

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 added in v0.2.4 

type CertTable struct {
	Entries []CertTableEntry
}

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

func CertsFromProto added in v0.10.2 

func CertsFromProto(chain *pb.CertificateChain) *CertTable

CertsFromProto returns the CertTable represented in the given certificate chain.

func (*CertTable) GetByGUIDString added in v0.2.4 

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) Marshal added in v0.10.2 

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

Marshal returns the CertTable in its GUID table ABI format.

func (*CertTable) Proto added in v0.2.4 

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 added in v0.2.4 

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 added in v0.2.4 

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 added in v0.11.0 

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 added in v0.11.0 

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 added in v0.11.0 

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

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

func (*ExtraPlatformInfo) Marshal added in v0.11.0 

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

Marshal returns ExtraPlatformInfo in its ABI format or errors.

type ReportSigner added in v0.8.0 

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 added in v0.8.0 

func (k ReportSigner) String() string

String returns a ReportSigner string rendering.

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 added in v0.8.0 

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 added in v0.8.0 

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 added in v0.2.4 

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
}

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

func ParseSnpPlatformInfo added in v0.2.4 

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
}

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.