Debian Codegraph @

tools/attest/README.md

raw
1 # `attest` CLI tool
2
3 This binary is a thin wrapper around the `client` library to gather attestation
4 reports in either AMD API format or in this module's `sevsnp` protobuf formats.
5
6 The tool's input is the intended `REPORT_DATA` contents, which is 64 bytes of
7 user-provided data to include in the attestation report. This is typically a
8 nonce.
9
10 The tool's output is the report in any specified format to either standard out
11 or directly to a file.
12
13 ## Example
14
15 ```
16 $ go run . -inform base64 -in \
17 SGVsbG8gU0VWLVNOUAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA== \
18 -out attestation.bin
19 ```
20
21 Or equivalently through stdin and default binary input format:
22
23 ```shell
24 $ echo \
25 “SGVsbG8gU0VWLVNOUAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA==” | \
26 base64 -d | go run . -out attestation.bin
27 ```
28
29 If the host does not provide cached certificates, passing --extended will return
30 empty certificates. It's still recommended to use --extended since the verification
31 logic won't change once the host provides cached certificates. The verification will
32 just not need to download them from the AMD Key Distribution Service (KDS).
33
34 ## Usage
35
36 ```
37 ./attest [options...]
38 ```
39
40 ### `-extended`
41
42 The flag requests that the tool uses the extended guest request to get both the
43 attestation report and the host-provided certificates. If `-outform` is `bin`,
44 then the output is the attestation report immediately followed by the
45 certificate table.
46
47 ### `-in`
48
49 This flag provides the `REPORT_DATA` content directly on the command line. The
50 contents will be interpreted by the value of the `-inform` flag. The `auto` inform
51 will default to expecting a hexadecimal string.
52
53 ### `-infile`
54
55 A path to a file that contains `REPORT_DATA` contents. May be `-` for standard
56 in. If neither `-in` nor `-infile` are specified, then the default input is
57 standard in. The `auto` inform will default to expecting binary.
58
59 ### `-inform`
60
61 The format that input takes. One of
62
63 * `bin`: for raw binary. Must have the expected number of bytes.
64 * `hex`: for a byte string encoded as a hexadecimal string. Fewer bytes than
65 expected will be zero-filled.
66 * `base64`: for a byte string in base64 encoding. Fewer bytes than expected
67 will be zero-filled.
68 * `auto`: has different meanings whether input is from a file or from a
69 command line argument.
70 + If from an argument, then defaults to expecting a hexadecimal string.
71 Will try base64 if hex decoding fails.
72 + If from a file, then defaults to expecting binary.
73
74 Default value is `auto`.
75
76 ### `-outform`
77
78 The format that output takes. This can be `bin` for AMD's specified structures
79 in binary, `proto` for this module's protobuf message types serialized to bytes,
80 or `textproto` for this module's protobuf message types in human readable text
81 format.
82
83 Default value is `bin`.
84
85 ### `-out`
86
87 Path to output file to write attestation report to.
88
89 Default is empty, interpreted as stdout.
90
91 ### `-vmpl`
92
93 The VMPL at which the attestation report should be collected at. Must be between
94 0 and 3.
95
96 Default value is 0.
97