README (2616B)
1 Important notice: Hare's cryptography implementations have not been audited. You 2 can contribute to the funding of an independent audit of our cryptography 3 implementation on OpenCollective: 4 5 https://opencollective.com/hare/projects/cryptography-audit 6 7 The "crypto" module provides easy-to-use and hard-to-misuse functions for doing 8 various high-level cryptographic operations. This is the recommended approach 9 for most cryptographic applications. For applications which need them, direct 10 access to supported cryptographic primitives is provided in submodules. 11 12 Cryptography is a difficult, high-risk domain of programming. The life and 13 well-being of your users may depend on your ability to implement cryptographic 14 applications with due care. Please carefully read all of the documentation, 15 double-check your work, and seek second opinions and independent review of your 16 code. Our documentation and API design aims to prevent easy mistakes from being 17 made, but it is no substitute for a good background in applied cryptography. We 18 recommend the "Crypto 101" course as a good general introduction to 19 cryptography: 20 21 https://www.crypto101.io 22 23 There are a few additional modules and functions which are of interest to users 24 of the crypto module. Access to secure random data is provided by the 25 [[crypto::random::]] module. The ability to securely erase sensitive data in RAM 26 is provided by [[bytes::zero]]. Note also that [[bytes::equal]] is not suitable 27 for constant-time comparisons; equality comparisons in a cryptographic context 28 should utilize [[compare]] instead. 29 30 TODO: Add something based on mlock to deal with storing sensitive information, 31 and add a note here about it. 32 33 We reserve the right to make breaking changes to this module in the future, 34 which may prevent data prepared by old versions from being readable by new 35 versions. Such changes will be accompanied with an increment of the major 36 version of the standard library, as well as a changelog explaining what changes 37 are required of downstream users, and a migration procedure will be prepared. 38 The hare-announce mailing list is the appropriate way to be notified of these 39 changes: 40 41 https://lists.sr.ht/~sircmpwn/hare-announce 42 43 The following features are offered in this module: 44 45 - [[encrypt]] and [[decrypt]] provide authenticated encryption. 46 - [[sign]] and [[verify]] provide public key message signing and verification. 47 - [[exchange]] provides a secure key exchange function. 48 - [[derivekey]] implements key derivation, which is also recommended for hashing passwords. 49 - [[hash::]] provides a [[hash::hash]] algorithm suitable for cryptographic use.