diff --git a/_topic_map.yml b/_topic_map.yml index b990338e6e..57ab48fa88 100644 --- a/_topic_map.yml +++ b/_topic_map.yml @@ -787,6 +787,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 diff --git a/images/179_OpenShift_NBDE_implementation_0821_1.png b/images/179_OpenShift_NBDE_implementation_0821_1.png new file mode 100644 index 0000000000..7007bcbeb7 Binary files /dev/null and b/images/179_OpenShift_NBDE_implementation_0821_1.png differ diff --git a/images/179_OpenShift_NBDE_implementation_0821_2.png b/images/179_OpenShift_NBDE_implementation_0821_2.png new file mode 100644 index 0000000000..2fe21e0832 Binary files /dev/null and b/images/179_OpenShift_NBDE_implementation_0821_2.png differ diff --git a/images/179_OpenShift_NBDE_implementation_0821_3.png b/images/179_OpenShift_NBDE_implementation_0821_3.png new file mode 100644 index 0000000000..f70ddba3da Binary files /dev/null and b/images/179_OpenShift_NBDE_implementation_0821_3.png differ diff --git a/images/179_OpenShift_NBDE_implementation_0821_4.png b/images/179_OpenShift_NBDE_implementation_0821_4.png new file mode 100644 index 0000000000..67d574b2c5 Binary files /dev/null and b/images/179_OpenShift_NBDE_implementation_0821_4.png differ diff --git a/modules/nbde-automatic-start-at-boot.adoc b/modules/nbde-automatic-start-at-boot.adoc new file mode 100644 index 0000000000..770cd2c160 --- /dev/null +++ b/modules/nbde-automatic-start-at-boot.adoc @@ -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. diff --git a/modules/nbde-backing-up-server-keys.adoc b/modules/nbde-backing-up-server-keys.adoc new file mode 100644 index 0000000000..72887ae576 --- /dev/null +++ b/modules/nbde-backing-up-server-keys.adoc @@ -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. diff --git a/modules/nbde-compromise-of-key-material.adoc b/modules/nbde-compromise-of-key-material.adoc new file mode 100644 index 0000000000..0b29d071b5 --- /dev/null +++ b/modules/nbde-compromise-of-key-material.adoc @@ -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. diff --git a/modules/nbde-compute-requirements.adoc b/modules/nbde-compute-requirements.adoc new file mode 100644 index 0000000000..180e1859e8 --- /dev/null +++ b/modules/nbde-compute-requirements.adoc @@ -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. diff --git a/modules/nbde-deciding-the-number-of-tang-servers-to-use.adoc b/modules/nbde-deciding-the-number-of-tang-servers-to-use.adoc new file mode 100644 index 0000000000..0e85bc4cec --- /dev/null +++ b/modules/nbde-deciding-the-number-of-tang-servers-to-use.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. diff --git a/modules/nbde-deleting-old-tang-server-keys.adoc b/modules/nbde-deleting-old-tang-server-keys.adoc new file mode 100644 index 0000000000..612d2a46de --- /dev/null +++ b/modules/nbde-deleting-old-tang-server-keys.adoc @@ -0,0 +1,90 @@ +// Module included in the following assemblies: +// +// security/nbde-implementation-guide.adoc + +[id="nbde-deleting-old-tang-server-keys_{context}"] += Deleting old Tang server keys + +.Prerequisites + +* A root shell on the Linux machine running the Tang server. + +.Procedure + +. Locate and access the directory where the Tang server key is stored. This is usually the `/var/db/tang` directory: ++ +[source,terminal] +---- +# cd /var/db/tang/ +---- + +. List the current Tang server keys, showing the advertised and unadvertised keys: ++ +[source,terminal] +---- +# ls -A1 +---- ++ +.Example output +[source,terminal] +---- +.36AHjNH3NZDSnlONLz1-V4ie6t8.jwk +.gJZiNPMLRBnyo_ZKfK4_5SrnHYo.jwk +Bp8XjITceWSN_7XFfW7WfJDTomE.jwk +WOjQYkyK7DxY_T5pMncMO5w0f6E.jwk +---- + +. Delete the old keys: ++ +[source,terminal] +---- +# rm .*.jwk +---- + +. List the current Tang server keys to verify the unadvertised keys are no longer present: ++ +[source,terminal] +---- +# ls -A1 +---- ++ +.Example output +[source,terminal] +---- +Bp8XjITceWSN_7XFfW7WfJDTomE.jwk +WOjQYkyK7DxY_T5pMncMO5w0f6E.jwk +---- + +.Verification + +At this point, the server still advertises the new keys, but an attempt to decrypt based on the old key will fail. + +. Query the Tang server for the current advertised key thumbprints: ++ +[source,terminal] +---- +# tang-show-keys 7500 +---- ++ +.Example output ++ +[source,terminal] +---- +WOjQYkyK7DxY_T5pMncMO5w0f6E +---- + +. Decrypt the test file created earlier to verify decryption against the old keys fails: ++ +[source,terminal] +---- +# clevis decrypt /tmp/encrypted.oldkey +---- ++ +* Verify that the encryption succeeded and the file can be decrypted to produce the same string `plaintext`: ++ +[source,terminal] +---- +# clevis decrypt - + {"t":1,"pins":{"tang":[ + {"url":"http://tangserver01:7500","thp":"WOjQYkyK7DxY_T5pMncMO5w0f6E"}, + {"url":"http://tangserver02:7500","thp":"I5Ynh2JefoAO3tNH9TgI4obIaXI"}, + {"url":"http://tangserver03:7500","thp":"38qWZVeDKzCPG9pHLqKzs6k1ons"} + ]}} + volumeMounts: + - name: hostroot + mountPath: /host + securityContext: + privileged: true + volumes: + - name: hostroot + hostPath: + path: / + nodeSelector: + kubernetes.io/os: linux + priorityClassName: system-node-critical + restartPolicy: Always + serviceAccount: machine-config-daemon + serviceAccountName: machine-config-daemon +---- ++ +In this case, even though you are rekeying `tangserver01`, you must specify not only the new thumbprint for `tangserver01`, but also the current thumbprints for all other Tang servers. Failure to specify all thumbprints for a rekeying operation opens up the opportunity for a man-in-the-middle attack. + +. To distribute the daemon set to every cluster that must be rekeyed, run the following command: ++ +[source,terminal] +---- +$ oc apply -f tang-rekey.yaml +---- ++ +However, to run at scale, wrap the daemon set in an ACM policy. This ACM configuration must contain one policy to deploy the daemon set, +a second policy to check that all the daemon set pods are READY, and a placement rule to apply it to the appropriate set of clusters. + +[NOTE] +==== +After validating that the daemon set has successfully rekeyed all servers, delete the daemon set. If you do not delete the daemon set, it must be deleted before the next rekeying operation. +==== + +.Verification + +After you distribute the daemon set, monitor the daemon sets to ensure that the rekeying has completed successfully. The script in the example daemon set terminates with an error if the rekeying failed, and remains in the `CURRENT` state if successful. There is also a readiness probe that marks the pod as `READY` when the rekeying has completed successfully. + +* This is an example of the output listing for the daemon set before the rekeying has completed: ++ +[source,terminal] +---- +$ oc get -n openshift-machine-config-operator ds tang-rekey +---- ++ +.Example output ++ +[source,terminal] +---- +NAME DESIRED CURRENT READY UP-TO-DATE AVAILABLE NODE SELECTOR AGE +tang-rekey 1 1 0 1 0 kubernetes.io/os=linux 11s +---- ++ +* This is an example of the output listing for the daemon set after the rekeying has completed successfully: ++ +[source,terminal] +---- +$ oc get -n openshift-machine-config-operator ds tang-rekey +---- ++ +.Example output ++ +[source,terminal] +---- +NAME DESIRED CURRENT READY UP-TO-DATE AVAILABLE NODE SELECTOR AGE +tang-rekey 1 1 1 1 1 kubernetes.io/os=linux 13h +---- + +Rekeying usually takes a few minutes to complete. + +[NOTE] +==== +If you use ACM policies to distribute the daemon sets to multiple clusters, you must include a compliance policy that checks every daemon set’s READY count is equal to the DESIRED count. In this way, compliance to such a policy demonstrates that all daemon set pods are READY and the rekeying has completed successfully. You could also use an ACM search to query all of the daemon sets' states. +==== diff --git a/modules/nbde-rekeying-tang-servers.adoc b/modules/nbde-rekeying-tang-servers.adoc new file mode 100644 index 0000000000..4ea18f50ae --- /dev/null +++ b/modules/nbde-rekeying-tang-servers.adoc @@ -0,0 +1,30 @@ +// Module included in the following assemblies: +// +// security/nbde-implementation-guide.adoc + +[id="nbde-rekeying-tang-servers_{context}"] += Rekeying Tang servers + +This procedure uses a set of three Tang servers, each with unique keys, as an example. + +Using redundant Tang servers reduces the chances of nodes failing to boot automatically. + +Rekeying a Tang server, and all associated NBDE-encrypted nodes, is a three-step procedure. + +.Prerequisites + +* A working Network-Bound Disk Encryption (NBDE) installation on one or more nodes. + +.Procedure + +. Generate a new Tang server key. +. Rekey all NBDE-encrypted nodes so they use the new key. +. Delete the old Tang server key. ++ +[NOTE] +==== +Deleting the old key before all NBDE-encrypted nodes have completed their rekeying causes those nodes to become overly dependent on any other configured Tang servers. +==== + +.Example workflow for rekeying a Tang server +image::179_OpenShift_NBDE_implementation_0821_4.png[Rekeying a Tang server] diff --git a/modules/nbde-secret-sharing-encryption.adoc b/modules/nbde-secret-sharing-encryption.adoc new file mode 100644 index 0000000000..9168ec0f82 --- /dev/null +++ b/modules/nbde-secret-sharing-encryption.adoc @@ -0,0 +1,10 @@ +// Module included in the following assemblies: +// +// security/nbde-implementation-guide.adoc + +[id="nbde-secret-sharing-encryption_{context}"] += Secret sharing encryption + +Shamir’s secret sharing (sss) is a cryptographic algorithm to securely divide up, distribute, and re-assemble keys. Using this algorithm, {product-title} can support more complicated mixtures of key protection. + +When you configure a cluster node to use multiple Tang servers, {product-title} uses sss to set up a decryption policy that will succeed if at least one of the specified servers is available. You can create layers for additional security. For example, you can define a policy where {product-title} requires both the TPM and one of the given list of Tang servers to decrypt the disk. diff --git a/modules/nbde-tpm-encryption.adoc b/modules/nbde-tpm-encryption.adoc new file mode 100644 index 0000000000..b98fee78f3 --- /dev/null +++ b/modules/nbde-tpm-encryption.adoc @@ -0,0 +1,10 @@ +// Module included in the following assemblies: +// +// security/nbde-implementation-guide.adoc + +[id="nbde-tpm-encryption_{context}"] += TPM encryption + +Trusted Platform Module (TPM) disk encryption is best suited for data centers or installations in remote protected locations. Full disk encryption utilities such as dm-crypt and BitLocker encrypt disks with a TPM bind key, and then store the TPM bind key in the TPM, which is attached to the motherboard of the node. The main benefit of this method is that there is no external dependency, and the node is able to decrypt its own disks at boot time without any external interaction. + +TPM disk encryption protects against decryption of data if the disk is stolen from the node and analyzed externally. However, for insecure locations this may not be sufficient. For example, if an attacker steals the entire node, the attacker can intercept the data when powering on the node, because the node decrypts its own disks. This applies to nodes with physical TPM2 chips as well as virtual machines with Virtual Trusted Platform Module (VTPM) access. diff --git a/modules/nbde-troubleshooting-permanent-error-conditions.adoc b/modules/nbde-troubleshooting-permanent-error-conditions.adoc new file mode 100644 index 0000000000..cd089e6cba --- /dev/null +++ b/modules/nbde-troubleshooting-permanent-error-conditions.adoc @@ -0,0 +1,94 @@ +// Module included in the following assemblies: +// +// security/nbde-implementation-guide.adoc + +[id="nbde-troubleshooting-permanent-error-conditions_{context}"] += Troubleshooting permanent rekeying errors for Tang servers + +If, after rekeying the Tang servers, the `READY` count does not equal the `DESIRED` count after an extended period of time, it might indicate a permanent failure condition. In this case, the following conditions might apply: + +* A typographical error in the Tang server URL or thumbprint in the `NEW_TANG_PIN` definition. +* The Tang server is decommissioned or the keys are permanently lost. + +.Prerequisites + +* The commands shown in this procedure can be run on the Tang server or on any Linux system that has network +access to the Tang server. + +.Procedure + +. Validate the Tang server configuration by performing a simple encrypt and decrypt operation on each Tang +server’s configuration as defined in the daemon set. ++ +This is an example of an encryption and decryption attempt with a bad thumbprint: ++ +[source,terminal] +---- +$ echo "okay" | clevis encrypt tang \ + '{"url":"http://tangserver02:7500","thp":"badthumbprint"}' | \ + clevis decrypt +---- ++ +.Example output ++ +[source,terminal] +---- +Unable to fetch advertisement: 'http://tangserver02:7500/adv/badthumbprint'! +---- ++ +This is an example of an encryption and decryption attempt with a good thumbprint: ++ +[source,terminal] +---- +$ echo "okay" | clevis encrypt tang \ + '{"url":"http://tangserver03:7500","thp":"goodthumbprint"}' | \ + clevis decrypt +---- ++ +.Example output + ++ +[source,terminal] +---- +okay +---- + +. After you identify the root cause, remedy the underlying situation: + +.. Delete the non-working daemon set. +.. Edit the daemon set definition to fix the underlying issue. This might include any of the following actions: ++ +* Edit a Tang server entry to correct the URL and thumbprint. +* Remove a Tang server that is no longer in service. +* Add a new Tang server that is a replacement for a decommissioned server. + +. Distribute the updated daemon set again. + +[NOTE] +==== +When replacing, removing, or adding a Tang server from a configuration, the rekeying operation will succeed as long as at least one original server is still functional, including the server currently being rekeyed. If none of the original Tang servers are functional or can be recovered, recovery of the system is impossible and you must redeploy the affected nodes. +==== + +.Verification + +* Check the logs from each pod in the daemon set to determine whether the rekeying completed successfully. If the rekeying is not successful, the logs might indicate the failure condition. The following log is from a completed successful rekeying operation: ++ +[source,terminal] +---- +$ oc logs rekey-tang-kp4q2 +---- ++ +.Example output +[source,terminal] +---- +Current tang pin: +1: sss '{"t":1,"pins":{"tang":[{"url":"http://10.46.55.192:7500"},{"url":"http://10.46.55.192:7501"},{"url":"http://10.46.55.192:7502"}]}}' +Applying new tang pin: {"t":1,"pins":{"tang":[ + {"url":"http://tangserver01:7500","thp":"WOjQYkyK7DxY_T5pMncMO5w0f6E"}, + {"url":"http://tangserver02:7500","thp":"I5Ynh2JefoAO3tNH9TgI4obIaXI"}, + {"url":"http://tangserver03:7500","thp":"38qWZVeDKzCPG9pHLqKzs6k1ons"} +]}} +Updating binding... +Binding edited successfully +Pin applied successfully +---- diff --git a/modules/nbde-troubleshooting-temporary-error-conditions.adoc b/modules/nbde-troubleshooting-temporary-error-conditions.adoc new file mode 100644 index 0000000000..4372d5e109 --- /dev/null +++ b/modules/nbde-troubleshooting-temporary-error-conditions.adoc @@ -0,0 +1,19 @@ +// Module included in the following assemblies: +// +// security/nbde-implementation-guide.adoc + +[id="nbde-troubleshooting-temporary-error-conditions_{context}"] += Troubleshooting temporary rekeying errors for Tang servers + +To determine if the error condition from rekeying the Tang servers is temporary, perform the following procedure. Temporary error conditions might include: + +* Temporary network outages +* Tang server maintenance + +Generally, when these types of temporary error conditions occur, you can wait until the daemon set succeeds in resolving the error or you can delete the daemon set and not try again until the temporary error condition has been resolved. + +.Procedure + +. Restart the pod that performs the rekeying operation using the normal Kubernetes pod restart policy. + +. If any of the associated Tang servers are unavailable, try rekeying until all the servers are back online. diff --git a/modules/nbde-unexpected-loss-of-network-connectivity.adoc b/modules/nbde-unexpected-loss-of-network-connectivity.adoc new file mode 100644 index 0000000000..ec0218a745 --- /dev/null +++ b/modules/nbde-unexpected-loss-of-network-connectivity.adoc @@ -0,0 +1,12 @@ +// Module included in the following assemblies: +// +// security/nbde-implementation-guide.adoc + +[id="nbde-unexpected-loss-of-network-connectivity_{context}"] += Unexpected loss of network connectivity + +If the network disruption is unexpected and a node reboots, consider the following scenarios: + +* If any nodes are still online, ensure that they do not reboot until network connectivity is restored. This is not applicable for single-node clusters. +* The node will remain offline until such time that either network connectivity is restored, or a pre-established passphrase is entered manually at the console. In exceptional circumstances, network administrators might be able to reconfigure network segments to reestablish access, but this is counter to the intent of NBDE, which is that lack of network access means lack of ability to boot. +* The lack of network access at the node can reasonably be expected to impact that node’s ability to function as well as its ability to boot. Even if the node were to boot via manual intervention, the lack of network access would make it effectively useless. diff --git a/modules/nbde-using-tang-servers-for-disk-encryption.adoc b/modules/nbde-using-tang-servers-for-disk-encryption.adoc new file mode 100644 index 0000000000..bc337da7a3 --- /dev/null +++ b/modules/nbde-using-tang-servers-for-disk-encryption.adoc @@ -0,0 +1,24 @@ +// Module included in the following assemblies: +// +// security/nbde-implementation-guide.adoc + +[id="nbde-using-tang-servers-for-disk-encryption_{context}"] += Tang server disk encryption + +The following components and technologies implement Network-Bound Disk Encryption (NBDE). + +image::179_OpenShift_NBDE_implementation_0821_3.png[Network-Bound Disk Encryption (NBDE), Clevis framework, Tang server] + +_Tang_ is a server for binding data to network presence. It makes a node containing the data available when the node is bound to a certain secure network. Tang is stateless and does not require Transport Layer Security (TLS) or authentication. Unlike escrow-based solutions, where the key server stores all encryption keys and has knowledge of every encryption key, Tang never interacts with any node keys, so it never gains any identifying information from the node. + +_Clevis_ is a pluggable framework for automated decryption that provides automated unlocking of Linux Unified Key Setup-on-disk-format (LUKS) volumes. The Clevis package runs on the node and provides the client side of the feature. + +A _Clevis pin_ is a plug-in into the Clevis framework. There are three pin types: + +TPM2:: Binds the disk encryption to the TPM2. +Tang:: Binds the disk encryption to a Tang server to enable NBDE. +Shamir’s secret sharing (sss):: Allows more complex combinations of other pins. It allows more nuanced policies such as the following: + +* Must be able to reach one of these three Tang servers +* Must be able to reach three of these five Tang servers +* Must be able to reach the TPM2 AND at least one of these three Tang servers diff --git a/security/network_bound_disk_encryption/images b/security/network_bound_disk_encryption/images new file mode 120000 index 0000000000..5e67573196 --- /dev/null +++ b/security/network_bound_disk_encryption/images @@ -0,0 +1 @@ +../images \ No newline at end of file diff --git a/security/network_bound_disk_encryption/modules b/security/network_bound_disk_encryption/modules new file mode 120000 index 0000000000..464b823aca --- /dev/null +++ b/security/network_bound_disk_encryption/modules @@ -0,0 +1 @@ +../modules \ No newline at end of file diff --git a/security/network_bound_disk_encryption/nbde-about-disk-encryption-technology.adoc b/security/network_bound_disk_encryption/nbde-about-disk-encryption-technology.adoc new file mode 100644 index 0000000000..b5db27d61e --- /dev/null +++ b/security/network_bound_disk_encryption/nbde-about-disk-encryption-technology.adoc @@ -0,0 +1,28 @@ +// CNF-2127 assembly +[id="nbde-about-disk-encryption-technology"] += About disk encryption technology +include::modules/common-attributes.adoc[] +:context: nbde-implementation + +toc::[] + +Network-Bound Disk Encryption (NBDE) allows you to encrypt root volumes of hard drives on physical and virtual +machines without having to manually enter a password when restarting machines. + +include::modules/nbde-disk-encryption-technology-comparison.adoc[leveloffset=+1] + +include::modules/nbde-key-escrow.adoc[leveloffset=+2] + +include::modules/nbde-tpm-encryption.adoc[leveloffset=+2] + +include::modules/nbde-network-bound-disk-encryption.adoc[leveloffset=+2] + +include::modules/nbde-secret-sharing-encryption.adoc[leveloffset=+2] + +include::modules/nbde-using-tang-servers-for-disk-encryption.adoc[leveloffset=+1] + +include::modules/nbde-locating-the-tang-servers.adoc[leveloffset=+1] + +include::modules/nbde-deciding-the-number-of-tang-servers-to-use.adoc[leveloffset=+1] + +include::modules/nbde-logging-considerations.adoc[leveloffset=+1] diff --git a/security/network_bound_disk_encryption/nbde-disaster-recovery-considerations.adoc b/security/network_bound_disk_encryption/nbde-disaster-recovery-considerations.adoc new file mode 100644 index 0000000000..8868bfb7e7 --- /dev/null +++ b/security/network_bound_disk_encryption/nbde-disaster-recovery-considerations.adoc @@ -0,0 +1,25 @@ +// CNF-2127 assembly +[id="nbde-disaster-recovery-considerations"] += Disaster recovery considerations +include::modules/common-attributes.adoc[] +:context: nbde-implementation + +toc::[] + +This section describes several potential disaster situations and the procedures to respond to each of them. Additional situations will be added here as they are discovered or presumed likely to be possible. + +include::modules/nbde-loss-of-a-client-machine.adoc[leveloffset=+1] + +include::modules/nbde-loss-of-client-connectivity.adoc[leveloffset=+1] + +include::modules/nbde-unexpected-loss-of-network-connectivity.adoc[leveloffset=+1] + +include::modules/nbde-recovering-network-connectivity-manually.adoc[leveloffset=+1] + +include::modules/nbde-emergency-recovery-of-network-connectivity.adoc[leveloffset=+1] + +include::modules/nbde-loss-of-a-network-segment.adoc[leveloffset=+1] + +include::modules/nbde-loss-of-a-tang-server.adoc[leveloffset=+1] + +include::modules/nbde-compromise-of-key-material.adoc[leveloffset=+1] diff --git a/security/network_bound_disk_encryption/nbde-managing-encryption-keys.adoc b/security/network_bound_disk_encryption/nbde-managing-encryption-keys.adoc new file mode 100644 index 0000000000..b38f72de2a --- /dev/null +++ b/security/network_bound_disk_encryption/nbde-managing-encryption-keys.adoc @@ -0,0 +1,28 @@ +// CNF-2127 assembly +[id="nbde-managing-encryption-keys"] += Tang server encryption key management +include::modules/common-attributes.adoc[] +:context: nbde-implementation + +toc::[] + + +The cryptographic mechanism to recreate the encryption key is based on the _blinded key_ stored on the node and the private key of the involved Tang servers. To protect against the possibility of an attacker who has obtained both the Tang server private key and the node’s encrypted disk, periodic rekeying is advisable. + +You must perform the rekeying operation for every node before you can delete the old key from the Tang server. The following sections provide procedures for rekeying and deleting old keys. + +include::modules/nbde-backing-up-server-keys.adoc[leveloffset=+1] + +include::modules/nbde-recovering-server-keys.adoc[leveloffset=+1] + +include::modules/nbde-rekeying-tang-servers.adoc[leveloffset=+1] + +include::modules/nbde-generating-a-new-tang-server-key.adoc[leveloffset=+2] + +include::modules/nbde-rekeying-all-nbde-nodes.adoc[leveloffset=+2] + +include::modules/nbde-troubleshooting-temporary-error-conditions.adoc[leveloffset=+2] + +include::modules/nbde-troubleshooting-permanent-error-conditions.adoc[leveloffset=+2] + +include::modules/nbde-deleting-old-tang-server-keys.adoc[leveloffset=+1] diff --git a/security/network_bound_disk_encryption/nbde-tang-server-installation-considerations.adoc b/security/network_bound_disk_encryption/nbde-tang-server-installation-considerations.adoc new file mode 100644 index 0000000000..a0f307877c --- /dev/null +++ b/security/network_bound_disk_encryption/nbde-tang-server-installation-considerations.adoc @@ -0,0 +1,26 @@ +// CNF-2127 assembly +[id="nbde-tang-server-installation-considerations"] += Tang server installation considerations +include::modules/common-attributes.adoc[] +:context: nbde-implementation + +toc::[] + +include::modules/nbde-installation-scenarios.adoc[leveloffset=+1] + +include::modules/nbde-installing-a-tang-server.adoc[leveloffset=+1] + +include::modules/nbde-compute-requirements.adoc[leveloffset=+2] + +include::modules/nbde-automatic-start-at-boot.adoc[leveloffset=+2] + +include::modules/nbde-http-versus-https.adoc[leveloffset=+2] + +include::modules/nbde-openshift-installation-with-nbde.adoc[leveloffset=+1] + +.Additional resources +* 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] +* https://catalog.redhat.com/software/containers/detail/5fbc405674aa0cc23b445f8f?container-tabs=overview>i-tabs=registry-tokens[Official Tang server container] +* https://docs.openshift.com/container-platform/4.8/installing/install_config/installing-customizing.html#installation-special-config-storage_installing-customizing[Encrypting and mirroring disks during installation] +// This is an xref suggested in peer review that does not work. +// * xref::../../installing/install_config/installing-customizing.adoc#installation-special-config-storage_installing-customizing[Encrypting and mirroring disks during installation]