Merge pull request #36403 from StephenJamesSmith/TELCODOCS-266

Telcodocs 266: Implementing Network Bound Disk Encryption

Author: mikemckiernan

_topic_map.yml

@@ -800,6 +800,18 @@ Topics:
 - Name: Scanning pods for vulnerabilities
   File: pod-vulnerability-scan
   Distros: openshift-enterprise,openshift-origin
+- Name: Network-Bound Disk Encryption (NBDE)
+  Dir: network_bound_disk_encryption
+  Topics:
+  - Name: About disk encryption technology
+    File: nbde-about-disk-encryption-technology
+  - Name: Tang server installation considerations
+    File: nbde-tang-server-installation-considerations
+  - Name: Tang server encryption key management
+    File: nbde-managing-encryption-keys
+  - Name: Disaster recovery considerations
+    File: nbde-disaster-recovery-considerations
+    Distros: openshift-enterprise,openshift-origin
 ---
 Name: Authentication and authorization
 Dir: authentication

images/179_OpenShift_NBDE_implementation_0821_1.png

@@ -0,0 +1,10 @@
+// Module included in the following assemblies:
+//
+// security/nbde-implementation-guide.adoc
+
+[id="nbde-automatic-start-at-boot_{context}"]
+= Automatic start at boot
+
+Due to the sensitive nature of the key material the Tang server uses, you should keep in mind that the overhead of manual intervention during the Tang server’s boot sequence can be beneficial.
+
+By default, if a Tang server starts and does not have key material present in the expected local volume, it will create fresh material and serve it.  You can avoid this default behavior by either starting with pre-existing key material or aborting the startup and waiting for manual intervention.

images/179_OpenShift_NBDE_implementation_0821_2.png

@@ -0,0 +1,12 @@
+// Module included in the following assemblies:
+//
+// security/nbde-implementation-guide.adoc
+
+[id="nbde-backing-up-server-keys_{context}"]
+= Backing up keys for a Tang server
+
+The Tang server, by default, stores its keys in the `/usr/libexec/tangd-keygen` directory. Back up the contents of this directory to enable recovery in the event of the loss of the Tang server. The keys are sensitive and since they are able to perform the boot disk decryption of all hosts that have used them, the keys must be protected accordingly.
+
+.Procedure
+
+* Back up the contents of the `/usr/libexec/tangd-keygen` directory.

images/179_OpenShift_NBDE_implementation_0821_3.png

@@ -0,0 +1,18 @@
+// Module included in the following assemblies:
+//
+// security/nbde-implementation-guide.adoc
+
+[id="nbde-compromise-of-key-material_{context}"]
+= Rekeying compromised key material
+
+If key material is potentially exposed to unauthorized third parties, such as through the physical theft of a Tang server or associated data, immediately rotate the keys.
+
+.Procedure
+
+. Rekey any Tang server holding the affected material.
+. Rekey all clients using the Tang server.
+. Destroy the original key material.
+. Scrutinize any incidents that result in unintended exposure of the master encryption key. If possible, take compromised nodes offline and re-encrypt their disks.
+
+[TIP]
+Reformatting and reinstalling on the same physical hardware, although slow, is easy to automate and test.

images/179_OpenShift_NBDE_implementation_0821_4.png

@@ -0,0 +1,10 @@
+// Module included in the following assemblies:
+//
+// security/nbde-implementation-guide.adoc
+
+[id="nbde-compute-requirements_{context}"]
+= Compute requirements
+
+The computational requirements for the Tang server are very low. Any typical server grade configuration that you would use to deploy a server into production can provision sufficient compute capacity.
+
+High availability considerations are solely for availability and not additional compute power to satisfy client demands.

modules/nbde-automatic-start-at-boot.adoc

@@ -0,0 +1,24 @@
+// Module included in the following assemblies:
+//
+// security/nbde-implementation-guide.adoc
+
+[id="nbde-deciding-the-number-of-tang-servers-to-use_{context}"]
+= Tang server sizing requirements
+
+The requirements around availability, network, and physical location drive the decision of how many Tang servers to use, rather than any concern over server capacity.
+
+Tang servers do not maintain the state of data encrypted using Tang resources. Tang servers are either fully independent or share only their key material, which enables them to scale well.
+
+There are two ways Tang servers handle key material:
+
+* Multiple Tang servers share key material:
+** You must load balance Tang servers sharing keys behind the same URL. The configuration can be as simple as round-robin DNS, or you can use physical load balancers.
+** You can scale from a single Tang server to multiple Tang servers. Scaling Tang servers does not require rekeying or client reconfiguration on the node when the Tang servers share key material and the same URL.
+** Client node setup and key rotation only requires one Tang server.
+
+* Multiple Tang servers generate their own key material:
+** You can configure multiple Tang servers at installation time.
+** You can scale an individual Tang server behind a load balancer.
+** All Tang servers must be available during client node setup or key rotation.
+** When a client node boots using the default configuration, the Clevis client contacts all Tang servers. Only _n_ Tang servers must be online to proceed with decryption. The default value for _n_ is 1.
+** Red Hat does not support post-installation configuration that changes the behavior of the Tang servers.