Skip to main content

Crate tor_keymgr

Crate tor_keymgr 

Source
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 given HiddenServiceDirectory directory (see HiddenServiceDirectory in tor(1)).
  • CTorClientKeystore (experimental): an on-disk keystore providing read-only access to the client restricted discovery keys rooted at a given ClientOnionAuthDir directory (see ClientOnionAuthDir in tor(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 ArtiPath of the specifier: this serves as a unique identifier for a particular instance of a key, and is used by ArtiNativeKeystore to determine the path of a key on disk
  • the CTorPath of 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 causes tor-keymgr to 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 support
  • onion-service-cli-extra – build with additional key and state management command line functionalities

  1. Remember, semantic versioning is what makes various cargo features work reliably. To be explicit: if you want cargo update to 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::ArtiPathUnavailableError;
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 🔒
ArtiPath and its associated helpers.
config
Configuration options for types implementing Keystore
err 🔒
An error type for the tor-keymgr crate.
key_specifier 🔒
The KeySpecifier trait and its implementations.
keystore 🔒
The Keystore trait 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_CertSpecifier
A helper for implementing KeyCertificateSpecifiers.
derive_deftly_template_KeySpecifier
A helper for implementing KeySpecifiers.
register_key_info_extractor
Register a KeyPathInfoExtractor for use with KeyMgr.

Structs§

KeystoreId
An identifier for a particular Keystore instance.
SshKeyData
A public key or a keypair.

Enums§

KeyType
A type of key stored in the key store.
KeystoreSelector
Specifies which keystores a KeyMgr operation should apply to.
SshKeyAlgorithm
SSH key algorithms.

Traits§

EncodableItem
A key that can be serialized to, and deserialized from.
Keygen
A trait for generating fresh keys.
KeygenRng
A random number generator for generating EncodableItems.
ToEncodableKey
A key that can be converted to an EncodableItem.

Type Aliases§

BoxedKeystore 🔒
A boxed Keystore.
ErasedKey
A type-erased key. Used by the tor-keymgr.
Result
A Result type for this crate.