Skip to content
n-at-han-kPublic

About

Ruby bindings for oo7, the Rust Secret Service and keyring implementation.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

oo7-rb

Ruby bindings for oo7, the Rust implementation of the freedesktop Secret Service — the API behind GNOME Keyring and KWallet.

Why not libsecret

libsecret reaches the keyring through gnome-keyring's client library and libgcr, whose gcr_secret_exchange carries a secret back from an unlock prompt. oo7 speaks the D-Bus protocol itself and does its own cryptography, so a caller here loads neither.

That matters when a bug in those libraries is not yours to fix. A plain OpenSession should not be able to abort the process that made it, or the shell that prompted for it, but when it can, the way out is to stop going through them.

Installation

gem "oo7-rb"

The gem is oo7-rb; the library is oo7. RubyGems holds the name oo7 for an unrelated OO7, and a name differing only in case cannot be taken once the other has indexed versions -- so the gem took the repository's name instead. require "oo7" is the one to write, and require "oo7-rb" also works so that Bundler.require needs no require: of its own.

Usage

require "oo7"

keyring = Oo7::Keyring.new
keyring.unlock

keyring.create("My app: nathan on example.com", {
  "xdg:schema" => "com.example.App",
  "server" => "example.com",
  "user" => "nathan",
}, "the-secret", true)

item = keyring.search({"xdg:schema" => "com.example.App", "user" => "nathan"}).first
item.secret        # => "the-secret"
item.label         # => "My app: nathan on example.com"
item.attributes    # => {"xdg:schema" => "com.example.App", ...}

create's last argument replaces any item with the same attributes, which is what keeps a rotated secret one item rather than a pile of them.

Keyring

new, unlock, lock, locked?, items, search(attributes), create(label, attributes, secret, replace), delete(attributes).

Keyring.new picks the backend the way the crate does: the file backend when the process is sandboxed, the D-Bus Secret Service otherwise.

Item

label, label=, attributes, attributes=, secret, secret=, locked?, lock, unlock, delete, created, modified.

Blocking

Every method on the crate is async. Each binding drives it to completion on a Tokio runtime owned by the extension and returns the result, so the Ruby API is ordinary and synchronous.

The calling thread blocks and the GVL is held while it waits. A call that may raise a prompt therefore belongs on a Ruby thread rather than on a GTK main loop — otherwise the loop that owes the prompt a reply is the one being blocked.

Example

examples/gtk is a GTK4 window that stores, reads and deletes a secret without ever stopping. It has its own flake, because the shell above carries the Rust toolchain and none of the GTK stack and this one is the other way round:

nix develop --command rake compile      # in the repository root
cd examples/gtk && nix develop
ruby main.rb

Every call is on a thread and only the label update comes back through GLib::Idle, which is ordinary GTK practice. The ticking counter is what makes the point: it is driven by a timeout on the main loop, so it only advances while that loop is running. Press a button and watch it keep going.

Ordinary GTK practice is not sufficient on its own, which is the other half of why this gem exists. The GVL is global, so a worker thread that blocks while holding it stops the main thread as surely as calling on the main thread would. oo7 releases it; an extension that does not would make the thread pure decoration. test/oo7/concurrency.rb is the guard.

Development

bin/test                      # compile the extension, run the suite
bin/test --skip-compile       # suite only

The suite runs against the session's real Secret Service and skips itself when there isn't one. Items are written under an xdg:schema of oo7-rb-test with a per-run marker, and removed afterwards.

Licence

Apache-2.0. The oo7 crate itself is MIT.

About

Ruby bindings for oo7, the Rust Secret Service and keyring implementation.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages