doc: improvements for hash-function-transition

Some asciidoc formatting errors and some minor formatting inconsistencies in hash-function-transition.txt were fixed.

Content-wise the rationale for choosing SHA-256 was shortened a little bit and moved to the beginning of the document. Also an incomplete sentence was corrected.

Changes since v2:

* Move a stray change from 1/6 back to 2/6; fix an incomplete conversion in 2/6.
* Rework rationale based on the comments from Junio and Brian.
* Rebased on current master.

Changes since v1:

* Better commit messages.

* Details on SHA-1 weaknesses were removed from the rationale.

* All http links to lore.kernel.org in the tree were changed to https links.

Thanks to Ævar, Junio and Brian for their suggestions and help.

Thomas Ackermann (6):
doc hash-function-transition: fix asciidoc output
doc hash-function-transition: use SHA-1 and SHA-256 consistently doc hash-function-transition: use upper case consistently doc hash-function-transition: fix incomplete sentence doc hash-function-transition: move rationale upwards
doc: use https links

 .../technical/hash-function-transition.txt    | 293 +++++++++---------
 t/t0021-conversion.sh                         |   4 +-
 2 files changed, 150 insertions(+), 147 deletions(-)

base-commit: 30b29f044a2b30f0667eb21559959e03eb1bd04f
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-858%2Ftacker66%2Fdoc_hash_function_transition-v3
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-858/tacker66/doc_hash_function_transition-v3
Pull-Request: https://github.com/gitgitgadget/git/pull/858

Range-diff vs v2:

1: f36c5dd4c1e3 ! 1: 7c78d0c1c30a doc hash-function-transition: fix asciidoc output
@@ Documentation/technical/hash-function-transition.txt: network byte order):
Loose object index
~~~~~~~~~~~~~~~~~~
@@ Documentation/technical/hash-function-transition.txt: the following steps:
- they will be discarded.)
3. convert to sha256: open a new (sha256) packfile. Read the topologically sorted list just generated. For each object, inflate its
-- sha1-content, convert to sha256-content, and write it to the sha256
+ sha1-content, convert to sha256-content, and write it to the sha256
- pack. Record the new sha1<->sha256 mapping entry for use in the idx.
-+ SHA-1 content, convert to SHA-256 content, and write it to the SHA-256
-+ pack. Record the new SHA-1<-->SHA-256 mapping entry for use in the idx.
++ pack. Record the new sha1<-->sha256 mapping entry for use in the idx.
4. sort: reorder entries in the new pack to match the order of objects
in the pack the server generated and include blobs. Write a sha256 idx
file
2: 681ce4129dc3 ! 2: 69ebc9a8f19a doc hash-function-transition: use SHA-1 and SHA-256 consistently
@@ Documentation/technical/hash-function-transition.txt: repository extensions.
-that objects referenced by the object are named using their sha256-names -instead of sha1-names. Because a blob object does not refer to any
-other object, its sha1-content and sha256-content are the same.
-+The SHA-256-content of an object is the same as its SHA-1 content, except ++The SHA-256 content of an object is the same as its SHA-1 content, except
+that objects referenced by the object are named using their SHA-256 names +instead of SHA-1 names. Because a blob object does not refer to any
+other object, its SHA-1 content and SHA-256 content are the same.
@@ Documentation/technical/hash-function-transition.txt: the following steps:
-3. convert to sha256: open a new (sha256) packfile. Read the topologically
+3. convert to SHA-256: open a new SHA-256 packfile. Read the topologically
sorted list just generated. For each object, inflate its
- SHA-1 content, convert to SHA-256 content, and write it to the SHA-256
- pack. Record the new SHA-1<-->SHA-256 mapping entry for use in the idx.
+- sha1-content, convert to sha256-content, and write it to the sha256
+- pack. Record the new sha1<-->sha256 mapping entry for use in the idx.
++ SHA-1 content, convert to SHA-256 content, and write it to the SHA-256
++ pack. Record the new SHA-1<-->SHA-256 mapping entry for use in the idx.
4. sort: reorder entries in the new pack to match the order of objects
- in the pack the server generated and include blobs. Write a sha256 idx
+ in the pack the server generated and include blobs. Write a SHA-256 idx

 3:  4f622fffcc5d = 3:  06b781206e4c doc hash-function-transition: use upper case consistently
 4:  58295cadffe5 = 4:  7a29f06c3f25 doc hash-function-transition: fix incomplete sentence
 5:  711a37969b6f ! 5:  ee0fa2ec1d0f doc hash-function-transition: move rationale upwards

@@ Commit message
Move rationale for new hash function to beginning of document so that it appears before the concrete move to SHA-256 is described.

- Remove details about SHA-1 weaknesses. Instead add references
- to the details of how the new hash function was chosen.
+ Remove some of the details about SHA-1 weaknesses and add references
+ to the details on how the new hash function was chosen instead.

## Documentation/technical/hash-function-transition.txt ##
-@@ Documentation/technical/hash-function-transition.txt: advantages:
- methods have a short reliable string that can be used to reliably
- address stored content.
-
--Over time some flaws in SHA-1 have been discovered by security
--researchers. On 23 February 2017 the SHAttered attack
--(https://shattered.io) demonstrated a practical SHA-1 hash collision.
-+Over time some flaws in SHA-1 have been discovered by security researchers.
+@@ Documentation/technical/hash-function-transition.txt: researchers. On 23 February 2017 the SHAttered attack

Git v2.13.0 and later subsequently moved to a hardened SHA-1
--implementation by default, which isn't vulnerable to the SHAttered
+ implementation by default, which isn't vulnerable to the SHAttered -attack.
-+implementation by default, but SHA-1 is still believed to be weak. ++attack, but SHA-1 is still weak.

-Thus Git has in effect already migrated to a new hash that isn't SHA-1 -and doesn't share its vulnerabilities, its new hash function just
@@ Documentation/technical/hash-function-transition.txt: SHA-1 still possesses the

+Choice of Hash
+--------------
++The hash to replace the hardened SHA-1 should be stronger than SHA-1 ++was: we would like it to be trustworthy and useful in practice for at ++least 10 years.
++
++Some other relevant properties:
++
++1. A 256-bit hash (long enough to match common security practice; not
++ excessively long to hurt performance and disk usage).
++
++2. High quality implementations should be widely available (e.g., in
++ OpenSSL and Apple CommonCrypto).
++
++3. The hash function's properties should match Git's needs (e.g. Git
++ requires collision and 2nd preimage resistance and does not require
++ length extension resistance).
++
++4. As a tiebreaker, the hash should be fast to compute (fortunately
++ many contenders are faster than SHA-1).
++
+There were several contenders for a successor hash to SHA-1, including +SHA-256, SHA-512/256, SHA-256x16, K12, and BLAKE2bp-256.
+
6: d6041b7e9e87 = 6: c31d6e258fd0 doc: use https links

gitgitgadget