doc hash-function-transition: pick SHA-256 as NewHash
From a security perspective, it seems that SHA-256, BLAKE2, SHA3-256,
K12, and so on are all believed to have similar security properties.
All are good options from a security point of view.
SHA-256 has a number of advantages:
* It has been around for a while, is widely used, and is supported by
just about every single crypto library (OpenSSL, mbedTLS, CryptoNG,
SecureTransport, etc).
* When you compare against SHA1DC, most vectorized SHA-256
implementations are indeed faster, even without acceleration.
* If we're doing signatures with OpenPGP (or even, I suppose, CMS),
we're going to be using SHA-2, so it doesn't make sense to have our
security depend on two separate algorithms when either one of them
alone could break the security when we could just depend on one.
So SHA-256 it is. Update the hash-function-transition design doc to
say so.
After this patch, there are no remaining instances of the string
"NewHash", except for an unrelated use from 2008 as a variable name in
t/t9700/test.pl.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Acked-by: Linus Torvalds <torvalds@linux-foundation.org>
Acked-by: brian m. carlson <sandals@crustytoothpaste.net>
Acked-by: Johannes Schindelin <Johannes.Schindelin@gmx.de>
Acked-by: Dan Shumow <danshu@microsoft.com>
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
maint
Jonathan Nieder7 years agocommitted byJunio C Hamano
@ -59,14 +59,11 @@ that are believed to be cryptographically secure.
@@ -59,14 +59,11 @@ that are believed to be cryptographically secure.
Goals
-----
Where NewHash is a strong 256-bit hash function to replace SHA-1 (see
"Selection of a New Hash", below):
1. The transition to NewHash can be done one local repository at a time.
1. The transition to SHA-256 can be done one local repository at a time.
a. Requiring no action by any other party.
b. A NewHash repository can communicate with SHA-1 Git servers
b. A SHA-256 repository can communicate with SHA-1 Git servers
(push/fetch).
c. Users can use SHA-1 and NewHash identifiers for objects
c. Users can use SHA-1 and SHA-256 identifiers for objects
interchangeably (see "Object names on the command line", below).
d. New signed objects make use of a stronger hash function than
SHA-1 for their security guarantees.
@ -79,7 +76,7 @@ Where NewHash is a strong 256-bit hash function to replace SHA-1 (see
@@ -79,7 +76,7 @@ Where NewHash is a strong 256-bit hash function to replace SHA-1 (see
Non-Goals
---------
1. Add NewHash support to Git protocol. This is valuable and the
1. Add SHA-256 support to Git protocol. This is valuable and the
logical next step but it is out of scope for this initial design.
2. Transparently improving the security of existing SHA-1 signed
4. Taking the opportunity to fix other bugs in Git's formats and
protocols.
5. Shallow clones and fetches into a NewHash repository. (This will
change when we add NewHash support to Git protocol.)
6. Skip fetching some submodules of a project into a NewHash
repository. (This also depends on NewHash support in Git
5. Shallow clones and fetches into a SHA-256 repository. (This will
change when we add SHA-256 support to Git protocol.)
6. Skip fetching some submodules of a project into a SHA-256
repository. (This also depends on SHA-256 support in Git
protocol.)
Overview
--------
We introduce a new repository format extension. Repositories with this
extension enabled use NewHash instead of SHA-1 to name their objects.
extension enabled use SHA-256 instead of SHA-1 to name their objects.
This affects both object names and object content --- both the names
of objects and all references to other objects within an object are
switched to the new hash function.
NewHash repositories cannot be read by older versions of Git.
SHA-256 repositories cannot be read by older versions of Git.
Alongside the packfile, a NewHash repository stores a bidirectional
mapping between NewHash and SHA-1 object names. The mapping is generated
Alongside the packfile, a SHA-256 repository stores a bidirectional
mapping between SHA-256 and SHA-1 object names. The mapping is generated
locally and can be verified using "git fsck". Object lookups use this
mapping to allow naming objects using either their SHA-1 and NewHash names
mapping to allow naming objects using either their SHA-1 and SHA-256 names
interchangeably.
"git cat-file" and "git hash-object" gain options to display an object
@ -116,7 +113,7 @@ object database so that they can be named using the appropriate name
@@ -116,7 +113,7 @@ object database so that they can be named using the appropriate name
(using the bidirectional hash mapping).
Fetches from a SHA-1 based server convert the fetched objects into
NewHash form and record the mapping in the bidirectional mapping table
SHA-256 form and record the mapping in the bidirectional mapping table
(see below for details). Pushes to a SHA-1 based server convert the
objects being pushed into sha1 form so the server does not have to be
up to and not including the table of CRC32 values.
- Zero or more NUL bytes.
- The trailer consists of the following:
- A copy of the 20-byte NewHash checksum at the end of the
- A copy of the 20-byte SHA-256 checksum at the end of the
corresponding packfile.
- 20-byte NewHash checksum of all of the above.
- 20-byte SHA-256 checksum of all of the above.
Loose object index
~~~~~~~~~~~~~~~~~~
@ -266,7 +263,7 @@ A new file $GIT_OBJECT_DIR/loose-object-idx contains information about
@@ -266,7 +263,7 @@ A new file $GIT_OBJECT_DIR/loose-object-idx contains information about
all loose objects. Its format is
# loose-object-idx
(newhash-name SP sha1-name LF)*
(sha256-name SP sha1-name LF)*
where the object names are in hexadecimal format. The file is not
sorted.
@ -292,8 +289,8 @@ To remove entries (e.g. in "git pack-refs" or "git-prune"):
@@ -292,8 +289,8 @@ To remove entries (e.g. in "git pack-refs" or "git-prune"):
Translation table
~~~~~~~~~~~~~~~~~
The index files support a bidirectional mapping between sha1-names
and newhash-names. The lookup proceeds similarly to ordinary object
lookups. For example, to convert a sha1-name to a newhash-name:
and sha256-names. The lookup proceeds similarly to ordinary object
lookups. For example, to convert a sha1-name to a sha256-name:
1. Look for the object in idx files. If a match is present in the
idx's sorted list of truncated sha1-names, then:
@ -301,8 +298,8 @@ lookups. For example, to convert a sha1-name to a newhash-name:
@@ -301,8 +298,8 @@ lookups. For example, to convert a sha1-name to a newhash-name:
name order mapping.
b. Read the corresponding entry in the full sha1-name table to
verify we found the right object. If it is, then
c. Read the corresponding entry in the full newhash-name table.
That is the object's newhash-name.
c. Read the corresponding entry in the full sha256-name table.
That is the object's sha256-name.
2. Check for a loose object. Read lines from loose-object-idx until
we find a match.
@ -318,25 +315,25 @@ for all objects in the object store.
@@ -318,25 +315,25 @@ for all objects in the object store.
Reading an object's sha1-content
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The sha1-content of an object can be read by converting all newhash-names
its newhash-content references to sha1-names using the translation table.
The sha1-content of an object can be read by converting all sha256-names
its sha256-content references to sha1-names using the translation table.
Fetch
~~~~~
Fetching from a SHA-1 based server requires translating between SHA-1
and NewHash based representations on the fly.
and SHA-256 based representations on the fly.
SHA-1s named in the ref advertisement that are present on the client
can be translated to NewHash and looked up as local objects using the
can be translated to SHA-256 and looked up as local objects using the
translation table.
Negotiation proceeds as today. Any "have"s generated locally are
converted to SHA-1 before being sent to the server, and SHA-1s
mentioned by the server are converted to NewHash when looking them up
mentioned by the server are converted to SHA-256 when looking them up
locally.
After negotiation, the server sends a packfile containing the
requested objects. We convert the packfile to NewHash format using
requested objects. We convert the packfile to SHA-256 format using
the following steps:
1. index-pack: inflate each object in the packfile and compute its
@ -351,12 +348,12 @@ the following steps:
@@ -351,12 +348,12 @@ the following steps:
(This list only contains objects reachable from the "wants". If the
pack from the server contained additional extraneous objects, then
they will be discarded.)
3. convert to newhash: open a new (newhash) packfile. Read the topologically
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 newhash-content, and write it to the newhash
pack. Record the new sha1<->newhash 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.
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 newhash idx
in the pack the server generated and include blobs. Write a sha256 idx
file
5. clean up: remove the SHA-1 based pack file, index, and
topologically sorted list obtained from the server in steps 1
Fortunately NewHash and SHA-1 have different lengths. If Git starts
Fortunately SHA-256 and SHA-1 have different lengths. If Git starts
using another hash with the same length to name objects, then it will
need to change the format of signed payloads using that hash to
address this issue.
@ -574,24 +571,24 @@ supports four different modes of operation:
@@ -574,24 +571,24 @@ supports four different modes of operation:
1. ("dark launch") Treat object names input by the user as SHA-1 and
convert any object names written to output to SHA-1, but store
objects using NewHash. This allows users to test the code with no
objects using SHA-256. This allows users to test the code with no
visible behavior change except for performance. This allows
allows running even tests that assume the SHA-1 hash function, to
sanity-check the behavior of the new mode.
2. ("early transition") Allow both SHA-1 and NewHash object names in
2. ("early transition") Allow both SHA-1 and SHA-256 object names in
input. Any object names written to output use SHA-1. This allows
users to continue to make use of SHA-1 to communicate with peers
(e.g. by email) that have not migrated yet and prepares for mode 3.
3. ("late transition") Allow both SHA-1 and NewHash object names in
input. Any object names written to output use NewHash. In this
3. ("late transition") Allow both SHA-1 and SHA-256 object names in
input. Any object names written to output use SHA-256. In this
mode, users are using a more secure object naming method by
default. The disruption is minimal as long as most of their peers
are in mode 2 or mode 3.
4. ("post-transition") Treat object names input by the user as
NewHash and write output using NewHash. This is safer than mode 3
SHA-256 and write output using SHA-256. This is safer than mode 3
because there is less risk that input is incorrectly interpreted
using the wrong hash function.
@ -601,27 +598,31 @@ The user can also explicitly specify which format to use for a
@@ -601,27 +598,31 @@ The user can also explicitly specify which format to use for a
particular revision specifier and for output, overriding the mode. For
In early 2005, around the time that Git was written, Xiaoyun Wang,
Yiqun Lisa Yin, and Hongbo Yu announced an attack finding SHA-1
collisions in 2^69 operations. In August they published details.
Luckily, no practical demonstrations of a collision in full SHA-1 were
published until 10 years later, in 2017.
The hash function NewHash to replace 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.
Git v2.13.0 and later subsequently moved to a hardened SHA-1
implementation by default that mitigates the SHAttered attack, but
SHA-1 is still believed to be weak.
The hash to replace this 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).
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
@ -630,14 +631,13 @@ Some other relevant properties:
@@ -630,14 +631,13 @@ Some other relevant properties:
4. As a tiebreaker, the hash should be fast to compute (fortunately
many contenders are faster than SHA-1).
Some hashes under consideration are SHA-256, SHA-512/256, SHA-256x16,
K12, and BLAKE2bp-256.
We choose SHA-256.
Transition plan
---------------
Some initial steps can be implemented independently of one another:
- adding a hash function API (vtable)
- teaching fsck to tolerate the gpgsig-newhash field
- teaching fsck to tolerate the gpgsig-sha256 field
- excluding gpgsig-* from the fields copied by "git commit --amend"
- annotating tests that depend on SHA-1 values with a SHA1 test
prerequisite
@ -664,7 +664,7 @@ Next comes introduction of compatObjectFormat:
@@ -664,7 +664,7 @@ Next comes introduction of compatObjectFormat:
- adding appropriate index entries when adding a new object to the
object store
- --output-format option
- ^{sha1} and ^{newhash} revision notation
- ^{sha1} and ^{sha256} revision notation
- configuration to specify default input and output format (see
"Object names on the command line" above)
@ -672,7 +672,7 @@ The next step is supporting fetches and pushes to SHA-1 repositories:
@@ -672,7 +672,7 @@ The next step is supporting fetches and pushes to SHA-1 repositories:
- allow pushes to a repository using the compat format
- generate a topologically sorted list of the SHA-1 names of fetched
objects
- convert the fetched packfile to newhash format and generate an idx
- convert the fetched packfile to sha256 format and generate an idx
file
- re-sort to match the order of objects in the fetched packfile
@ -680,30 +680,30 @@ The infrastructure supporting fetch also allows converting an existing
@@ -680,30 +680,30 @@ The infrastructure supporting fetch also allows converting an existing
repository. In converted repositories and new clones, end users can
gain support for the new hash function without any visible change in
behavior (see "dark launch" in the "Object names on the command line"
section). In particular this allows users to verify NewHash signatures
section). In particular this allows users to verify SHA-256 signatures
on objects in the repository, and it should ensure the transition code
is stable in production in preparation for using it more widely.
Over time projects would encourage their users to adopt the "early
transition" and then "late transition" modes to take advantage of the
new, more futureproof NewHash object names.
new, more futureproof SHA-256 object names.
When objectFormat and compatObjectFormat are both set, commands
generating signatures would generate both SHA-1 and NewHash signatures
generating signatures would generate both SHA-1 and SHA-256 signatures
by default to support both new and old users.
In projects using NewHash heavily, users could be encouraged to adopt
In projects using SHA-256 heavily, users could be encouraged to adopt
the "post-transition" mode to avoid accidentally making implicit use
of SHA-1 object names.
Once a critical mass of users have upgraded to a version of Git that
can verify NewHash signatures and have converted their existing
can verify SHA-256 signatures and have converted their existing
repositories to support verifying them, we can add support for a
setting to generate only NewHash signatures. This is expected to be at
setting to generate only SHA-256 signatures. This is expected to be at
least a year later.
That is also a good moment to advertise the ability to convert
repositories to use NewHash only, stripping out all SHA-1 related
repositories to use SHA-256 only, stripping out all SHA-1 related
metadata. This improves performance by eliminating translation
overhead and security by avoiding the possibility of accidentally
relying on the safety of SHA-1.
@ -742,16 +742,16 @@ using the old hash function.
@@ -742,16 +742,16 @@ using the old hash function.
Signed objects with multiple hashes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Instead of introducing the gpgsig-newhash field in commit and tag objects
for newhash-content based signatures, an earlier version of this design
added "hash newhash <newhash-name>" fields to strengthen the existing
Instead of introducing the gpgsig-sha256 field in commit and tag objects
for sha256-content based signatures, an earlier version of this design
added "hash sha256 <sha256-name>" fields to strengthen the existing
sha1-content based signatures.
In other words, a single signature was used to attest to the object
content using both hash functions. This had some advantages:
* Using one signature instead of two speeds up the signing process.
* Having one signed payload with both hashes allows the signer to
attest to the sha1-name and newhash-name referring to the same object.
attest to the sha1-name and sha256-name referring to the same object.
* All users consume the same signature. Broken signatures are likely
to be detected quickly using current versions of git.
@ -760,11 +760,11 @@ However, it also came with disadvantages:
@@ -760,11 +760,11 @@ However, it also came with disadvantages:
objects it references, even after the transition is complete and
translation table is no longer needed for anything else. To support
this, the design added fields such as "hash sha1 tree <sha1-name>"
and "hash sha1 parent <sha1-name>" to the newhash-content of a signed
and "hash sha1 parent <sha1-name>" to the sha256-content of a signed
commit, complicating the conversion process.
* Allowing signed objects without a sha1 (for after the transition is
complete) complicated the design further, requiring a "nohash sha1"
field to suppress including "hash sha1" fields in the newhash-content
field to suppress including "hash sha1" fields in the sha256-content
Jonathan Nieder
7 years ago
committed by