oo7 - ArchWiki

Jump to content

# oo7

From ArchWiki

Related articles

- GNOME/Keyring
- XDG Desktop Portal

oo7 is a D-Bus Secret Service provider written in Rust. It implements `org.freedesktop.secrets`, the freedesktop.org Secret Storage API, and is intended as a lightweight, cross-desktop replacement for gnome-keyring.

oo7 is developed as part of the linux-credentials project and is the native secret service for the COSMIC desktop environment.

## Security

### Protection against malicious application

Any application that can communicate with the session D-Bus bus can read any secret stored in the keyring. Only sandboxed applications (e.g. via Flatpak) have their access restricted.

See GNOME/Keyring#Protection against malicious application for the same considerations that apply to all `org.freedesktop.secrets` providers.

## Installation

Install the oo7 package. It provides `org.freedesktop.secrets` and conflicts with gnome-keyring, so only one can be installed at a time.

libsecret should also be installed so that applications can access the keyring through the standard libsecret API.

The package includes the following components:

- `oo7-daemon` — the Secret Service daemon implementing `org.freedesktop.secrets`
- `oo7-portal` — an XDG Desktop Portal backend for sandboxed applications
- `oo7-cli` — command-line interface to store and retrieve secrets
- `cargo-credential-oo7` — a Cargo credential provider for registry authentication
- `pam_oo7.so` — a PAM module for automatic keyring unlocking at login

### Starting the daemon

The daemon is started automatically via systemd user service on demand through D-Bus activation. To enable it to start at login, enable the `oo7-daemon.service` user unit.

## Manage using GUI

You can manage keyring contents using Seahorse; install the seahorse package. Seahorse uses libsecret and works with any `org.freedesktop.secrets` provider, including oo7.

## Using the keyring

The PAM module `pam_oo7.so` captures the user's login password during authentication and sends it to `oo7-daemon` via a Unix socket (`$XDG_RUNTIME_DIR/oo7-pam.sock`), unlocking the login keyring automatically.

### PAM step

Note To use automatic unlocking without automatic login, the password for the user account should be the same as the login keyring. See #Automatically change keyring password with user password.

When using a display manager, edit the appropriate PAM configuration file for your login manager.

For greetd (e.g. cosmic-greeter):

    /etc/pam.d/greetd

    #%PAM-1.0

    auth       required     pam_securetty.so
    auth       requisite    pam_nologin.so
    auth       include      system-local-login
    auth       optional     pam_oo7.so
    account    include      system-local-login
    session    include      system-local-login
    session    optional     pam_oo7.so

For console-based login (using getty):

    /etc/pam.d/login

    #%PAM-1.0

    auth       required     pam_securetty.so
    auth       requisite    pam_nologin.so
    auth       include      system-local-login
    auth       optional     pam_oo7.so
    account    include      system-local-login
    session    include      system-local-login
    session    optional     pam_oo7.so

The `auth optional pam_oo7.so` line captures the verified password, while `session optional pam_oo7.so` sends it to the daemon over the PAM socket.

### Automatically change keyring password with user password

Note This only affects the login keyring.

Append `password optional pam_oo7.so` to `/etc/pam.d/passwd`:

    /etc/pam.d/passwd

    #%PAM-1.0
    auth		include		system-auth
    account		include		system-auth
    password	include		system-auth
    password	optional	pam_oo7.so

### Unlocking without PAM (systemd-creds)

If you do not use a display manager with PAM, the daemon can automatically unlock the keyring using a credential stored in the user's systemd credential store. This requires systemd v258 or newer.

First, create an encrypted credential:

    $ mkdir -p ${XDG_CONFIG_HOME:-~/.config}/credstore.encrypted
    $ systemd-ask-password -n | systemd-creds encrypt --user --name=oo7.keyring-encryption-password - ${XDG_CONFIG_HOME:-~/.config}/credstore.encrypted/oo7.keyring-encryption-password

