KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #typescript #developer-tools #claude-code #ai-agent #codex #deepseek-harness #ai-agents #cli #react #mcp

go-sev-guest

★ 77 Open GitHub ↗

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.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 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.It aligns with the AMD SEV-SNP
ABI specification up to Rev. 1.58.

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](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](https://download.amd.com/developer/eula/sev/ask_ark_milan.cert))
for the
[KDS product_name=Milan cert_chain](https://kdsintf.amd.com/vcek/v1/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, then `SnpAttestation` will download the
    certificate revocation list (CRL) and check for revocations.
*   `Getter HTTPSGetter`: must be non-`nil` if `CheckRevocations` is true.
*   `TrustedRoots map[string][]*AMDRootCerts`: if `nil`, 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 with
    `AskX509`. Represents the information present in the AMD SEV certificate
    format for the ASK.
*   `ArkSev *abi.AskCert`: if non-`nil`, will cross-check with
    `ArkX509`. 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 if `SnpAttestation` is called with `CheckRevocations: 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:

*   `ReportData` for the `REPORT_DATA` field
*   `HostData` for the `HOST_DATA` field
*   `ImageID` for the `IMAGE_ID` field
*   `FamilyID` for the `FAMILY_ID` field
*   `ReportID` for the `FEPORT_ID` field
*   `ReportIDMA` for the `REPORT_ID_MA` field
*   `Measurement` for the `MEASUREMENT` field

The fields that provide a minimum acceptable value are:

*   `MinimumBuild` for the minimum build number for the AMD secure processor
    firmware.
*   **`MinimumLaunchMitigationVector`**: A bitmask used to enforce a minimum set 
of **required security mitigations** present in the report's `LAUNCH_MIT_VECTOR`.
*   **`MinimumCurrentMitigationVector`**: A bitmask used to enforce a minimum set 
of **required security mitigations** present in the report's `CURRENT_MIT_VECTOR`.
*   `RequireAuthorKey` for whether `AUTHOR_KEY_EN` can be 0 or 1 (false), or
    just 1 (true).
*   `RequireIDBlock` for whether IDBlock fields can be anything (false) or must
    validate (true) against the `Trusted` family of options.

The fields that provide a maximum acceptable value are:

*   `GuestPolicy`: each true field of `GuestPolicy` is permission for an
    attestation report's `POLICY` corresponding 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 of `PlatformInfo` is permission for the
    attestation report's `PLATFORM_INFO` corresponding 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 as
    `TrustedAuthorKeys`.
*   `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 as
    `TrustedIDKeys`.
*   `Product`: A replacement or supplemental `SevProduct` value to use for
    a given attestation or report. If nil, uses the information present in
    the attestation proto, or provides a default `Milan-B0` value.

## License

go-sev-guest is released under the Apache 2.0 license.

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

*   [AMD SEV API specification](https://www.amd.com/system/files/TechDocs/55766_SEV-KM_API_Specification.pdf)
*   [AMD SEV-SNP API specification](https://www.amd.com/content/dam/amd/en/documents/developer/56860.pdf)
*   [AMD KDS specification](https://www.amd.com/system/files/TechDocs/57230.pdf)

## Disclaimers

This is not an officially supported Google product.

go-sev-guest

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README