1# sha1cd
 2
 3A Go implementation of SHA1 with counter-cryptanalysis, which detects
 4collision attacks. 
 5
 6The `cgo/lib` code is a carbon copy of the [original code], based on
 7the award winning [white paper] by Marc Stevens.
 8
 9The Go and native implementations are largely based off upstream Go.
10
11## Usage
12
13`sha1cd` can be used as a drop-in replacement for `crypto/sha1`:
14
15```golang
16import "github.com/pjbgf/sha1cd"
17
18func test(){
19	data := []byte("data to be sha1 hashed")
20	h := sha1cd.Sum(data)
21	fmt.Printf("hash: %q\n", hex.EncodeToString(h))
22}
23```
24
25To obtain information as to whether a collision was found, use the
26func `CollisionResistantSum`.
27
28```golang
29import "github.com/pjbgf/sha1cd"
30
31func test(){
32	data := []byte("data to be sha1 hashed")
33	h, col  := sha1cd.CollisionResistantSum(data)
34	if col {
35		fmt.Println("collision found!")
36	}
37	fmt.Printf("hash: %q", hex.EncodeToString(h))
38}
39```
40
41Note that the algorithm will automatically avoid collision, by 
42extending the SHA1 to 240-steps, instead of 80 when a collision
43attempt is detected. Therefore, inputs that contains the unavoidable
44bit conditions will yield a different hash from `sha1cd`, when compared
45with results using `crypto/sha1`. Valid inputs will have matching the outputs.
46
47## References
48- https://shattered.io/
49- https://github.com/cr-marcstevens/sha1collisiondetection
50- https://csrc.nist.gov/Projects/Cryptographic-Algorithm-Validation-Program/Secure-Hashing#shavs
51
52## Use of the Original Implementation
53- https://github.com/git/git/commit/28dc98e343ca4eb370a29ceec4c19beac9b5c01e
54- https://github.com/libgit2/libgit2/pull/4136
55
56[original code]: https://github.com/cr-marcstevens/sha1collisiondetection
57[white paper]: https://marc-stevens.nl/research/papers/C13-S.pdf