1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
|
# go-configfs-tsm
This library wraps the configfs/tsm Linux subsystem for Trusted Security Module operations.
## `report` library
This library wraps the configfs/tsm/report subsystem for safely generating
attestation reports.
The TSM `report` subsystem provides a vendor-agnostic interface for collecting a
signed document for the Trusted Execution Environment's (TEE) state for remote
verification. For simplicity, we call this document an "attestation report",
though other sources may sometimes refer to it as a "quote".
Signing keys are expected to be rooted back to the manufacturer. Certificates
may be present in the `auxblob` attribute or as part of the report in `outblob`.
The core functionality of attestation report interaction is nonce in, report
out. For testability, we abstract the file operations that are needed for
creating configfs report entries, reading and writing attributes, and final
reclaiming of resources.
```golang
func Get(client configfsi.Client, req *report.Request) (*report.Response, error)
```
Where
```golang
type Request struct {
InBlob []byte
Privilege *Privilege
GetAuxBlob bool
}
type Response struct {
Provider string
OutBlob []byte
AuxBlob []byte
}
type Privilege struct {
Level int
}
```
The provider may not implement an `AuxBlob` delivery mechanism, so if
`GetAuxBlob` is true, then `AuxBlob` still must be checked for length 0.
### Errors
Since this is a file-based system, there's always a chance that an operation may
fail with a permission error. By default, the TSM system requires root access.
The host may also add rate limiting to requests, such that an outblob read fails
with `EBUSY`. The kernel may or may not try again on behalf of the user.
Finally, due to the fact that the TSM report system only requests an attestation
report when reading `outblob` or `auxblob`, there is a chance the input
attributes may have been changed to unexpected values from an interfering
process. This interference is a bug in user space that the kernel does not block
for simplicity. Interference is evident through the `generation` attribute. When
`generation` does not match the expectations that the `report` package tracks,
`report.Get` returns a `*report.GenerationErr` or an error that wraps
`*report.GenerationErr`.
Use `func GetGenerationErr(error) *GenerationErr` to extract a `*GenerationErr`
from an error if it is or contains a `*GenerationErr`. If present, the caller
should try to identify the source of interference and remove it. Meanwhile, the
caller may try again.
## `configfsi.Client` interface
Most users will only want to use the client from `linuxtsm.MakeClient`.
A client on real hardware is just the filesystem, since the configfs
interactions will interact with the hardware. In unit tests though, we can
emulate the behavior that has been proposed in v7 of the patch series
```golang
type Client interface {
MkdirTemp(dir, pattern string) (string, error)
ReadFile(name string) ([]byte, error)
WriteFile(name string, contents []byte) error
RemoveAll(path string) error
}
```
The `RemoveAll` function is the only oddly named method, since the real
interface would just `rmdir` the report directory
([`os.Remove`](https://pkg.go.dev/os#Remove) in Golang), even when there are
apparent files underneath. Non-empty directory removal is generally not allowed,
so the `RemoveAll` name is clearer with what it does.
## `linuxtsm` package
The `linuxtsm` package defines an implementation of `configfsi.Client` with
```golang
func MakeClient() (configfsi.Client, error)
```
For further convenience, `linuxtsm` provides an alias for `MakeClient` combined with `report.Get` as
```golang
func GetReport(req *report.Request) (*report.Response, error)
```
The usage is the same as for `report.Get`.
## `faketsm` package
The `faketsm.Client` implementation allows tests to provide custom behavior for subsystems by name:
```golang
type Client struct {
Subsystems map[string]configfsi.Client
}
```
The `faketsm.ReportSubsystem` type implements a client that emulates the
concurrent behavior and `generation` attribute semantics. To test negative
behavior as well, the subsystem allows the user to override `Mkdir`, `ReadFile`,
existing entries' values, and the error behavior of `WriteFile`.
## Disclaimer
This is not an officially supported Google product.
|
