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).
• (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 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_extension]s).

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: [ArtiNativeKeystore]s 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 versioning¹ guarantees: we might break them or remove them between patch versions.

• (None at present)