abi

Documentation

Overview

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

Index

• Constants
• func AmdBigInt(b []byte) *big.Int
• func ReportToAbiBytes(r *pb.Report) ([]byte, error)
• func ReportToProto(data []uint8) (*pb.Report, error)
• func ReportToSignatureDER(report []byte) ([]byte, error)
• func SetSignature(r, s *big.Int, report []byte) error
• func SignatureAlgo(report []byte) uint32
• func SignedComponent(report []byte) []byte
• func SnpPolicyToBytes(policy SnpPolicy) uint64
• func ValidateReportFormat(r []byte) error
• type AskCert
  • func ParseAskCert(data []byte) (*AskCert, int, error)
• type CertTableHeaderEntry
  • func ParseSnpCertTableHeader(certs []byte) ([]CertTableHeaderEntry, error)
  • func (h *CertTableHeaderEntry) Unmarshal(data []byte) error
  • func (h *CertTableHeaderEntry) Write(data []byte) error
• type SevFirmwareErr
  • func (e SevFirmwareErr) Error() string
• type SevFirmwareStatus
• type SnpPolicy
  • func ParseSnpPolicy(guestPolicy uint64) (SnpPolicy, error)

Constants

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

	// EcdsaP384Sha384SignatureSize is the length in bytes of the ECDSA-P384-SHA384 signature format.
	EcdsaP384Sha384SignatureSize = ecdsaRSsize + ecdsaRSsize

	// 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"
	// AskGUID is the AMD signing Key GUID
	AskGUID = "4ab7b379-bbac-4fe4-a02f-05aef327c782"
	// ArkGUID is the AMD Root Key GUID
	ArkGUID = "c0b406a4-a803-4952-9743-3fb6014cd0ae"

	// ExpectedReportVersion is set by the SNP API specification
	// https://www.amd.com/system/files/TechDocs/56860.pdf
	ExpectedReportVersion = 2
)

Functions

func AmdBigInt

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

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

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 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

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 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 SevFirmwareErr

type SevFirmwareErr struct {
	Status SevFirmwareStatus
	// contains filtered or unexported fields
}

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 int

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 (
	// Success denotes successful completion of a firmware command.
	Success SevFirmwareStatus = iota
	// InvalidPlatformState is the code for the platform to be in the wrong state for a given command.
	InvalidPlatformState
	// InvalidGuestState is the code for the guest to be in the wrong state for a given command.
	InvalidGuestState

	// InvalidLength is the code for a provided buffer size is too small to complete the command.
	InvalidLength

	// PolicyFailure is the code for when the guest policy disallows the command.
	PolicyFailure
	// Inactive is the code for when a command is sent for a guest, but the guest is inactive.
	Inactive
	// InvalidAddress is the code for when a provided address is invalid.
	InvalidAddress

	// InvalidCommand is the code for when the command code is invalid.
	InvalidCommand

	// HwErrorPlatform is the code for when the hardware failed but it's okay to update its buffers.
	HwErrorPlatform
	// HwErrorUnsafe is the code for when the hardware failed and it's unsafe to update its buffers.
	HwErrorUnsafe
	// Unsupported is for an unsupported feature.
	Unsupported
	// InvalidParam is the code for an invalid parameter in a command.
	InvalidParam
	// ResourceLimit is the code for when the firmware has reached a resource limit and can't complete the command.
	ResourceLimit
	// SecureDataInvalid is the code for when a hardware integrity check has failed.
	SecureDataInvalid
	// InvalidPageSize indicates an RMP error with the recorded page size.
	InvalidPageSize
	// InvalidPageState indicates an RMP error with the recorded page state.
	InvalidPageState
	// InvalidMdataEntry indicates an RMP error with the recorded metadata.
	InvalidMdataEntry
	// InvalidPageOwner indicates an RMP error with ASID mismatch between accessors.
	InvalidPageOwner
	// AeadOflow indicates that firmware memory capacity is reached in the AEAD cryptographic algorithm.
	AeadOflow
)

Unexported errors are not expected to leave the kernel.

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