Add vTPM specification

config-linux.md

@@ -585,6 +585,45 @@ 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`** *(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'.
+* **`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
+    "vtpms": [
+        {
+            "statePath": "/var/lib/runc/myvtpm1",
+            "statePathIsManaged": false,
+            "vtpmVersion": "2",
+            "createCerts": false,
+            "runAs": "tss",
+            "pcrBanks": "sha1,sha512",
+            "encryptionPassword": "mysecret",
+            "vtpmName": "tpm0",
+            "vtpmMajor": 100,
+            "vtpmMinor": 1
+        }
+    ]
+```
+
 ### <a name="configLinuxHugePageLimits" />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).

config.md

@@ -1076,7 +1076,19 @@ 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",
+                    "vtpmName": "tpm0",
+                    "vtpmMajor": 100,
+                    "vtpmMinor": 1
+                }
+            ]
         },
         "rootfsPropagation": "slave",
         "seccomp": {

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": {

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,45 @@
                 }
             ]
         },
+        "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"
+                },
+                "vtpmName": {
+                    "type": "string"
+                },
+                "vtpmMajor": {
+                    "$ref": "#/definitions/Major"
+                },
+                "vtpmMinor": {
+                    "$ref": "#/definitions/Minor"
+                }
+            },
+            "required": [
+                "statePath",
+                "vtpmName"
+            ]
+        },
         "DeviceCgroup": {
             "type": "object",
             "properties": {

schema/test/config/good/spec-example.json

@@ -345,7 +345,32 @@
                         "rate": 300
                     }
                 ]
-            }
+            },
+            "vtpms": [
+                {
+                    "statePath": "/var/lib/runc/myvtpm1",
+                    "vtpmVersion": "2",
+                    "createCerts": false,
+                    "runAs": "tss",
+                    "pcrBanks": "sha1,sha512",
+                    "encryptionPassword": "mysecret",
+                    "vtpmName": "tpm0",
+                    "vtpmMajor": 100,
+                    "vtpmMinor": 1
+                },
+                {
+                    "statePath": "/var/lib/runc/myvtpm2",
+                    "statePathIsManaged": true,
+                    "vtpmVersion": "1.2",
+                    "createCerts": true,
+                    "runAs": "root",
+                    "pcrBanks": "sha1,sha512",
+                    "encryptionPassword": "mysecret",
+                    "vtpmName": "tpm1",
+                    "vtpmMajor": 101,
+                    "vtpmMinor": 1
+                }
+            ]
         },
         "rootfsPropagation": "slave",
         "seccomp": {

specs-go/config.go

@@ -453,6 +453,30 @@ 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
+	VTPMVersion 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"`
+	// 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
 type LinuxResources struct {
 	// Devices configures the device allowlist.
@@ -475,6 +499,8 @@ type LinuxResources struct {
 	Rdma map[string]LinuxRdma `json:"rdma,omitempty"`
 	// Unified resources.
 	Unified map[string]string `json:"unified,omitempty"`
+	// Linux VTPM configuration
+	VTPMs []LinuxVTPM `json:"vtpms,omitempty"`
 }
 
 // LinuxDevice represents the mknod information for a Linux special device file