saymrwulf/curve25519-dalek-source
1
0
Fork 0
mirror of https://github.com/saymrwulf/curve25519-dalek-source.git synced 2026-09-04 20:24:10 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Update README.md with 2.x changes.

Browse source
This commit is contained in:
Henry de Valence 2019-10-25 15:58:41 -07:00
parent 4d735ed27a
commit be4cbe2af3
1 changed files with 17 additions and 24 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

41
README.md
View file

@ -45,7 +45,7 @@ make doc-internal
To import `curve25519-dalek`, add the following to the dependencies section of
your project's `Cargo.toml`:
```toml
curve25519-dalek = "1"
curve25519-dalek = "2"
```
Then import the crate as:
```rust,no_run
@ -59,17 +59,19 @@ compiler. **It is recommended for security**.
Curve arithmetic is implemented using one of the following backends:
* a `u32` backend using `u64` products;
* a `u64` backend using `u128` products;
* an `avx2` backend using [parallel formulas][parallel_doc], available
when compiling for a target with `target_feature=+avx2`.
* a `u32` backend using serial formulas and `u64` products;
* a `u64` backend using serial formulas and `u128` products;
* an `avx2` backend using [parallel formulas][parallel_doc] and `avx2` instructions (sets speed records);
* an `ifma` backend using [parallel formulas][parallel_doc] and `ifma` instructions (sets speed records);
By default the `u64` backend is selected. To select a specific backend, use:
```sh
cargo build --no-default-features --features "std u32_backend"
cargo build --no-default-features --features "std u64_backend"
# Requires RUSTFLAGS="-C target_feature=+avx2"
cargo build --no-default-features --features "std avx2_backend"
# Requires nightly, RUSTFLAGS="-C target_feature=+avx2" to use avx2
cargo build --no-default-features --features "std simd_backend"
# Requires nightly, RUSTFLAGS="-C target_feature=+avx512ifma" to use ifma
cargo build --no-default-features --features "std simd_backend"
```
Crates using `curve25519-dalek` can either select a backend on behalf of their
users, or expose feature flags that control the `curve25519-dalek` backend.
@ -79,13 +81,6 @@ builds using `--no-default-features`. Note that this requires explicitly
selecting an arithmetic backend using one of the `_backend` features.
If no backend is selected, compilation will fail.
The `yolocrypto` feature enables experimental features. The name `yolocrypto`
is meant to indicate that it is not considered production-ready, and we do not
consider `yolocrypto` features to be covered by semver guarantees.
This is designed to make it easier to test intended new features
without having to stabilise them first. Use `yolocrypto` at your own,
obvious, risk.
# Safety
The `curve25519-dalek` types are designed to make illegal states
@ -120,23 +115,21 @@ entrypoints of `curve25519-dalek` functions, but at the entrypoints of
functions in other crates.
The implementation is memory-safe, and contains no significant
`unsafe` code. The AVX2 backend uses `unsafe` internally to call AVX2
intrinsics. These are marked `unsafe` because invoking them on a
non-AVX2 target would cause `SIGILL`, but the entire backend is only
compiled for `target_feature=+avx2`. Some types implement an `unsafe
trait` to mark them as zeroable (for heap allocations), but this does
not affect memory safety.
`unsafe` code. The SIMD backend uses `unsafe` internally to call SIMD
intrinsics. These are marked `unsafe` because invoking them on an
inappropriate CPU would cause `SIGILL`, but the entire backend is only
compiled with appropriate `target_feature`s.
# Performance
Benchmarks are run using [`criterion.rs`][criterion]:
```sh
# You must set RUSTFLAGS to enable AVX2 support.
export RUSTFLAGS="-C target_cpu=native"
cargo bench --no-default-features --features "std u32_backend"
cargo bench --no-default-features --features "std u64_backend"
cargo bench --no-default-features --features "std avx2_backend"
# Uses avx2 or ifma only if compiled for an appropriate target.
export RUSTFLAGS="-C target_cpu=native"
cargo bench --no-default-features --features "std simd_backend"
```
Performance is a secondary goal behind correctness, safety, and
@ -191,7 +184,7 @@ The fast `u32` and `u64` scalar arithmetic was implemented by Andrew Moon, and
the addition chain for scalar inversion was provided by Brian Smith. The
optimised batch inversion was contributed by Sean Bowe and Daira Hopwood.
The `no_std` support was contributed by Tony Arcieri.
The `no_std` and `zeroize` support was contributed by Tony Arcieri.
Thanks also to Ashley Hauck, Lucas Salibian, and Manish Goregaokar for their
contributions.