Add explanations on safe delete

We keep seeing people concerned about data leakage and thorough deletion
of data from volumes on volume deletion [1][2], and Cinder currently
only worries about the data leakage, not the stealing of the physical
disks.

In order to clarify this for administrators and to reduce the number of
specs proposed to address this issue we are adding additional
documentation on security aspects as well as data leakage.

This patch was decided as an action from the discussion during the
Wallaby PTG [3].

[1]: https://review.opendev.org/#/c/758375/
[2]: https://review.opendev.org/#/c/759553/
[3]: https://wiki.openstack.org/wiki/CinderWallabyPTGSummary#Two_proposed_specs_on_the_same_topic_.28mutually_assured_destruction.29

Change-Id: I9f8d413cf8337e75241ad24c85692135b34a17fc
Implements: blueprint specify-data-secure-deletion

cinder/interface/volume_driver.py

@@ -168,6 +168,10 @@ class VolumeDriverCore(base.CinderInterface):
         longer present, this call should succeed and allow Cinder to complete
         the process of deleting the volume.
 
+        It is imperative that this operation ensures that the data from the
+        deleted volume cannot leak into new volumes when they are created, as
+        new volumes are likely to belong to a different tenant/project.
+
         :param volume: The volume to delete.
         :raises VolumeIsBusy: if the volume is still attached or has snapshots.
                  VolumeBackendAPIException on error.

cinder/volume/driver.py

@@ -615,6 +615,10 @@ class BaseVD(object, metaclass=abc.ABCMeta):
 
         If volume_type extra specs includes 'replication: <is> True'
         then the driver needs to delete the volume replica too.
+
+        It is imperative that this operation ensures that the data from the
+        deleted volume cannot leak into new volumes when they are created, as
+        new volumes are likely to belong to a different tenant/project.
         """
         return
 

doc/source/admin/blockstorage-security.rst

@@ -0,0 +1,75 @@
+========
+Security
+========
+
+Network traffic
+~~~~~~~~~~~~~~~
+
+Depending on your deployment's security requirements, you might be required to
+encrypt network traffic.  This can be accomplished with TLS.
+
+There are multiple deployment options, with the most common and recommended
+ones being:
+
+- Only encrypt traffic between clients and public endpoints. This approach
+  results in fewer certificates to manage, and we refer to it as public TLS.
+  Public endpoints, in this sense, are endpoints only exposed to end-users.
+  Traffic between internal endpoints is not encrypted.
+
+- Leverages TLS for all endpoints in the entire deployment, including internal
+  endpoints of the OpenStack services and with auxiliary services such as the
+  database and the message broker.
+
+You can look at `TripleO's documentation on TLS`_ for examples on how to do
+this.
+
+Cinder drivers should support secure TLS/SSL communication between the cinder
+volume service and the backend, as configured by the ``driver_ssl_cert_verify``
+and ``driver_ssl_cert_path`` options in ``cinder.conf``.
+
+If unsure whether your driver supports TLS/SSL, please check the driver's
+specific page in the :ref:`volume-drivers` page or contact the vendor.
+
+Data at rest
+~~~~~~~~~~~~
+
+Volumes' data can be secured at rest using Cinder's volume encryption feature.
+
+For encryption keys Cinder uses a Key management service, with Barbican being
+the recommended service.
+
+More information on encryption can be found on the :ref:`volume-encryption`
+section.
+
+Data leakage
+~~~~~~~~~~~~
+
+Some users and admins worry about data leakage between OpenStack projects or
+users caused by a new volume containing partial or full data from a previously
+deleted volume.
+
+These concerns are sometimes instigated by the ``volume_clear`` and
+``volume_clear_size`` configuration options, but these options are only
+relevant to the LVM driver, and only when using thick volumes (which are not
+the default, thin volumes are).
+
+Writing data on a Cinder volume as a generic mechanism to prevent data leakage
+is not implemented for other drivers because it does not ensure that the data
+will be actually erased on the physical disks, as the storage solution could be
+doing copy-on-write or other optimizations.
+
+Thin provisioned volumes return zeros for unallocated blocks, so we don't have
+to worry about data leakage. As for thick volumes, each of the individual
+Cinder drivers must ensure that data from a deleted volume can never leak to a
+newly created volume.
+
+This prevents other OpenStack projects and users from being able to get data
+from deleted volumes, but since the data may still be present on the physical
+disks, somebody with physical access to the disks may still be able to retrieve
+that data.
+
+For those concerned with this, we recommend using encrypted volumes or read
+your storage solution's documentation or contact your vendor to see if they
+have some kind of clear policy option available on their storage solution.
+
+.. _TripleO's documentation on TLS: https://docs.openstack.org/project-deploy-guide/tripleo-docs/latest/features/tls-introduction.html

doc/source/admin/index.rst

@@ -24,6 +24,7 @@ Amazon EC2 Elastic Block Storage (EBS) offering.
 .. toctree::
    :maxdepth: 1
 
+   blockstorage-security.rst
    blockstorage-accelerate-image-compression.rst
    blockstorage-api-throughput.rst
    blockstorage-manage-volumes.rst

doc/source/configuration/block-storage/volume-drivers.rst

@@ -1,3 +1,5 @@
+.. _volume-drivers:
+
 ==============
 Volume drivers
 ==============

doc/source/configuration/block-storage/volume-encryption.rst

@@ -1,3 +1,5 @@
+.. _volume-encryption:
+
 ==============================================
 Volume encryption supported by the key manager
 ==============================================