The service file already includes `ImportCredential=oo7.keyring-encryption-password`, so the daemon will load and decrypt the credential automatically at startup.

Warning Any user capable of reading the credential file and with access to the TPM (e.g. the root user) can decrypt the blob. Consider using systemd-homed with an encrypted home directory to mitigate this.

### Unlocking manually

To unlock the keyring manually from the command line:

    $ oo7-cli unlock -s "your_password"

Alternatively, start the daemon with the `--login` flag:

    $ /usr/lib/oo7-daemon --login --replace

The password is read from stdin.

## XDG Desktop Portal

oo7 includes an XDG Desktop Portal backend (`oo7-portal`) for sandboxed applications (e.g. Flatpak) to access secrets. However, the shipped portal file declares `UseIn=gnome` only, so it must be configured for other desktop environments.

### Configuring user-level Secrets Portal

Create a portals.conf override for your desktop environment. For example, for COSMIC (`$XDG_CURRENT_DESKTOP=COSMIC`):

    ~/.config/xdg-desktop-portal/cosmic-portals.conf

    [preferred]
    org.freedesktop.impl.portal.Secret=oo7-portal

For Sway:

    ~/.config/xdg-desktop-portal/sway-portals.conf

    [preferred]
    org.freedesktop.impl.portal.Secret=oo7-portal

Then restart the `xdg-desktop-portal.service` user unit.

### Modifying oo7-portal.portal

Alternatively, add your desktop environment to the `UseIn` key in `/usr/share/xdg-desktop-portal/portals/oo7-portal.portal`. Note that this modifies a package file and will be overwritten on package upgrades.

## Tips and tricks

### CLI usage

The `oo7-cli` command provides access to the keyring from the terminal.

Store a secret (read from stdin):

    $ echo "my_secret_value" | oo7-cli store "My Label" key1=value1 key2=value2

Retrieve a secret:

    $ oo7-cli lookup key1=value1

List all items:

    $ oo7-cli list

### Git integration

oo7 works with Git's libsecret credential helper, since libsecret uses the `org.freedesktop.secrets` D-Bus API.

Configure Git to use the libsecret helper:

    $ git config --global credential.helper /usr/lib/git-core/git-credential-libsecret

### Cargo credential provider

oo7 provides a credential helper for Cargo registry authentication:

    ~/.cargo/config.toml

    [registry]
    global-credential-providers = ["cargo-credential-oo7"]

### Locking the keyring

    $ dbus-send --session --dest=org.freedesktop.secrets \
       --type=method_call \
       /org/freedesktop/secrets \
       org.freedesktop.Secret.Service.Lock \
       array:objpath:/org/freedesktop/secrets/collection/login

### GnuPG integration

If you use Seahorse, you may want to set the GNOME 3 pinentry for passphrase prompts:

    ~/.gnupg/gpg-agent.conf

    pinentry-program /usr/bin/pinentry-gnome3

### Renaming a keyring

Keyring files are stored in `~/.local/share/keyrings/v1/`. The display name can be changed by editing the `display-name` value in the keyring file.

## Troubleshooting

### Resetting the keyring

Stop the `oo7-daemon.service` user unit and remove the keyring data:

    $ rm -rf ~/.local/share/keyrings/v1/

This permanently deletes all stored secrets. The keyring will be recreated on the next daemon start.

### No Process Capabilities, Insecure Memory Might Get Used

The daemon may log a warning about missing process capabilities, meaning secrets could be swapped to disk. To grant memory locking permissions:

    # setcap cap_ipc_lock=+ep /usr/lib/oo7-daemon

### Keyring is not locked when session is locked

Like other Secret Service providers, the keyring is not automatically locked when the desktop session is locked. Passwords remain in memory, which could be extracted via a DMA attack.

## See also

- oo7 documentation
- oo7 repository
- Secret Service Specification
- Packages providing org.freedesktop.secrets

Category:

- Security

oo7
Add topic