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 <[email protected]>

Author: stefanberger

config-linux.md

@@ -585,6 +585,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'.
+* **`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 HugeTLB reservations (if supported) or usage (page fault).

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

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

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

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