Skip to content

Commit 438758d

Browse files
pragathi93CyrilRoelandteNovance
pragathi93
authored and
CyrilRoelandteNovance
committed
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
1 parent 0f8e5ef commit 438758d

File tree

4 files changed

+118
-0
lines changed

4 files changed

+118
-0
lines changed

‎doc/source/admin/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,3 +25,4 @@ Glance Administration Guide
2525
useful-image-properties
2626
requirements
2727
quotas
28+
os_hash_algo

‎doc/source/admin/os_hash_algo.rst‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
..
2+
This work is licensed under a Creative Commons Attribution 3.0 Unported
3+
License.
4+
5+
http://creativecommons.org/licenses/by/3.0/legalcode
6+
7+
=========================================
8+
Secure Hash Algorithm Support (Multihash)
9+
=========================================
10+
11+
The Secure Hash Algorithm feature supplements the current ‘checksum’
12+
image property with a self-describing secure hash.
13+
14+
The self-description consists of two new image properties:
15+
16+
``os_hash_algo``
17+
Contains the name of the secure hash algorithm used to generate the value on
18+
the image
19+
20+
``os_hash_value``
21+
The hexdigest computed by applying the secure hash algorithm named in the
22+
``os_hash_algo`` property to the image data
23+
24+
Hash Algorithm Configuration
25+
============================
26+
27+
``os_hash_algo`` will be populated by the value of the configuration option
28+
``hashing_algorithm`` in the ``glance.conf`` file. The ``os_hash_value`` value
29+
will be populated by the hexdigest computed when the algorithm is applied to
30+
the uploaded or imported image data.
31+
32+
These are read-only image properties and are not user-modifiable.
33+
34+
The default secure hash algorithm is SHA-512. It should be suitable for most
35+
applications.
36+
37+
The multihash is computed only for new images. There is no provision for
38+
computing the multihash for existing images.

‎doc/source/user/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,3 +14,4 @@ Glance User Guide
1414
glanceclient
1515
glancemetadefcatalogapi
1616
signature
17+
os_hash_algo

‎doc/source/user/os_hash_algo.rst‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
..
2+
This work is licensed under a Creative Commons Attribution 3.0 Unported
3+
License.
4+
5+
http://creativecommons.org/licenses/by/3.0/legalcode
6+
7+
=========================================
8+
Secure Hash Algorithm Support (Multihash)
9+
=========================================
10+
11+
The Secure Hash Algorithm feature adds image properties that may be used to
12+
verify image integrity based on its hash.
13+
14+
The Secure Hash consists of two new image properties:
15+
16+
``os_hash_algo``
17+
Contains the name of the secure hash algorithm
18+
used to generate the value on the image
19+
20+
``os_hash_value``
21+
The hexdigest computed by applying the
22+
secure hash algorithm named in the ``os_hash_algo`` property to
23+
the image data
24+
25+
Image Verification
26+
==================
27+
28+
When Secure Hash is used, the Glance image properties will include the two
29+
fields ``os_hash_algo`` and ``os_hash_value``. These two fields provide the
30+
hashing algorithm used to calculate the secure hash, along with the hash value
31+
calculated for the image.
32+
33+
These values can be used to verify the image integrity when used. For example,
34+
an image and its properties may be viewed with the following::
35+
36+
$ glance image-show fa33e3cd-5fe4-46df-a604-1e9b9438b420
37+
+------------------+----------------------------------------------------------------------------------+
38+
| Property | Value |
39+
+------------------+----------------------------------------------------------------------------------+
40+
| checksum | ffa3dd42fae539dcd8fe72d429bc677b |
41+
| container_format | bare |
42+
| created_at | 2019-06-05T13:39:46Z |
43+
| disk_format | qcow2 |
44+
| id | fa33e3cd-5fe4-46df-a604-1e9b9438b420 |
45+
| min_disk | 10 |
46+
| min_ram | 1024 |
47+
| name | fedora-30 |
48+
| os_hash_algo | sha512 |
49+
| os_hash_value | d9f99d22a6b6ea1e8b93379dd2080f51a7ed6885aa7d4c2f2262ea1054935e02c47b45f9b56aa7f5 |
50+
| | 5e61d149d06f4ff6de03efde24f9d6774baf35f08c5e9d92 |
51+
| os_hidden | False |
52+
| owner | 0e82e8f863a4485fabfbed1b5b856cd7 |
53+
| protected | False |
54+
| size | 332267520 |
55+
| status | active |
56+
| tags | [] |
57+
| updated_at | 2019-06-07T11:41:12Z |
58+
| virtual_size | Not available |
59+
| visibility | public |
60+
+------------------+----------------------------------------------------------------------------------+
61+
62+
From that output, we can see the ``os_hash_algo`` property shows that
63+
**sha512** was used to generate the multihash. The ``os_hash_value`` then shows
64+
the generated hash value is::
65+
66+
d9f99d22a6b6ea1e8b93379dd2080f51a7ed6885aa7d4c2f2262ea1054935e02c47b45f9b56aa7f55e61d149d06f4ff6de03efde24f9d6774baf35f08c5e9d92
67+
68+
When downloading the image, you may now use these values to be able to verify
69+
the integrity of the image. For example::
70+
71+
$ glance image-download fa33e3cd-5fe4-46df-a604-1e9b9438b420 --file fedora-30
72+
$ sha512sum fedora-30
73+
d9f99d22a6b6ea1e8b93379dd2080f51a7ed6885aa7d4c2f2262ea1054935e02c47b45f9b56aa7f55e61d149d06f4ff6de03efde24f9d6774baf35f08c5e9d92
74+
75+
Using the ``sha512sum`` command, we are able to calculate the hash locally on
76+
the image and verify it matches what was expected. If the output were not to
77+
match, that would indicate the image has somehow been modified or corrupted
78+
since being uploaded to Glance, and should likely not be used.

0 commit comments

Comments
 (0)