diff --git a/Cargo.lock b/Cargo.lock index bad194edd..695725121 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -2931,6 +2931,16 @@ dependencies = [ "cfg-if 1.0.0", "cpufeatures", "digest 0.10.3", + "sha1-asm", +] + +[[package]] +name = "sha1-asm" +version = "0.5.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "563d4f7100bc3fce234e5f37bbf63dc2752558964505ba6ac3f7204bdc59eaac" +dependencies = [ + "cc", ] [[package]] diff --git a/crates/tor-llcrypto/Cargo.toml b/crates/tor-llcrypto/Cargo.toml index 04eca4d6e..167a8e354 100644 --- a/crates/tor-llcrypto/Cargo.toml +++ b/crates/tor-llcrypto/Cargo.toml @@ -14,6 +14,7 @@ repository = "https://gitlab.torproject.org/tpo/core/arti.git/" [features] default = [] with-openssl = ["openssl", "typenum", "cipher"] +with-sha1-asm = ["sha-1/asm"] # Enable support for cryptography needed to be a Tor relay. relay = [] diff --git a/crates/tor-llcrypto/src/lib.rs b/crates/tor-llcrypto/src/lib.rs index 31c9059e8..48f976ab5 100644 --- a/crates/tor-llcrypto/src/lib.rs +++ b/crates/tor-llcrypto/src/lib.rs @@ -2,67 +2,76 @@ //! //! # Overview //! -//! The `tor-llcrypto` crate wraps lower-level cryptographic -//! primitives that Tor needs, and provides a few smaller pieces of -//! cryptographic functionality that are commonly required to -//! implement Tor correctly. +//! The `tor-llcrypto` crate wraps lower-level cryptographic primitives that Tor +//! needs, and provides a few smaller pieces of cryptographic functionality that +//! are commonly required to implement Tor correctly. //! -//! This crate is part of -//! [Arti](https://gitlab.torproject.org/tpo/core/arti/), a project to -//! implement [Tor](https://www.torproject.org/) in Rust. -//! Many other crates in Arti depend on it. +//! This crate is part of [Arti](https://gitlab.torproject.org/tpo/core/arti/), +//! a project to implement [Tor](https://www.torproject.org/) in Rust. Many +//! other crates in Arti depend on it. //! -//! You probably wouldn't want to use this crate for implementing -//! non-Tor-based protocols; instead you should probably use the other -//! crates that it depends on if you have a low-level protocol to -//! implement, or a higher-level cryptographic system if you want to -//! add security to something else. It is easy to accidentally put -//! these functions together in ways that are unsafe. +//! You probably wouldn't want to use this crate for implementing non-Tor-based +//! protocols; instead you should probably use the other crates that it depends +//! on if you have a low-level protocol to implement, or a higher-level +//! cryptographic system if you want to add security to something else. It is +//! easy to accidentally put these functions together in ways that are unsafe. //! //! ## Why a separate crate? //! -//! Why do we collect and re-export our cryptography here in -//! `tor-llcrypto`, instead of having the different crates in Arti use -//! underlying cryptographic crates directly? +//! Why do we collect and re-export our cryptography here in `tor-llcrypto`, +//! instead of having the different crates in Arti use underlying cryptographic +//! crates directly? //! -//! By wrapping our cryptography in this crate, we ensure that we're -//! using the same implementations across our ecosystem, and provide -//! a single place to upgrade and test our cryptography. +//! By wrapping our cryptography in this crate, we ensure that we're using the +//! same implementations across our ecosystem, and provide a single place to +//! upgrade and test our cryptography. //! //! ## Adding to `tor-llcrypto` //! -//! Any low-level cryptographic algorithm that is used by at least two -//! other crates in Arti is a candidate for inclusion in -//! `tor-llcrypto`, especially if that algorithm's purpose is not -//! specific to any single piece of the Tor algorithm. +//! Any low-level cryptographic algorithm that is used by at least two other +//! crates in Arti is a candidate for inclusion in `tor-llcrypto`, especially if +//! that algorithm's purpose is not specific to any single piece of the Tor +//! algorithm. //! -//! Cryptographic _traits_ (like those from RustCrypto) don't have to -//! go in `tor-llcrypto`, since they are interfaces rather than -//! implementations. +//! Cryptographic _traits_ (like those from RustCrypto) don't have to go in +//! `tor-llcrypto`, since they are interfaces rather than implementations. //! //! # Contents //! -//! Encryption is implemented in [`cipher`]: Currently only AES is -//! exposed or needed. +//! Encryption is implemented in [`cipher`]: Currently only AES is exposed or +//! needed. //! -//! Cryptographic digests are in [`d`]: The Tor protocol uses several -//! digests in different places, and these are all collected here. +//! Cryptographic digests are in [`d`]: The Tor protocol uses several digests in +//! different places, and these are all collected here. //! //! Public key cryptography (including signatures, encryption, and key -//! agreement) are in [`pk`]. Older parts of the Tor protocol require -//! RSA; newer parts are based on Curve25519 and Ed25519. There is -//! also functionality here for _key manipulation_ for the keys used -//! in these symmetric algorithms. +//! agreement) are in [`pk`]. Older parts of the Tor protocol require RSA; +//! newer parts are based on Curve25519 and Ed25519. There is also functionality +//! here for _key manipulation_ for the keys used in these symmetric algorithms. //! -//! The [`util`] module has some miscellaneous compatibility utilities -//! for manipulating cryptography-related objects and code. +//! The [`util`] module has some miscellaneous compatibility utilities for +//! manipulating cryptography-related objects and code. //! //! # Features //! +//! ## API features +//! //! `relay` -- enable cryptography that's only used on relays. //! -//! `hsv3-client` -- enable cryptography that's only needed when running -//! as a v3 onion service client. +//! `hsv3-client` -- enable cryptography that's only needed when running as a v3 +//! onion service client. +//! +//! ## Acceleration features +//! +//! These features should never be enabled by default from libraries, since they +//! are not "strictly additive": they disable one implementation in order to +//! enable another. +//! +//! `with-openssl` -- Use `openssl` as the backend for those cryptographic +//! features it supports. +//! +//! `with-sha1-asm` -- Use an assembly implementation of the sha1 algorithm, if +//! one is enabled. // @@ begin lint list maintained by maint/add_warning @@ #![deny(missing_docs)]