lair_keystore/lib.rs
1// grrr clippy... you cannot specify extra bounds with the async fn syntax...
2#![allow(clippy::manual_async_fn)]
3// default implementations don't always make sense...
4#![allow(clippy::new_without_default)]
5#![deny(missing_docs)]
6#![deny(unsafe_code)]
7
8//! Secret lair private keystore
9//!
10//! [](http://holochain.org/)
11//! [](https://forum.holochain.org)
12//! [](https://chat.holochain.org)
13//!
14//! [](https://opensource.org/licenses/MIT)
15//! [](https://www.apache.org/licenses/LICENSE-2.0)
16//!
17//! This crate mostly provides the `lair-keystore` executable allowing
18//! initialization, configuration, and running of a Lair keystore.
19//!
20//! If you want to run an in-process keystore, this crate also provides the
21//! canonical sqlite store.
22//!
23//! For making use of a Lair keystore in a client application, see the
24//! [lair_keystore_api](https://crates.io/crates/lair_keystore_api) crate.
25//!
26//! # What is lair-keystore, and why does it exist?
27//!
28//! Lair Keystore is a general asymmetric cryptographic private key store
29//! project originally written for Holochain, but intended to be usable for
30//! any application.
31//!
32//! The store mainly tracks the "seed" data that for ed25519 and x25519 allow
33//! generation of keypairs, and can be thought of as synonymous with private
34//! keys.
35//!
36//! Lair allows derivation of this seed material for usage similar to HD
37//! wallets, with the intention that an end-user could create a "root" seed,
38//! from which could be deterministically derived a revocation seed and any
39//! number of device and application seeds, which would all be retrievable from
40//! a securely stored paper mnemonic of the root. (This has not yet been
41//! implemented in Holochain).
42//!
43//! Lair Keystore was originally intended to be a standalone binary.
44//! Given the overhead and security implications of having a process with access
45//! to private key material, it was originally envisioned that an end-user would
46//! run a single keystore on their system, and be prompted with a pin-entry UI
47//! that would unlock access to the private keys for a specified period of time,
48//! or every time an operation with a private key occurred in the case of "deep
49//! locked" seeds. (This has also not been implemented in Holochain, and
50//! moreover, Holochain has moved farther away from this intention by running
51//! Lair Keystore as an "in process" library which makes it easier to bundle
52//! executables).
53//!
54//! [lair_keystore_api::LairClient] is the main type that is used to access
55//! the keystore, and it mainly functions over an IPC connection (unix domain
56//! sockets on Linux and MacOs, and named pipes on Windows). This type allows
57//! you to create, access, export, and import tagged seeds, and then, using
58//! either those tags or the public keys that are derived from those seeds,
59//! perform signing, verification, encryption, and decryption operations.
60//!
61//! # Rust conventions for dashes and underscores:
62//!
63//! - Install with an underscore: `cargo install lair_keystore`
64//! - Use binary with a dash: `$ lair-keystore help`
65//! - Cargo.toml with an underscore:
66//!
67//! ```text
68//! [dependencies]
69//! lair_keystore = "0.1.1"
70//! ```
71//!
72//! - Library usage with underscores:
73//!
74//! ```
75//! use lair_keystore::*;
76//! ```
77//!
78//! # `lair-keystore` commandline executable usage:
79//!
80#![doc = include_str!("./docs/help.md")]
81#![doc = include_str!("./docs/init-help.md")]
82#![doc = include_str!("./docs/url-help.md")]
83#![doc = include_str!("./docs/import-seed-help.md")]
84#![doc = include_str!("./docs/server-help.md")]
85
86include!(concat!(env!("OUT_DIR"), "/ver.rs"));
87
88/// Re-exported dependencies.
89pub mod dependencies {
90 // Not sure why Clippy picks this up as unused, it's exported to be used elsewhere
91 #[allow(unused_imports)]
92 pub use hc_seed_bundle::dependencies::*;
93 pub use lair_keystore_api;
94 pub use lair_keystore_api::dependencies::*;
95 pub use rpassword;
96 pub use rusqlite;
97 pub use sysinfo;
98 pub use tracing_subscriber;
99}
100
101use dependencies::*;
102use lair_keystore_api::prelude::*;
103
104pub(crate) mod sql;
105
106pub mod pid_check;
107pub mod server;
108pub mod store_sqlite;
109
110#[doc(inline)]
111pub use store_sqlite::create_sql_pool_factory;