1# Project Wycheproof 2https://github.com/google/wycheproof 3 4*Project Wycheproof is named after 5[Mount Wycheproof](https://en.wikipedia.org/wiki/Mount_Wycheproof), the smallest 6mountain in the world. The main motivation for the project is to have a goal 7that is achievable. The smaller the mountain the more likely it is to be able to 8climb it.* 9 10[TOC] 11 12## Introduction 13 14Project Wycheproof tests crypto libraries against known attacks. It is developed 15and maintained by members of Google Security Team, but it is not an official 16Google product. 17 18At Google, we rely on many third party cryptographic software libraries. 19Unfortunately, in cryptography, subtle mistakes can have catastrophic 20consequences, and we found that libraries fall into such implementation 21pitfalls much too often and for much too long. Good implementation guidelines, 22however, are hard to come by: understanding how to implement cryptography 23securely requires digesting decades' worth of academic literature. We recognize 24that software engineers fix and prevent bugs with unit testing, and we found 25that cryptographic loopholes can be resolved by the same means. 26 27These observations have prompted us to develop Project Wycheproof, a collection 28of unit tests that detect known weaknesses or check for expected behaviors of 29some cryptographic algorithm. Project Wycheproof provides tests for most 30cryptographic algorithms, including RSA, elliptic curve crypto and 31authenticated encryption. Our cryptographers have systematically surveyed the 32literature and implemented most known attacks. We have over 80 test cases which 33have uncovered more than [40 bugs](doc/bugs.md). For 34example, we found that we could recover the private key of widely-used DSA and 35ECDHC implementations. 36 37While we are committed to develop as many attacks as possible, Project 38Wycheproof is by no means complete. Passing the tests does not imply that the 39library is secure, it just means that it is not vulnerable to the attacks that 40Project Wycheproof tests for. Cryptographers are also constantly discovering 41new attacks. Nevertheless, with Project Wycheproof developers and users now can 42check their libraries against a large number of known attacks, without having 43to spend years reading academic papers or become cryptographers themselves. 44 45For more information on the goals and strategies of Project Wycheproof, please 46check out our [doc](doc/). 47 48### Coverage 49 50Project Wycheproof has tests for the most popular crypto algorithms, including 51 52- AES-EAX 53- AES-GCM 54- [DH](doc/dh.md) 55- DHIES 56- [DSA](doc/dsa.md) 57- [ECDH](doc/ecdh.md) 58- ECDSA 59- ECIES 60- [RSA](doc/rsa.md) 61 62The tests detect whether a library is vulnerable to many attacks, including 63 64- Invalid curve attacks 65- Biased nonces in digital signature schemes 66- Of course, all Bleichenbacher’s attacks 67- And many more -- we have over 80 test cases 68 69Our first set of tests are written in Java, because Java has a common 70cryptographic interface. This allowed us to test multiple providers with a 71single test suite. While this interface is somewhat low level, and should not 72be used directly, we still apply a "defense in depth" argument and expect that 73the implementations are as robust as possible. For example, we consider weak 74default values to be a significant security flaw. We are converting as many 75tests into sets of test vectors to simplify porting the tests to other 76languages. We provide ready-to-use test runners for Java Cryptography 77Architecture providers such as [Bouncy Castle](http://bouncycastle.org), 78[Spongy Castle](https://rtyley.github.io/spongycastle/), and the default 79providers in [OpenJDK](http://openjdk.java.net/). 80 81### Usage 82 83- Install [Bazel](https://bazel.build/). 84 85- Install [Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction 86 Policy 87 Files](http://stackoverflow.com/questions/6481627/java-security-illegal-key-size-or-default-parameters): 88 this enables tests with large key sizes. Otherwise you'll see a lot of 89 "illegal key size" exceptions. 90 91- Check out the tests 92 93``` 94git clone https://github.com/google/wycheproof.git 95``` 96 97- To test latest stable version of Bouncy Castle: 98 99``` 100bazel test BouncyCastleAllTests 101``` 102 103- To test other versions, e.g., v1.52: 104 105``` 106bazel test BouncyCastleAllTests_1_52 107``` 108 109- To test all known versions (warning, will take a long time): 110 111``` 112bazel test BouncyCastleAllTests_* 113``` 114 115- To test a local jar, set the `WYCHEPROOF_BOUNCYCASTLE_JAR` environment 116 variable: 117 118```shell 119$ WYCHEPROOF_BOUNCYCASTLE_JAR=/path/to/bouncycastle 120$ bazel test BouncyCastleTestLocal 121$ bazel test BouncyCastleAllTestsLocal 122``` 123 124Note: bazel does not currently invalidate the build on environment changes. If 125you change the `WYCHEPROOF_BOUNCYCASTLE_JAR` environment variable, run `bazel 126clean` to force a rebuild: 127 128```shell 129$ WYCHEPROOF_BOUNCYCASTLE_JAR=/path/to/bouncycastle 130$ bazel test BouncyCastleTestLocal 131$ WYCHEPROOF_BOUNCYCASTLE_JAR=/path/to/other/jar 132$ bazel clean 133$ bazel test BouncyCastleTestLocal 134``` 135 136- To test [Spongy Castle](https://rtyley.github.io/spongycastle/), replace 137BouncyCastle with SpongyCastle in your commands, for example 138 139``` 140bazel test SpongyCastleAllTests 141``` 142 143- To test your current installation of 144[OpenJDK](http://openjdk.java.net/): 145 146``` 147bazel test OpenJDKAllTests 148``` 149 150Note that OpenJDKAllTests expects that OpenJDK is your default JDK, so it might 151refuse to run or its results might be incorrect if you are using some other JDK. 152If you downloaded your JDK from Oracle or https://java.com, you're probably 153using Oracle JDK, which should be compatible with OpenJDK, thus the tests should 154run correctly. 155 156Some tests take a very long time to finish. If you want to exclude them, use 157BouncyCastleTest, SpongyCastleTest or OpenJDKTest -- these targets exclude all 158slow tests (which are annotated with @SlowTest). 159 160Most test targets are failing, and each failure might be a security issue. To 161learn more about what a failed test means, you might want to check out [our 162documentation](doc/bugs.md) or the comments on top of the corresponding test 163function and test class. 164 165### Hall of Bugs 166 167Here are some of the notable vulnerabilities that are uncovered by 168Project Wycheproof: 169 170- OpenJDK's SHA1withDSA leaks private keys > 1024 bits 171 - Test: testBiasSha1WithDSA in 172[DsaTest](https://github.com/google/wycheproof/blob/master/java/com/google/security/wycheproof/testcases/DsaTest.java). 173 - This bug is the same as 174[CVE-2003-0971 - GnuPG generated ElGamal signatures that leaked the private key] 175(https://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-2003-0971). 176 177- Bouncy Castle's ECDHC leaks private keys 178 - Test: testModifiedPublic and testWrongOrderEcdhc in 179[EcdhTest](https://github.com/google/wycheproof/blob/master/java/com/google/security/wycheproof/testcases/EcdhTest.java). 180 181### Maintainers 182 183Project Wycheproof is maintained by: 184 185- Daniel Bleichenbacher 186- Thai Duong 187- Emilia Kasper 188- Quan Nguyen 189 190### Contact and mailing list 191 192If you want to contribute, please read [CONTRIBUTING](CONTRIBUTING.md) and send 193us pull requests. You can also report bugs or request new tests. 194 195If you'd like to talk to our developers or get notified about major new 196tests, you may want to subscribe to our 197[mailing list](https://groups.google.com/forum/#!forum/wycheproof-users). To 198join, simply send an empty mail to wycheproof-users+subscribe@googlegroups.com. 199