From 151a0113911cb4f0883d161a11d619b9950044a9 Mon Sep 17 00:00:00 2001 From: Stefan Berger Date: Mon, 6 Jul 2020 13:51:27 -0400 Subject: [PATCH 1/2] Add vTPM specification Add the vTPM specification to the documentation, config.go, and schema description. The following is an example of a vTPM description that is found under the path /linux/resources/vtpms: "vtpms": [ { "statePath": "/var/lib/runc/myvtpm1", "vtpmVersion": "2", "createCerts": false, "runAs": "tss", "pcrBanks": "sha1,sha512" } ] Signed-off-by: Stefan Berger --- config-linux.md | 30 ++++++++++++++++++ config.md | 11 ++++++- schema/config-linux.json | 6 ++++ schema/defs-linux.json | 37 +++++++++++++++++++++++ schema/test/config/good/spec-example.json | 20 +++++++++++- specs-go/config.go | 20 ++++++++++++ 6 files changed, 122 insertions(+), 2 deletions(-) diff --git a/config-linux.md b/config-linux.md index 6553ccb7c..f5bcda5a3 100644 --- a/config-linux.md +++ b/config-linux.md @@ -585,6 +585,36 @@ The following parameters can be specified to set up the controller: } ``` +### 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'. +* **`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" + } + ] +``` + ### Huge page limits **`hugepageLimits`** (array of objects, OPTIONAL) represents the `hugetlb` controller which allows to limit the HugeTLB reservations (if supported) or usage (page fault). diff --git a/config.md b/config.md index d642359d1..7965b61df 100644 --- a/config.md +++ b/config.md @@ -1076,7 +1076,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": { diff --git a/schema/config-linux.json b/schema/config-linux.json index 778561d89..172c5446b 100644 --- a/schema/config-linux.json +++ b/schema/config-linux.json @@ -49,6 +49,12 @@ "$ref": "defs-linux.json#/definitions/DeviceCgroup" } }, + "vtpms" : { + "type": "array", + "items": { + "$ref": "defs-linux.json#/definitions/VTPM" + } + }, "pids": { "type": "object", "properties": { diff --git a/schema/defs-linux.json b/schema/defs-linux.json index ec34445e0..c3cbf613a 100644 --- a/schema/defs-linux.json +++ b/schema/defs-linux.json @@ -148,6 +148,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", @@ -249,6 +257,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": { diff --git a/schema/test/config/good/spec-example.json b/schema/test/config/good/spec-example.json index 5b9ad01dc..8b8d62195 100644 --- a/schema/test/config/good/spec-example.json +++ b/schema/test/config/good/spec-example.json @@ -345,7 +345,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": { diff --git a/specs-go/config.go b/specs-go/config.go index 36d28032e..a7e2f91a5 100644 --- a/specs-go/config.go +++ b/specs-go/config.go @@ -453,6 +453,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 allowlist. @@ -475,6 +493,8 @@ type LinuxResources struct { Rdma map[string]LinuxRdma `json:"rdma,omitempty"` // Unified resources. Unified map[string]string `json:"unified,omitempty"` + // VTPM configuration + VTPMs []LinuxVTPM `json:"vtpms,omitempty"` } // LinuxDevice represents the mknod information for a Linux special device file From f0885e035161068218a9c8a1f9df31fb67fc804c Mon Sep 17 00:00:00 2001 From: Verzakov Efim Date: Wed, 6 Aug 2025 13:14:12 +0000 Subject: [PATCH 2/2] Add additional vTPM fields to the config to be able to run runtime in the container Signed-off-by: Efim Verzakov --- config-linux.md | 17 +++++++++++++---- config.md | 5 ++++- schema/defs-linux.json | 12 +++++++++++- schema/test/config/good/spec-example.json | 11 +++++++++-- specs-go/config.go | 10 ++++++++-- 5 files changed, 45 insertions(+), 10 deletions(-) diff --git a/config-linux.md b/config-linux.md index f5bcda5a3..50c21e998 100644 --- a/config-linux.md +++ b/config-linux.md @@ -592,13 +592,19 @@ The following parameters can be specified to set up the controller: 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. +* **`statePathIsManaged`** *(boolean, OPTIONAL)* - Whether runtime is not allowed to delete the TPM's state path upon destroying the TPM, e.g. if we do not want to recreate vTPM with the previous state. Defaults to false. +* **`vtpmVersion`** *(string, OPTIONAL)* - The version of TPM to emulate, either 1.2 or 2, defaults to 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'. +* **`runAs`** *(string, OPTIONAL)* - Under which user to run the vTPM, e.g. 'tss'. * **`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. +* **`vtpmName`** *(string, REQUIRED)* - The name of vTPM device to emulate in the container. The devpath will have the format `/dev/tpm` + `vtpmName`. `vtpmName` should be unique among the container's `vtpms` devices. +Note that some runtimes can use different commands to pass device in the container (e.g. bind if the container will be running in the non-default user namespace and mknod otherwise). Runtime can adopt a device path to the format `/dev/generated-host-path` + `vtpmName`. This can be essential if we want to create different containers with non-shared VTPM devices under the same device path. +* **`vtpmMajor`** *(int64, OPTIONAL) - The major of vTPM device to emulate in the container. This is required when runtime is running in the container and tmpfs is mounted on `/dev` path. +* **`vtpmMinor`** *(int64, OPTIONAL) - The minor of vTPM device to emulate in the container. This is required when runtime is running in the container and tmpfs is mounted on `/dev` path. + +Note that a vTPM device should be precreated with Endorsement Key Pair. Another main commands e.g. TakeOwnership for TPM 1.2 can be called in the createContainer hooks. #### Example ```json @@ -610,7 +616,10 @@ Each entry has the following structure: "createCerts": false, "runAs": "tss", "pcrBanks": "sha1,sha512", - "encryptionPassword": "mysecret" + "encryptionPassword": "mysecret", + "vtpmName": "tpm0", + "vtpmMajor": 100, + "vtpmMinor": 1 } ] ``` diff --git a/config.md b/config.md index 7965b61df..debf611b0 100644 --- a/config.md +++ b/config.md @@ -1083,7 +1083,10 @@ Here is a full example `config.json` for reference. "vtpmVersion": "2", "createCerts": false, "runAs": "tss", - "pcrBanks": "sha1,sha512" + "pcrBanks": "sha1,sha512", + "vtpmName": "tpm0", + "vtpmMajor": 100, + "vtpmMinor": 1 } ] }, diff --git a/schema/defs-linux.json b/schema/defs-linux.json index c3cbf613a..6406bebe9 100644 --- a/schema/defs-linux.json +++ b/schema/defs-linux.json @@ -280,10 +280,20 @@ }, "encryptionPassword": { "type": "string" + }, + "vtpmName": { + "type": "string" + }, + "vtpmMajor": { + "$ref": "#/definitions/Major" + }, + "vtpmMinor": { + "$ref": "#/definitions/Minor" } }, "required": [ - "statePath" + "statePath", + "vtpmName" ] }, "DeviceCgroup": { diff --git a/schema/test/config/good/spec-example.json b/schema/test/config/good/spec-example.json index 8b8d62195..c7eb69f62 100644 --- a/schema/test/config/good/spec-example.json +++ b/schema/test/config/good/spec-example.json @@ -352,7 +352,11 @@ "vtpmVersion": "2", "createCerts": false, "runAs": "tss", - "pcrBanks": "sha1,sha512" + "pcrBanks": "sha1,sha512", + "encryptionPassword": "mysecret", + "vtpmName": "tpm0", + "vtpmMajor": 100, + "vtpmMinor": 1 }, { "statePath": "/var/lib/runc/myvtpm2", @@ -361,7 +365,10 @@ "createCerts": true, "runAs": "root", "pcrBanks": "sha1,sha512", - "encryptionPassword": "mysecret" + "encryptionPassword": "mysecret", + "vtpmName": "tpm1", + "vtpmMajor": 101, + "vtpmMinor": 1 } ] }, diff --git a/specs-go/config.go b/specs-go/config.go index a7e2f91a5..6d4b25b98 100644 --- a/specs-go/config.go +++ b/specs-go/config.go @@ -460,7 +460,7 @@ type LinuxVTPM struct { // 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"` + VTPMVersion string `json:"vtpmVersion,omitempty"` // Whether to create certificates upon first start of vTPM CreateCertificates bool `json:"createCerts,omitempty"` // The PCR banks to enable @@ -469,6 +469,12 @@ type LinuxVTPM struct { RunAs string `json:"runAs,omitempty"` // The password to derive the encryption key from EncryptionPassword string `json:"encryptionPassword,omitempty"` + // Name of the vtpm + VTPMName string `json:"vtpmName,omitempty"` + // Device's major to be created + VTPMMajor int64 `json:"vtpmMajor,omitempty"` + // Device's minor to be created + VTPMMinor int64 `json:"vtpmMinor,omitempty"` } // LinuxResources has container runtime resource constraints @@ -493,7 +499,7 @@ type LinuxResources struct { Rdma map[string]LinuxRdma `json:"rdma,omitempty"` // Unified resources. Unified map[string]string `json:"unified,omitempty"` - // VTPM configuration + // Linux VTPM configuration VTPMs []LinuxVTPM `json:"vtpms,omitempty"` }