| 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. |