You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

README.md 4.6KB

4 years ago
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111
  1. # Introduction
  2. CryptCheck is a Ruby toolbox that help anybody to check for cryptography security
  3. level and best practices compliance.
  4. CryptCheck is released under
  5. [AGPLv3+](https://www.gnu.org/licenses/agpl-3.0.en.html) license.
  6. # Preliminary warning
  7. **/!\ This tool use custom weak builds of OpenSSL library and OpenSSL Ruby extension /!\**.
  8. Those builds are cryptographically weaken to be able to test for (very) weak and
  9. today totally deprecated ciphers.
  10. Don’t deploy it on production machine to avoid any security troubles, or use VM
  11. to isolate them !
  12. # Setup
  13. ## Ruby
  14. You need a fully operationnal Ruby stack.
  15. Because of the warning above, don’t use your system Ruby.
  16. I recommend to use [RBEnv](https://github.com/sstephenson/rbenv) and it
  17. [Ruby-build](https://github.com/sstephenson/ruby-build) plugin to build a new
  18. ruby environment instead of your system one.
  19. Currently supported Ruby stack is v2.2.2.
  20. ## OpenSSL library and Ruby extension
  21. To be able to test for (very) weak ciphers and to have access to DH parameters,
  22. CryptCheck need custom build of OpenSSL library and patched build of OpenSSL Ruby
  23. extension.
  24. Once you have cloned CryptCheck repository, just run `make` inside to
  25. build the needed libraries.
  26. If `make` fails with the following error :
  27. ```
  28. make: *** No rule to make target 'lib/libssl.so.1.0.0', needed by 'libs'. Stop.
  29. ```
  30. just run again `make` (if you understand this problem, contact me !).
  31. The built libraries (*libcrypto.so*, *libssl.so* and *openssl.so*) are located
  32. under the *lib* directory.<br/>
  33. CryptCheck use *LD_LIBRARY_PATH* and Ruby load path hack to inject those weaken
  34. libraries instead of the system ones.
  35. ## Ruby dependencies
  36. CryptCheck relies on few Ruby libraries, managed with [Bundler](http://bundler.io/).
  37. To fetch and install them, just run `bundle install`.
  38. # Usage
  39. Simply run the corresponding runner of what you want to test :
  40. * HTTPS : ```bin/check_https example.org```
  41. * XMPP : ```bin/check_xmpp example.org```
  42. * SMTP : ```bin/check_smtp example.org```
  43. If you want more information of what is going on under the hood, run the command
  44. with debug enabled, like ```bin/check_https example.org debug```
  45. ## Understanding results
  46. Rank goes from "A+" (perfect) to "F" (very weak).<br/>
  47. "M" means your certificate and your hostname mismatch.<br/>
  48. "T" means your certificate is not issued by a valid root certificate authority.
  49. Only a perfect setup gets a perfect score and a "A" rank :).<br/>
  50. "A" score is based on [RFC 7525](https://tools.ietf.org/html/rfc7525) recommandations.
  51. * Protocol
  52. * SSL (v2 and v3) are totally [deprecated](https://tools.ietf.org/html/rfc7568)
  53. now, because of very serious known vulnerabilities
  54. ([Poodle](https://www.openssl.org/~bodo/ssl-poodle.pdf)…).
  55. Using one of them cap your rank to "F".
  56. * TLSv1 and TLSv1.1 suffer of the
  57. [Poodle TLS](https://community.qualys.com/blogs/securitylabs/2014/12/08/poodle-bites-tls)
  58. vulnerability.
  59. * TLSv1.2 is the only remaining protocol with no known vulnerabilities, so if
  60. you don’t support it, your rank is cap to "B".
  61. * Key size
  62. * If you use certificate key less than 2048 bits, your rank is cap to "B".
  63. * Ciphers
  64. * Very weak ciphers, including MD5 hash, anonymous DH parameters, NULL ciphers
  65. (yes, it exits…), export ciphers ([Freak](https://freakattack.com/)) or weak
  66. ciphers (RC4, DES…) cap your rank to "F".
  67. * 3DES is considered weak and must be avoided, using it cap your score to "C".
  68. * Score
  69. * Protocol score is based on the **weakest** protocol you support :<br/>
  70. SSLv2 = 0, SSLv3 = 20, TLSv1 = 60, TLSv1.1 = 80, TLSv1.2 = 100.
  71. * Key score is based on your certificate key size :<br/>
  72. <512 = 10, <1024 = 20, <2048 = 50, <4096 = 90, ≥4096 = 100.
  73. * Cipher score is based on the **weakest** cipher you support :<br/>
  74. 0 = 0, <112 = 10, <128 = 50, <256 = 90, ≥256 = 100.
  75. * Overall score is based on the other scores :<br/>
  76. overall = 0.3 * protocol + 0.3 * key + 0.4 * cipher
  77. * Best practices
  78. * PFS : you gain this flag when you support **only**
  79. [perfect forward secrecy](https://en.wikipedia.org/wiki/Forward_secrecy)
  80. ciphers (DHE or ECDHE)
  81. * HSTS : you gain this flag when you protect yourself with
  82. [HTTP Strict Transport Security](https://tools.ietf.org/html/rfc6797).
  83. * Long HSTS : you gain this flag when you support HSTS with a duration of at
  84. least 6 monthes.
  85. * Rank
  86. * Rank is based on your overall score and above caps :<br/>
  87. <20 = F, <35 = E, <50 = D, <65 = C, <80 = B, ≥80 = A.
  88. * If you get an "A" and you have all the best practices above, you get "A+".