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. Signed-off-by: Thomas Ackermann th.acker@xxxxxxxx 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. Signed-off-by: Thomas Ackermann <th.acker@xxxxxxxx> ## 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
