Keyring flows

Rust I/O-free library to manage keyring entries, based on keyring-rs.

Design

This library does not perform I/O the usual way. It relies instead on 3 concepts:

Flow

The flow is an I/O-free, composable and iterable state machine that emits I/O requests. A flow is considered terminated when it does not emit I/O requests anymore.

See available flows at ./src/flows.

Handler

The I/O handler contains all the I/O logic, and is responsible for processing I/O requests. It takes input from the flow, performs I/O, then puts the output back inside the flow.

See available handlers at ./src/handlers.

Loop

The loop is the glue between the flow and the I/O handler. It makes the flow progress while allowing handlers to process I/O.

Examples

See complete examples at ./examples.

Single use, synchronously

Flows are perfect for simple, single keyring usage:

use keyring_flows::{flows::*, handlers::std::Handler};

// update keyring entry secret
let mut write = Write::new("service", "user", "password");
while let Err(io) = write.next() {
    Handler::handle(&mut write, io).unwrap()
}

// read keyring entry secret
let mut read = Read::new("service", "user");
let secret = loop {
    match read.next() {
        Ok(secret) => secret,
	Err(io) => Handler::handle(&mut read, io).unwrap(),
    }
}

// delete keyring entry
let mut delete = Delete::new("service", "user", "password");
while let Err(io) = delete.next() {
    Handler::handle(&mut delete, io).unwrap()
}

Multiple use, synchronously

In case of multiple keyring usage, manipulating directly the keyring State is more advantageous:

use keyring_flows::{State, handlers::std::Handler};

let mut state = State::new(service, name);

// read keyring entry secret
Handler::read(&mut state).unwrap();
let secret = state.take_secret().unwrap();

// update keyring entry secret
state.set_secret(password);
Handler::write(&mut state).unwrap();

// delete keyring entry
Handler::delete(&mut state).unwrap();

See complete example at ./examples/crud.rs.

cargo run --example crud

More

Have a look at bigger projects built on the top of keyring flows:

• secret-flows

Sponsoring

Special thanks to the NLnet foundation and the European Commission that helped the project to receive financial support from various programs:

• NGI Assure in 2022
• NGI Zero Entrust in 2023
• NGI Zero Core in 2024 (still ongoing)

If you appreciate the project, feel free to donate using one of the following providers: