SEV Guest
This project offers libraries for a simple wrapper around the /dev/sev-guest
device in Linux, as well as a library for attestation verification of
fundamental components of an attestation report.
This project is split into two complementary roles. The first role is producing
an attestation report, and the second is checking an attestation report. The
client library produces reports, the verify library verifies reports'
signatures and key certificates, and the validate library checks non-signature
report fields against a user-provided policy.
client
This library should be used within the confidential workload to collect an attestation report along with requisite certificates.
Your main interactions with it will be to open the device, get an attestation report with your provided 64 bytes of user data (typically a nonce or a hash of a public key), and then close the device. For convenience, the attestation with its associated certificates can be collected in a wire-transmittable protocol buffer format.
func OpenDevice() (*LinuxDevice, error)
This function creates a file descriptor to the /dev/sev-guest device and
returns an object that has methods encapsulating commands to the device. When
done, remember to Close() the device.
func GetExtendedReport(d Device, reportData [64]byte) (*pb.Attestation, error)
This function takes an object implementing the Device interface (e.g., a
LinuxDevice) and returns the protocol buffer representation of the attestation
report and associated certificates. The report will be associated with VM
privilege level 0. You can provide a different privilege level as the third
argument to GetExtendedReportAtVmpl.
You can use GetRawExtendedReport or GetRawExtendedReportAtVmpl to get the
AMD SEV-SNP API formatted report and certificate table, or just GetReport,
GetReportAtVmpl, GetRawReport, or GetRawReportAtVmpl to avoid fetching the
certificate table.
func GetDerivedKeyAcknowledgingItsLimitations(d Device, request *SnpDerivedKeyReq) ([]byte, error)
This function uses the /dev/sev-guest command for requesting a key derived
from data that is measured at VM launch time, with the additional ability to
continue to generate the same key as at earlier TCB and GuestSVN values.
This function's name is selected to discourage its use in a Cloud setting. See LIMITATIONS.md.
func (d Device) Close() error
Closes the device.
func (d Device) Product() *spb.SevProduct
Returns a representation of CPU info relevant to the AMD SEV product version.
verify
This library will check the signature and basic well-formedness properties of an attestation report and certificate chain. The requirements for report well-formedness comes from the AMD SEV-SNP API specification, and the requirements for certificate well-formedness come from the AMD Key Distribution Service (KDS) specification.
This library embeds AMD's root and SEV intermediate keys (AMD source) for the KDS product_name=Milan cert_chain in the AMD SEV certificate format to cross check against any certificate chain that it's sent. The SEV certificate format is defined in an appendix of the AMD SEV API specification.
func SnpAttestation(attestation *spb.Attestation, options *Options) error
This function verifies that the attestation has a valid signature and certificate chain, and optionally checks the certificate revocation list (CRL). At time of writing, the CRL is empty. From discussions with AMD, we expect the CRL to never contain a VCEK or ARK, and only in a very rare circumstance contain the ASK (intermediate signing key). The default option is to not check the CRL.
Example expected invocation:
verify.SnpAttestation(myAttestation, verify.DefaultOptions())
Options type
This type contains three fields:
CheckRevocations bool: if true, thenSnpAttestationwill download the certificate revocation list (CRL) and check for revocations.Getter HTTPSGetter: must be non-nilifCheckRevocationsis true.TrustedRoots map[string][]*AMDRootCerts: ifnil, uses the library's embedded certificates. Maps a product name to all allowed root certifications for that product (e.g., Milan).
The HTTPSGetter interface consists of a single method Get(url string) ([]byte, error) that should return the body of the HTTPS response.
AMDRootCerts type
This type has 6 fields, the first 3 of which are mandatory:
Product string: the name of the product this bundle is for (e.g.,"Milan").AskX509 *x509.Certificate: an X.509 representation of the AMD SEV Signer intermediate key (ASK)'s certificate.ArkX509 *x509.Certificate: an X.509 representation of the AMD SEV Root key (ARK)'s certificate.AskSev *abi.AskCert: if non-nil, will cross-check withAskX509. Represents the information present in the AMD SEV certificate format for the ASK.ArkSev *abi.AskCert: if non-nil, will cross-check withArkX509. Represents the information present in the AMD SEV certificate format for the ARK.CRL *x509.RevocationList: the certificate revocation list signed by the ARK. Will be populated ifSnpAttestationis called withCheckRevocations: true.
validate
This library checks fields of an attestation report according to a policy
provided by the user. The policy is represented with the Options type, which
specifies which fields to check, what their exact values should be, or whether
the field should be within a given bound.
func SnpAttestation(attestation *spb.Attestation, options *Options) error
Not to be confused with verify.SnpAttestation for checking certificates and
signatures, the validate.SnpAttestation function is more open-ended about what
reports are acceptable. It's up to the user of the library to set the parameters
of acceptable values with the options argument.
The Option type
An instance of the Option type is a simple validation policy for non-signature
fields of an attestation report.
The fields that either can be skipped or must match the given value exactly are:
ReportDatafor theREPORT_DATAfieldHostDatafor theHOST_DATAfieldImageIDfor theIMAGE_IDfieldFamilyIDfor theFAMILY_IDfieldReportIDfor theFEPORT_IDfieldReportIDMAfor theREPORT_ID_MAfieldMeasurementfor theMEASUREMENTfield
The fields that provide a minimum acceptable value are:
MinimumBuildfor the minimum build number for the AMD secure processor firmware.RequireAuthorKeyfor whetherAUTHOR_KEY_ENcan be 0 or 1 (false), or just 1 (true).RequireIDBlockfor whether IDBlock fields can be anything (false) or must validate (true) against theTrustedfamily of options.
The fields that provide a maximum acceptable value are:
GuestPolicy: each true field ofGuestPolicyis permission for an attestation report'sPOLICYcorresponding bit to be set.PermitProvisionalFirmware: if false, the minimum TCB and API values are equal to the reported values. If true, the maximum TCB and API values are the reported values.PlatformInfo: each true field ofPlatformInfois permission for the attestation report'sPLATFORM_INFOcorresponding bit to be set.
Finally, the fields for trusting IDBlock signers. Both ID keys and Author keys
have x.509 certificate and SEV-SNP hash format inputs for usability. The x.509
certificates will be converted to their corresponding SEV-SNP API format and
appended to the corresponding KeyHashes array. Only certificates for ECSDA
P-384 public keys are considered. All other certificates are quietly ignored.
TrustedAuthorKeys: x.509 certificates for author keys that are trusted to endorse an attestation report. If the report's author key is trusted, then the identity key it signed is implicitly trusted.TrustedAuthorKeyHashes: An array of SHA-384 hashes of the SEV-SNP API format for an ECDSA public key. Has the same validation behavior asTrustedAuthorKeys.TrustedIDKeys: x.509 certificates for identity keys that are trusted to endorse an attestation report. If the report's identity key is explicitly trusted, then its author key does not need to be trusted.TrustedIDKeyHashes: An array of SHA-384 hashes of the SEV-SNP API format for an ECDSA public key. Has the same validation behavior asTrustedIDKeys.Product: A replacement or supplementalSevProductvalue to use for a given attestation or report. If nil, uses the information present in the attestation proto, or provides a defaultMilan-B0value.
License
go-sev-guest is released under the Apache 2.0 license.
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.
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.
Links
Disclaimers
This is not an officially supported Google product.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent