Merge pull request #65077 from jldohmann/OSDOCS-6988

OSDOCS-6988: add offline tang provisioning

Author: jldohmann

modules/installation-special-config-storage.adoc

@@ -54,8 +54,10 @@ You can also configure the TPM v2 and Tang encryption modes simultaneously.
 This enables boot disk data decryption only if the TPM secure cryptoprocessor is present and the Tang servers are accessible over a secure network.
 
 You can use the `threshold` attribute in your Butane configuration to define the minimum number of TPM v2 and Tang encryption conditions required for decryption to occur.
-The threshold is met when the stated value is reached through any combination of the declared conditions.
-For example, the `threshold` value of `2` in the following configuration can be reached by accessing the two Tang servers, or by accessing the TPM secure cryptoprocessor and one of the Tang servers:
+
+The threshold is met when the stated value is reached through any combination of the declared conditions. In the case of offline provisioning, the offline server is accessed using an included advertisement, and only uses that supplied advertisement if the number of online servers do not meet the set threshold.
+
+For example, the `threshold` value of `2` in the following configuration can be reached by accessing two Tang servers, with the offline server available as a backup, or by accessing the TPM secure cryptoprocessor and one of the Tang servers:
 
 .Example Butane configuration for disk encryption
 
@@ -76,15 +78,19 @@ boot_device:
         thumbprint: jwGN5tRFK-kF6pIX89ssF3khxxX
       - url: http://tang2.example.com:7500
         thumbprint: VCJsvZFjBSIHSldw78rOrq7h2ZF
-    threshold: 2 <4>
+      - url: http://tang3.example.com:7500
+        thumbprint: PLjNyRdGw03zlRoGjQYMahSZGu9
+        advertisement: "{\"payload\": \"...\", \"protected\": \"...\", \"signature\": \"...\"}" <4>
+    threshold: 2 <5>
 openshift:
   fips: true
 ----
 <1> Set this field to the instruction set architecture of the cluster nodes.
 Some examples include, `x86_64`, `aarch64`, or `ppc64le`.
 <2> Include this field if you want to use a Trusted Platform Module (TPM) to encrypt the root file system.
 <3> Include this section if you want to use one or more Tang servers.
-<4> Specify the minimum number of TPM v2 and Tang encryption conditions required for decryption to occur.
+<4> Optional: Include this field for offline provisioning. Ignition will provision the Tang server binding rather than fetching the advertisement from the server at runtime. This lets the server be unavailable at provisioning time.
+<5> Specify the minimum number of TPM v2 and Tang encryption conditions required for decryption to occur.
 
 [IMPORTANT]
 ====
@@ -151,11 +157,11 @@ $ sudo yum install clevis
 ----
 
 .. On the {op-system-base} 8 machine, run the following command to generate a thumbprint of the exchange key.
-Replace `\http://tang.example.com:7500` with the URL of your Tang server:
+Replace `\http://tang1.example.com:7500` with the URL of your Tang server:
 +
 [source,terminal]
 ----
-$ clevis-encrypt-tang '{"url":"http://tang.example.com:7500"}' < /dev/null > /dev/null <1>
+$ clevis-encrypt-tang '{"url":"http://tang1.example.com:7500"}' < /dev/null > /dev/null <1>
 ----
 <1> In this example, `tangd.socket` is listening on port `7500` on the Tang server.
 +
@@ -184,6 +190,28 @@ Some other distributions provide Clevis version 17 or later, which use the SHA-2
 You must use a Clevis version that uses SHA-1 to create the thumbprint, to prevent Clevis binding issues when you install {op-system-first} on your {product-title} cluster nodes.
 ====
 
