Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 39 additions & 0 deletions client/src/file/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,45 @@
//! # Ok(())
//! # }
//! ```
//!
//! # File format
//!
//! Keyrings use the format of libsecret's file backend. A file starts with
//! the `GnomeKeyring\n\r\0\n` header, the major and minor versions as two
//! bytes (`1`, `0`), and a little-endian
//! [GVariant](https://docs.gtk.org/glib/struct.Variant.html) of type
//! `(uayutua(a{say}ay))`:
//!
//! | Type | Field |
//! | ------------- | --------------------------------------------- |
//! | `u` | salt size |
//! | `ay` | salt |
//! | `u` | PBKDF2 iteration count |
//! | `t` | modification time, in seconds since the epoch |
//! | `u` | usage count |
//! | `a(a{say}ay)` | items |
//!
//! Each item is a pair of:
//!
//! - `a{say}`: its attributes, mapping each name to the HMAC of its value, so
//! items can be searched without decrypting them.
//! - `ay`: the encrypted item, `ciphertext ‖ IV ‖ HMAC(ciphertext ‖ IV)`.
//!
//! Decrypted, an item is a `(a{ss}sttay)` GVariant holding its attributes,
//! label, creation and modification times, and secret.
//!
//! The key is derived from the password with PBKDF2-HMAC-SHA256, using at
//! least 100000 iterations and a 32 bytes salt. Items are encrypted with
//! AES-128-CBC, with PKCS#7 padding and a random IV, and the same key is used

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I misremember it was AES-256-CBC, but yes, this looks correct. That means we might want to update it to AES-256-CBC and SHA384 or SHA512 at some point to be compliant with CNSA 2.0 (i.e., PQC).

//! for HMAC-SHA256. These algorithms were chosen for being FIPS 140-3
//! approved.
//!
//! oo7 also supports keyrings without a password, which store attribute
//! values and items in plain text.
//!
//! gnome-keyring keyrings, in either its encrypted binary format or the plain
//! text one used for keyrings without a password, are migrated to this
//! format.

#[cfg(feature = "unstable")]
#[cfg_attr(docsrs, doc(cfg(feature = "unstable")))]
Expand Down
11 changes: 11 additions & 0 deletions server/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,17 @@ encrypted home with [systemd-homed](https://systemd.io/HOME_DIRECTORY/).

See the manual page `systemd.exec(5)` for more details.

## Storage

Keyrings are stored in `$XDG_DATA_HOME/keyrings/v1/`, using libsecret's file
format, see the [`oo7::file`][file-format] documentation. Keyrings left by
gnome-keyring in `$XDG_DATA_HOME/keyrings/` are migrated to it.

The format relies on PBKDF2-HMAC-SHA256, AES-128-CBC and HMAC-SHA256, which
were chosen for being FIPS 140-3 approved.

[file-format]: https://docs.rs/oo7/latest/oo7/file/index.html#file-format

## Debugging and Logs

When running `oo7-daemon` as a systemd user service, logs can be viewed using `journalctl`:
Expand Down
Loading