Skip to content

Add vTPM specification #920

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 2 commits into from
Closed

Add vTPM specification #920

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
32f2dc9
Add vTPM specification
stefanberger Jul 6, 2020
4621d9a
Add Devpath to LinuxDevice for different dev path on host and container
stefanberger Jul 6, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 30 additions & 0 deletions config-linux.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -387,6 +387,36 @@ The following parameters can be specified to set up the controller:
}
```

### <a name="configLinuxVTPMs" />vTPMs

**`vtpms`** (array of objects, OPTIONAL) lists a number of emulated TPMs that will be made available to the container.

Each entry has the following structure:

* **`statePath`** *(string, REQUIRED)* - Unique path where vTPM writes its state into.
* **`statePathIsManaged`** *(string, OPTIONAL)* - Whether runc is allowed to delete the TPM's state path upon destroying the TPM, defaults to false.
* **`vtpmVersion`** *(string, OPTIONAL)* - The version of TPM to emulate, either 1.2 or 2, defaults to 1.2.
* **`createCerts`** *(boolean, OPTIONAL)* - If true then create certificates for the vTPM, defaults to false.
* **`runAs`** *(string, OPTIONAL)* - Under which user to run the vTPM, e.g. 'tss'.
Copy link
Contributor

@mrunalp mrunalp Aug 6, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does it make sense to run this as the container user or it is typically set to a separate tss user?

* **`pcrBanks`** *(string, OPTIONAL)* - Comma-separated list of PCR banks to activate, default depends on `swtpm`.
* **`encryptionPassword`** *(string, OPTIONAL)* - Write state encrypted with a key derived from the password, defaults to not encrypted.

#### Example

```json
"vtpms": [
{
"statePath": "/var/lib/runc/myvtpm1",
"statePathIsManaged": false,
"vtpmVersion": "2",
"createCerts": false,
"runAs": "tss",
"pcrBanks": "sha1,sha512",
"encryptionPassword": "mysecret"
}
]
```

### <a name="configLinuxHugePageLimits" />Huge page limits

**`hugepageLimits`** (array of objects, OPTIONAL) represents the `hugetlb` controller which allows to limit the
Expand Down
11 changes: 10 additions & 1 deletion config.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -886,7 +886,16 @@ Here is a full example `config.json` for reference.
"rate": 300
}
]
}
},
"vtpms": [
{
"statePath": "/var/lib/runc/myvtpm1",
"vtpmVersion": "2",
"createCerts": false,
"runAs": "tss",
"pcrBanks": "sha1,sha512"
}
]
},
"rootfsPropagation": "slave",
"seccomp": {
Expand Down
6 changes: 6 additions & 0 deletions schema/config-linux.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,12 @@
"$ref": "defs-linux.json#/definitions/DeviceCgroup"
}
},
"vtpms" : {
"type": "array",
"items": {
"$ref": "defs-linux.json#/definitions/VTPM"
}
},
"pids": {
"type": "object",
"properties": {
Expand Down
37 changes: 37 additions & 0 deletions schema/defs-linux.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -140,6 +140,14 @@
"description": "minor device number",
"$ref": "defs.json#/definitions/int64"
},
"TPMVersion": {
"description": "The TPM version",
"type": "string",
"enum": [
"1.2",
"2"
]
},
"FileMode": {
"description": "File permissions mode (typically an octal value)",
"type": "integer",
Expand Down Expand Up @@ -233,6 +241,35 @@
}
]
},
"VTPM" : {
"type": "object",
"properties" : {
"statePath": {
"type": "string"
},
"statePathIsManaged": {
"type": "boolean"
},
"vtpmVersion": {
"$ref": "#/definitions/TPMVersion"
},
"createCerts": {
"type": "boolean"
},
"runAs": {
"type": "string"
},
"pcrBanks": {
"type": "string"
},
"encryptionPassword": {
"type": "string"
}
},
"required": [
"statePath"
]
},
"DeviceCgroup": {
"type": "object",
"properties": {
Expand Down
20 changes: 19 additions & 1 deletion schema/test/config/good/spec-example.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -330,7 +330,25 @@
"rate": 300
}
]
}
},
"vtpms": [
{
"statePath": "/var/lib/runc/myvtpm1",
"vtpmVersion": "2",
"createCerts": false,
"runAs": "tss",
"pcrBanks": "sha1,sha512"
},
{
"statePath": "/var/lib/runc/myvtpm2",
"statePathIsManaged": true,
"vtpmVersion": "1.2",
"createCerts": true,
"runAs": "root",
"pcrBanks": "sha1,sha512",
"encryptionPassword": "mysecret"
}
]
},
"rootfsPropagation": "slave",
"seccomp": {
Expand Down
22 changes: 22 additions & 0 deletions specs-go/config.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -352,6 +352,24 @@ type LinuxRdma struct {
HcaObjects *uint32 `json:"hcaObjects,omitempty"`
}

// LinuxVTPM for vTPM definition
type LinuxVTPM struct {
// Path on host where vTPM writes state to
StatePath string `json:"statePath,omitempty"`
// Whether runc is allowed to delete the 'Statepath' once the TPM is destroyed
StatePathIsManaged bool `json:"statePathIsManaged,omitempty"`
// Version of the TPM that is emulated
TPMVersion string `json:"vtpmVersion,omitempty"`
// Whether to create certificates upon first start of vTPM
CreateCertificates bool `json:"createCerts,omitempty"`
// The PCR banks to enable
PcrBanks string `json:"pcrBanks,omitempty"`
// Under what user to run the vTPM process
RunAs string `json:"runAs,omitempty"`
// The password to derive the encryption key from
EncryptionPassword string `json:"encryptionPassword,omitempty"`
}

// LinuxResources has container runtime resource constraints
type LinuxResources struct {
// Devices configures the device whitelist.
Expand All @@ -372,12 +390,16 @@ type LinuxResources struct {
// Limits are a set of key value pairs that define RDMA resource limits,
// where the key is device name and value is resource limits.
Rdma map[string]LinuxRdma `json:"rdma,omitempty"`
// VTPM configuration
VTPMs []LinuxVTPM `json:"vtpms,omitempty"`
}

// LinuxDevice represents the mknod information for a Linux special device file
type LinuxDevice struct {
// Path to the device.
Path string `json:"path"`
// Path of passed-through device on host
Devpath string `json:"devpath"`
Copy link
Contributor

@mrunalp mrunalp Jul 22, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What is this needed for?

Copy link
Author

@stefanberger stefanberger Jul 22, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So that /dev/tpm10 on the host can appear as /dev/tpm0 inside the container.

Copy link
Contributor

@mrunalp mrunalp Aug 6, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we need to know the host path or the entity creating the config.json can get the host device major / minor? For e.g. docker/podman have this feature:

sudo podman run --rm -it --device=/dev/null:/dev/mynull fedora:32 sh
sh-5.0# ls -l /dev/
total 0
crw--w----. 1 root tty  136, 0 Aug  6 21:35 console
lrwxrwxrwx. 1 root root     11 Aug  6 21:35 core -> /proc/kcore
lrwxrwxrwx. 1 root root     13 Aug  6 21:35 fd -> /proc/self/fd
crw-rw-rw-. 1 root root   1, 7 Aug  6 21:35 full
drwxrwxrwt. 2 root root     40 Aug  6 21:35 mqueue
crw-rw-rw-. 1 root root   1, 3 Aug  6 21:35 mynull
crw-rw-rw-. 1 root root   1, 3 Aug  6 21:35 null
lrwxrwxrwx. 1 root root      8 Aug  6 21:35 ptmx -> pts/ptmx
drwxr-xr-x. 2 root root      0 Aug  6 21:35 pts
crw-rw-rw-. 1 root root   1, 8 Aug  6 21:35 random
drwxrwxrwt. 2 root root     40 Aug  6 21:35 shm
lrwxrwxrwx. 1 root root     15 Aug  6 21:35 stderr -> /proc/self/fd/2
lrwxrwxrwx. 1 root root     15 Aug  6 21:35 stdin -> /proc/self/fd/0
lrwxrwxrwx. 1 root root     15 Aug  6 21:35 stdout -> /proc/self/fd/1
crw-rw-rw-. 1 root root   5, 0 Aug  6 21:35 tty
crw-rw-rw-. 1 root root   1, 9 Aug  6 21:35 urandom
crw-rw-rw-. 1 root root   1, 5 Aug  6 21:35 zero
sh-5.0#

The config.json snippet for this:

 "devices": [
      {
        "path": "/dev/mynull",
        "type": "c",
        "major": 1,
        "minor": 3,
        "fileMode": 8630,
        "uid": 0,
        "gid": 0
      }
    ],

// Device type, block, char, etc.
Type string `json:"type"`
// Major is the device's major number.
Expand Down