From 438758db2feeb59d75d6432b84e449df52ba84d6 Mon Sep 17 00:00:00 2001 From: pragathi93 Date: Wed, 30 Sep 2020 13:21:03 +0530 Subject: [PATCH] Add multihash info in glance documentation New docs added for os_hash_algo in user guide and admin guide. Change-Id: Id78be3935998b9c5acdd0706393117e892e5ab59 Closes-bug:#1871419 --- doc/source/admin/index.rst | 1 + doc/source/admin/os_hash_algo.rst | 38 +++++++++++++++ doc/source/user/index.rst | 1 + doc/source/user/os_hash_algo.rst | 78 +++++++++++++++++++++++++++++++ 4 files changed, 118 insertions(+) create mode 100644 doc/source/admin/os_hash_algo.rst create mode 100644 doc/source/user/os_hash_algo.rst diff --git a/doc/source/admin/index.rst b/doc/source/admin/index.rst index 4766e1aea2..9d13ac4924 100644 --- a/doc/source/admin/index.rst +++ b/doc/source/admin/index.rst @@ -25,3 +25,4 @@ Glance Administration Guide useful-image-properties requirements quotas + os_hash_algo diff --git a/doc/source/admin/os_hash_algo.rst b/doc/source/admin/os_hash_algo.rst new file mode 100644 index 0000000000..04a8c1deb3 --- /dev/null +++ b/doc/source/admin/os_hash_algo.rst @@ -0,0 +1,38 @@ +.. + This work is licensed under a Creative Commons Attribution 3.0 Unported + License. + + http://creativecommons.org/licenses/by/3.0/legalcode + +========================================= +Secure Hash Algorithm Support (Multihash) +========================================= + +The Secure Hash Algorithm feature supplements the current ‘checksum’ +image property with a self-describing secure hash. + +The self-description consists of two new image properties: + +``os_hash_algo`` + Contains the name of the secure hash algorithm used to generate the value on + the image + +``os_hash_value`` + The hexdigest computed by applying the secure hash algorithm named in the + ``os_hash_algo`` property to the image data + +Hash Algorithm Configuration +============================ + +``os_hash_algo`` will be populated by the value of the configuration option +``hashing_algorithm`` in the ``glance.conf`` file. The ``os_hash_value`` value +will be populated by the hexdigest computed when the algorithm is applied to +the uploaded or imported image data. + +These are read-only image properties and are not user-modifiable. + +The default secure hash algorithm is SHA-512. It should be suitable for most +applications. + +The multihash is computed only for new images. There is no provision for +computing the multihash for existing images. diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst index a8c186d26e..f5ddaabdb2 100644 --- a/doc/source/user/index.rst +++ b/doc/source/user/index.rst @@ -14,3 +14,4 @@ Glance User Guide glanceclient glancemetadefcatalogapi signature + os_hash_algo diff --git a/doc/source/user/os_hash_algo.rst b/doc/source/user/os_hash_algo.rst new file mode 100644 index 0000000000..8e5c44dde1 --- /dev/null +++ b/doc/source/user/os_hash_algo.rst @@ -0,0 +1,78 @@ +.. + This work is licensed under a Creative Commons Attribution 3.0 Unported + License. + + http://creativecommons.org/licenses/by/3.0/legalcode + +========================================= +Secure Hash Algorithm Support (Multihash) +========================================= + +The Secure Hash Algorithm feature adds image properties that may be used to +verify image integrity based on its hash. + +The Secure Hash consists of two new image properties: + +``os_hash_algo`` + Contains the name of the secure hash algorithm + used to generate the value on the image + +``os_hash_value`` + The hexdigest computed by applying the + secure hash algorithm named in the ``os_hash_algo`` property to + the image data + +Image Verification +================== + +When Secure Hash is used, the Glance image properties will include the two +fields ``os_hash_algo`` and ``os_hash_value``. These two fields provide the +hashing algorithm used to calculate the secure hash, along with the hash value +calculated for the image. + +These values can be used to verify the image integrity when used. For example, +an image and its properties may be viewed with the following:: + + $ glance image-show fa33e3cd-5fe4-46df-a604-1e9b9438b420 + +------------------+----------------------------------------------------------------------------------+ + | Property | Value | + +------------------+----------------------------------------------------------------------------------+ + | checksum | ffa3dd42fae539dcd8fe72d429bc677b | + | container_format | bare | + | created_at | 2019-06-05T13:39:46Z | + | disk_format | qcow2 | + | id | fa33e3cd-5fe4-46df-a604-1e9b9438b420 | + | min_disk | 10 | + | min_ram | 1024 | + | name | fedora-30 | + | os_hash_algo | sha512 | + | os_hash_value | d9f99d22a6b6ea1e8b93379dd2080f51a7ed6885aa7d4c2f2262ea1054935e02c47b45f9b56aa7f5 | + | | 5e61d149d06f4ff6de03efde24f9d6774baf35f08c5e9d92 | + | os_hidden | False | + | owner | 0e82e8f863a4485fabfbed1b5b856cd7 | + | protected | False | + | size | 332267520 | + | status | active | + | tags | [] | + | updated_at | 2019-06-07T11:41:12Z | + | virtual_size | Not available | + | visibility | public | + +------------------+----------------------------------------------------------------------------------+ + +From that output, we can see the ``os_hash_algo`` property shows that +**sha512** was used to generate the multihash. The ``os_hash_value`` then shows +the generated hash value is:: + + d9f99d22a6b6ea1e8b93379dd2080f51a7ed6885aa7d4c2f2262ea1054935e02c47b45f9b56aa7f55e61d149d06f4ff6de03efde24f9d6774baf35f08c5e9d92 + +When downloading the image, you may now use these values to be able to verify +the integrity of the image. For example:: + + $ glance image-download fa33e3cd-5fe4-46df-a604-1e9b9438b420 --file fedora-30 + $ sha512sum fedora-30 + d9f99d22a6b6ea1e8b93379dd2080f51a7ed6885aa7d4c2f2262ea1054935e02c47b45f9b56aa7f55e61d149d06f4ff6de03efde24f9d6774baf35f08c5e9d92 + +Using the ``sha512sum`` command, we are able to calculate the hash locally on +the image and verify it matches what was expected. If the output were not to +match, that would indicate the image has somehow been modified or corrupted +since being uploaded to Glance, and should likely not be used.