+.. Optional: For offline Tang provisioning:
+
+... Obtain the advertisement from the server using the `curl` command. Replace `\http://tang2.example.com:7500` with the URL of your Tang server:
++
+[source,terminal]
+----
+$ curl -f http://tang2.example.com:7500/adv > adv.jws && cat adv.jws
+----
++
+.Expected output
+[source,text]
+----
+{"payload": "eyJrZXlzIjogW3siYWxnIjogIkV", "protected": "eyJhbGciOiJFUzUxMiIsImN0eSI", "signature": "ADLgk7fZdE3Yt4FyYsm0pHiau7Q"}
+----
+
+... Provide the advertisement file to Clevis for encryption:
++
+[source,terminal]
+----
+$ clevis-encrypt-tang '{"url":"http://tang2.example.com:7500","adv":"adv.jws"}' < /dev/null > /dev/null
+----
+
 .. If the nodes are configured with static IP addressing, run `coreos-installer iso customize --dest-karg-append` or use the `coreos-installer` `--append-karg` option when installing {op-system} nodes to set the IP address of the installed system.
 Append the `ip=` and other arguments needed for your network.
 +
@@ -219,15 +247,18 @@ boot_device:
   luks: <3>
     tpm2: true <4>
     tang: <5>
-      - url: http://tang.example.com:7500 <6>
+      - url: http://tang1.example.com:7500 <6>
         thumbprint: PLjNyRdGw03zlRoGjQYMahSZGu9 <7>
-    threshold: 1 <8>
-  mirror: <9>
-    devices: <10>
+      - url: http://tang2.example.com:7500
+        thumbprint: VCJsvZFjBSIHSldw78rOrq7h2ZF
+        advertisement: "{"payload": "eyJrZXlzIjogW3siYWxnIjogIkV", "protected": "eyJhbGciOiJFUzUxMiIsImN0eSI", "signature": "ADLgk7fZdE3Yt4FyYsm0pHiau7Q"}" <8>
+    threshold: 1 <9>
+  mirror: <10>
+    devices: <11>
       - /dev/sda
       - /dev/sdb
 openshift:
-  fips: true <11>
+  fips: true <12>
 ----
 +
 <1> For control plane configurations, replace `worker` with `master` in both of these locations.
@@ -240,13 +271,14 @@ For more details, see "About disk encryption".
 <6> Specify the URL of a Tang server.
 In this example, `tangd.socket` is listening on port `7500` on the Tang server.
 <7> Specify the exchange key thumbprint, which was generated in a preceding step.
-<8> Specify the minimum number of TPM v2 and Tang encryption conditions that must be met for decryption to occur.
+<8> Optional: Specify the advertisement for your offline Tang server in valid JSON format.
+<9> Specify the minimum number of TPM v2 and Tang encryption conditions that must be met for decryption to occur.
 The default value is `1`.
 For more information about this topic, see "Configuring an encryption threshold".
-<9> Include this section if you want to mirror the boot disk.
+<10> Include this section if you want to mirror the boot disk.
 For more details, see "About disk mirroring".
-<10> List all disk devices that should be included in the boot disk mirror, including the disk that {op-system} will be installed onto.
-<11> Include this directive to enable FIPS mode on your cluster.
+<11> List all disk devices that should be included in the boot disk mirror, including the disk that {op-system} will be installed onto.
+<12> Include this directive to enable FIPS mode on your cluster.
 +
 [IMPORTANT]
 ====
@@ -451,4 +483,4 @@ In the example output, the `/boot` file system is mounted on the `/dev/md126` so
 [role="_additional-resources"]
 .Additional resources
 
-* For more information about the TPM v2 and Tang encryption modes, see link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/security_hardening/configuring-automated-unlocking-of-encrypted-volumes-using-policy-based-decryption_security-hardening[Configuring automated unlocking of encrypted volumes using policy-based decryption].
+* For more information about the TPM v2 and Tang encryption modes, see link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/security_hardening/configuring-automated-unlocking-of-encrypted-volumes-using-policy-based-decryption_security-hardening[Configuring automated unlocking of encrypted volumes using policy-based decryption].