search

google / go-sev-guest

go-sev-guest offers a library to wrap the /dev/sev-guest device in Linux, as well as a library for attestation verification of fundamental components of an attestation report.
Apache License 2.0
52 stars 19 forks source link

readme

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' certificates (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:

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:

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:

The fields that provide a minimum acceptable value are:

The fields that provide a maximum acceptable value are:

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.

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.