Debian Codegraph @

crypto/README

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