2021-05-25 20:41:23 +01:00
|
|
|
# tor-llcrypto
|
|
|
|
|
|
|
|
`tor-llcrypto`: Low-level cryptographic implementations for Tor.
|
|
|
|
|
|
|
|
## Overview
|
|
|
|
|
2022-06-24 13:02:56 +01:00
|
|
|
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.
|
|
|
|
|
|
|
|
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.
|
2021-05-25 20:41:23 +01:00
|
|
|
|
|
|
|
### Why a separate crate?
|
|
|
|
|
2022-06-24 13:02:56 +01:00
|
|
|
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?
|
2021-05-25 20:41:23 +01:00
|
|
|
|
2022-06-24 13:02:56 +01:00
|
|
|
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.
|
2021-05-25 20:41:23 +01:00
|
|
|
|
|
|
|
### Adding to `tor-llcrypto`
|
|
|
|
|
2022-06-24 13:02:56 +01:00
|
|
|
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.
|
2021-05-25 20:41:23 +01:00
|
|
|
|
2022-06-24 13:02:56 +01:00
|
|
|
Cryptographic _traits_ (like those from RustCrypto) don't have to go in
|
|
|
|
`tor-llcrypto`, since they are interfaces rather than implementations.
|
2021-05-25 20:41:23 +01:00
|
|
|
|
|
|
|
## Contents
|
|
|
|
|
2022-06-24 13:02:56 +01:00
|
|
|
Encryption is implemented in [`cipher`]: Currently only AES is exposed or
|
|
|
|
needed.
|
2021-05-25 20:41:23 +01:00
|
|
|
|
2022-06-24 13:02:56 +01:00
|
|
|
Cryptographic digests are in [`d`]: The Tor protocol uses several digests in
|
|
|
|
different places, and these are all collected here.
|
2021-05-25 20:41:23 +01:00
|
|
|
|
|
|
|
Public key cryptography (including signatures, encryption, and key
|
2022-06-24 13:02:56 +01:00
|
|
|
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.
|
2021-05-25 20:41:23 +01:00
|
|
|
|
2022-06-24 13:02:56 +01:00
|
|
|
The [`util`] module has some miscellaneous compatibility utilities for
|
|
|
|
manipulating cryptography-related objects and code.
|
2021-05-25 20:41:23 +01:00
|
|
|
|
2021-11-29 11:29:28 +00:00
|
|
|
## Features
|
|
|
|
|
2022-06-24 13:02:56 +01:00
|
|
|
### API features
|
|
|
|
|
2021-11-29 11:29:28 +00:00
|
|
|
`relay` -- enable cryptography that's only used on relays.
|
|
|
|
|
2022-06-24 13:02:56 +01:00
|
|
|
`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.
|
2021-11-29 11:29:28 +00:00
|
|
|
|
2021-05-25 20:41:23 +01:00
|
|
|
License: MIT OR Apache-2.0
|