Merge "Disable MD5 image checksums"

1 files changed, 33 insertions, 0 deletions

diff --git a/doc/source/admin/how_it_works.rst b/doc/source/admin/how_it_works.rst
index 5f4a6773..20a5f477 100644
--- a/doc/source/admin/how_it_works.rst
+++ b/doc/source/admin/how_it_works.rst
@@ -223,3 +223,36 @@ fields:
     .. note::
         This is most likely to be set by the DHCP server. Could be localhost
         if the DHCP server does not set it.
+
+Image Checksums
+---------------
+
+As part of the process of downloading images to be written to disk as part of
+image deployment, a series of fields are utilized to determine if the
+image which has been downloaded matches what the user stated as the expected
+image checksum utilizing the ``instance_info/image_checksum`` value.
+
+OpenStack, as a whole, has replaced the "legacy" ``checksum`` field with
+``os_hash_value`` and ``os_hash_algo`` fields, which allows for an image
+checksum and value to be asserted. An advantage of this is a variety of
+algorithms are available, if a user/operator is so-inclined.
+
+For the purposes of Ironic, we continue to support the pass-through checksum
+field as we support the checksum being retrieved via a URL.
+
+We also support determining the checksum by length.
+
+The field can be utilized to designate:
+
+* A URL to retreive a checksum from.
+* MD5 (Disabled by default, see ``[DEFAULT]md5_enabled`` in the agent
+  configuration file.)
+* SHA-2 based SHA256
+* SHA-2 based SHA512
+
+SHA-3 based checksums are not supported for auto-determination as they can
+have a variable length checksum result. At of when this documentation was
+added, SHA-2 based checksum algorithms have not been withdrawn from from
+approval. If you need to force use of SHA-3 based checksums, you *must*
+utilize the ``os_hash_algo`` setting along with the ``os_hash_value``
+setting.