76 lines
3.0 KiB
Markdown
76 lines
3.0 KiB
Markdown
This is a pure Rust implementation of the ChaCha20-Poly1305 AEAD from
|
|
[RFC 7539].
|
|
|
|
[RFC 7539]: https://tools.ietf.org/html/rfc7539
|
|
|
|
## Design
|
|
|
|
There are two main designs for an encryption/decryption API: either
|
|
having one state/context struct with a method which is called repeatedly
|
|
to encrypt/decrypt the next fragment of data, or having a single
|
|
standalone function which is called once and does all the work in a
|
|
single call.
|
|
|
|
For authenticated encryption, it's important that on decryption no
|
|
output is produced until the authentication tag is verified. That
|
|
requires two passes over the data for decryption: the first pass
|
|
verifies the tag, and the second pass does the output. It would be
|
|
needlessly complex to implement this with a state/context struct, so
|
|
this crate uses a single function call to do the whole decryption. For
|
|
simmetry, the same design is used for the encryption function.
|
|
|
|
The base primitives (ChaCha20 and Poly1305) are not exposed separately,
|
|
since they are harder to use securely. This also allows their
|
|
implementation to be tuned to the combined use case; for instance, the
|
|
base primitives need no buffering.
|
|
|
|
## Limitations
|
|
|
|
The amount of data that can be encrypted in a single call is 2^32 - 1
|
|
blocks of 64 bytes, slightly less than 256 GiB. This limit could be
|
|
increased to 2^64 bytes, if necessary, by allowing the use of a shorter
|
|
nonce.
|
|
|
|
This crate does not attempt to clear potentially sensitive data from its
|
|
work memory (which includes the the stack and processor registers). To
|
|
do so correctly without a heavy performance penalty would require help
|
|
from the compiler. It's better to not attempt to do so than to present a
|
|
false assurance.
|
|
|
|
## SIMD optimization
|
|
|
|
This crate has experimental support for explicit SIMD optimizations. It
|
|
requires nightly Rust due to the use of unstable features.
|
|
|
|
The following cargo features enable the explicit SIMD optimization:
|
|
|
|
* `simd` enables the explicit use of SIMD vectors instead of a plain
|
|
struct
|
|
* `simd_opt` additionally enables the use of SIMD shuffles to implement
|
|
some of the rotates
|
|
|
|
While one might expect that each of these is faster than the previous
|
|
one, and that they are all faster than not enabling explicit SIMD
|
|
vectors, that's not always the case. It can vary depending on target
|
|
architecture and compiler options. If you need the extra speed from
|
|
these optimizations, benchmark each one (the `bench` feature enables
|
|
`cargo bench` in this crate, so you can use for instance `cargo bench
|
|
--features="bench simd_opt"`). They have currently been tuned for SSE2
|
|
(x86 and x86-64) and NEON (arm).
|
|
|
|
## License
|
|
|
|
Licensed under either of
|
|
|
|
* Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
|
|
* MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
|
|
|
|
at your option.
|
|
|
|
### Contribution
|
|
|
|
Unless you explicitly state otherwise, any contribution intentionally
|
|
submitted for inclusion in the work by you, as defined in the Apache-2.0
|
|
license, shall be dual licensed as above, without any additional terms or
|
|
conditions.
|