Expand description
§tor-keymgr
Code to fetch, store, and update keys.
§Overview
This crate is part of Arti, a project to implement Tor in Rust.
§Likely to change
The APIs exposed by this crate (even without the keymgr feature)
are new and are likely to change rapidly.
We’ll therefore often be making semver-breaking changes
(and will update the crate version accordingly).
§Key stores
The KeyMgr is an interface to one or more key stores. A key
store is a type that implements the Keystore trait.
The following key store implementations are provided:
ArtiNativeKeystore: an on-disk store that stores keys in OpenSSH format. It does not currently support keys that have a passphrase. Passphrase support will be added in the future (see #902).CTorServiceKeystore(experimental): an on-disk keystore providing read-only access to the hidden service keys rooted at a givenHiddenServiceDirectorydirectory (seeHiddenServiceDirectoryintor(1)).CTorClientKeystore(experimental): an on-disk keystore providing read-only access to the client restricted discovery keys rooted at a givenClientOnionAuthDirdirectory (seeClientOnionAuthDirintor(1)).
In the future we plan to also support HSM-based key stores.
§Key specifiers and key types
The Keystore APIs identify a particular instance of a key using a
KeySpecifier and a KeyType.
This enables key stores to have multiple keys with the same role
(i.e. the same KeySpecifier::arti_path), but different key types (i.e.
different KeyType::arti_extensions).
A KeySpecifier identifies a group of equivalent keys, each of a different
type (algorithm). In the ArtiNativeKeystore, it is used to determine the
path of the key within the key store, minus the extension (the extension of
the key is derived from its KeyType). KeySpecifier implementers must
specify:
- the
ArtiPathof the specifier: this serves as a unique identifier for a particular instance of a key, and is used byArtiNativeKeystoreto determine the path of a key on disk - the
CTorPathof the key: the location of the key in the C Tor key store (optional).
KeyType represents the type (“keypair”, “public key”) and
algorithm (“ed25519”, “x25519”) of a key
KeyType::arti_extension specifies what file extension keys of that type are
expected to have when stored in an ArtiNativeKeystore: ArtiNativeKeystores
join the KeySpecifier::arti_path and KeyType::arti_extension to form the
path of the key on disk (relative to the root directory of the key store).
§Feature flags
§Additive features
keymgr– build with full key manager support. Disabling this feature causestor-keymgrto export a no-op, placeholder implementation.
§Experimental and unstable features
Note that the APIs enabled by these features are NOT covered by semantic versioning1 guarantees: we might break them or remove them between patch versions.
ephemeral-keystore– build with ephemeral keystore supportonion-service-cli-extra– build with additional key and state management command line functionalities
Remember, semantic versioning is what makes various
cargofeatures work reliably. To be explicit: if you wantcargo updateto only make safe changes, then you cannot enable these features. ↩
Re-exports§
pub use arti_path::ArtiPath;pub use arti_path::DENOTATOR_GROUP_SEP;pub use arti_path::DENOTATOR_SEP;pub use err::ArtiPathSyntaxError;pub use err::Error;pub use err::KeystoreCorruptionError;pub use err::KeystoreError;pub use err::UnknownKeyTypeError;pub use err::UnrecognizedEntry;pub use err::UnrecognizedEntryError;pub use key_specifier::ArtiPathError;pub use key_specifier::ArtiPathRange;pub use key_specifier::CTorKeySpecifier;pub use key_specifier::CTorPath;pub use key_specifier::CTorPathError;pub use key_specifier::InvalidKeyPathComponentValue;pub use key_specifier::KeyCertificateSpecifier;pub use key_specifier::KeyPath;pub use key_specifier::KeyPathError;pub use key_specifier::KeyPathInfo;pub use key_specifier::KeyPathInfoBuilder;pub use key_specifier::KeyPathInfoExtractor;pub use key_specifier::KeyPathPattern;pub use key_specifier::KeySpecifier;pub use key_specifier::KeySpecifierComponent;pub use key_specifier::KeySpecifierComponentViaDisplayFromStr;pub use key_specifier::KeySpecifierPattern;pub use raw::RawEntryId;pub use key_specifier::CertSpecifierPattern;pub use keystore::arti::ArtiNativeKeystore;pub use keystore::ctor::CTorClientKeystore;pub use keystore::ctor::CTorServiceKeystore;pub use keystore::Keystore;pub use keystore::KeystoreEntryResult;pub use mgr::KeyMgr;pub use mgr::KeyMgrBuilder;pub use mgr::KeyMgrBuilderError;pub use mgr::KeystoreEntry;pub use ssh_key;pub use keystore::ephemeral::ArtiEphemeralKeystore;pub use ssh_key;pub(crate) use AsRef;🔒pub(crate) use Display;🔒pub(crate) use From;🔒pub(crate) use Deserialize;🔒pub(crate) use Deserialize;🔒pub(crate) use Serialize;🔒pub(crate) use Serialize;🔒pub(crate) use std::str::FromStr;🔒
Modules§
- arti_
path 🔒 ArtiPathand its associated helpers.- config
- Configuration options for types implementing
Keystore - err 🔒
- An error type for the
tor-keymgrcrate. - key_
specifier 🔒 - The
KeySpecifiertrait and its implementations. - keystore 🔒
- The
Keystoretrait and its implementations. - mgr 🔒
- Code for managing multiple
Keystores. - raw 🔒
- Raw keystore entry identifiers used in plumbing CLI functionalities.
- test_
utils - Test helpers.
Macros§
- derive_
deftly_ template_ Cert Specifier - A helper for implementing
KeyCertificateSpecifiers. - derive_
deftly_ template_ KeySpecifier - A helper for implementing
KeySpecifiers. - register_
key_ info_ extractor - Register a
KeyPathInfoExtractorfor use withKeyMgr.
Structs§
- Keystore
Id - An identifier for a particular
Keystoreinstance. - SshKey
Data - A public key or a keypair.
Enums§
- KeyType
- A type of key stored in the key store.
- Keystore
Selector - Specifies which keystores a
KeyMgroperation should apply to. - SshKey
Algorithm - SSH key algorithms.
Traits§
- Encodable
Item - A key that can be serialized to, and deserialized from.
- Keygen
- A trait for generating fresh keys.
- Keygen
Rng - A random number generator for generating
EncodableItems. - ToEncodable
Key - A key that can be converted to an
EncodableItem.
Type Aliases§
- Boxed
Keystore 🔒 - A boxed
Keystore. - Erased
Key - A type-erased key. Used by the tor-keymgr.
- Result
- A Result type for this crate.