Crate tor_keymgr

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. The key stores are types that implement the Keystore trait.

This crate provides the following key store implementations:

• Arti key store: an on-disk store that stores keys in OpenSSH format.
• (not yet implemented) C Tor key store: an on-disk store that is backwards-compatible with C Tor (new keys are stored in the format used by C Tor, and any existing keys are expected to be in this format too).

In the future we plan to also support HSM-based key stores.

Key specifiers and key types

The Keystore APIs expect a “key specifier” (specified for each supported key type via the KeySpecifier trait), and a KeyType.

A “key specifier” identifies a group of equivalent keys, each of a different type (algorithm). It is used to determine the path of the key within the key store (minus the extension).

KeyType represents the type of a key (e.g. “Ed25519 keypair”). KeyType::arti_extension specifies what file extension keys of that type are expected to have (when stored in an Arti store).

The KeySpecifier::arti_path and KeyType::arti_extension are joined to form the path of the key on disk (relative to the root dir of the key store). This enables the 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).

KeySpecifier implementers must specify:

• arti_path: the location of the key in the Arti key store. This also serves as a unique identifier for a particular instance of a key.
• ctor_path: the location of the key in the C Tor key store (optional).

Feature flags

Additive features

(None yet.)

Experimental and unstable features

Note that the APIs enabled by these features are NOT covered by semantic versioning¹ guarantees: we might break them or remove them between patch versions.

• keymgr – build with full key manager support. Disabling this feature causes tor-keymgr to export a no-op, placeholder implementation.

---

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 ssh_key;
  keymgr

Modules

• config
  Keystore configuration.
• test_utilstesting
  Test helpers.

Macros

• derive_adhoc_template_KeySpecifier
  A helper for implementing KeySpecifiers.
• register_key_info_extractor
  Register a KeyInfoExtractor for use with KeyMgr.

Structs

• ArtiNativeKeystorekeymgr
  The Arti key store.
• ArtiPath
  A unique identifier for a particular instance of a key.
• CTorPath
  The path of a key in the C Tor key store.
• KeyMgrkeymgr
  A key manager that acts as a frontend to a default Keystore and any number of secondary Keystores.
• KeyMgrBuilderkeymgr
  Builder for KeyMgr.
• KeyPathInfo
  Information about a KeyPath.
• KeyPathInfoBuilder
  Builder for KeyPathInfo.
• KeyPathRange
  A range specifying a substring of a KeyPath.
• KeystoreId
  An identifier for a particular Keystore instance.
• UnknownKeyTypeErrorkeymgr
  An error that happens when we encounter an unknown key type.

Enums

• ArtiPathSyntaxError
  An error caused by a syntactically invalid ArtiPath.
• ArtiPathUnavailableError
  An error returned by a KeySpecifier.
• Error
  An Error type for this crate.
• KeyPath
  The identifier of a key.
• KeyPathError
  An error while attempting to extract information about a key given its path
• KeyPathPattern
  A pattern that can be used to match ArtiPaths or CTorPaths.
• KeyTypekeymgr
  A type of key stored in the key store.
• KeystoreCorruptionError
  An error caused by keystore corruption.
• KeystoreSelector
  Specifies which keystores a KeyMgr operation should apply to.
• SshKeyDatakeymgr
  A public key or a keypair.

Constants

• DENOTATOR_SEP
  A separator for that marks the beginning of the keys denotators within an ArtiPath.

Traits

• EncodableKeykeymgr
  A key that can be serialized to, and deserialized from, a format used by a Keystore.
• KeyInfoExtractor
  A trait for extracting info out of a KeyPaths.
• KeySpecifier
  The “specifier” of a key, which identifies an instance of a key.
• KeySpecifierComponent
  A trait for serializing and deserializing specific types of Slugs.
• KeySpecifierComponentViaDisplayFromStr
  Implement KeySpecifierComponent in terms of Display and FromStr (helper trait)
• KeySpecifierPattern
  A pattern specifying some or all of a kind of key
• Keygenkeymgr
  A trait for generating fresh keys.
• KeygenRngkeymgr
  A random number generator for generating EncodableKeys.
• Keystorekeymgr
  A generic key store.
• KeystoreError
  An error returned by a Keystore.
• ToEncodableKeykeymgr
  A key that can be converted to an EncodableKey.

Type Aliases

• ErasedKeykeymgr
  A type-erased key returned by a Keystore.
• Result
  A Result type for this crate.