Keyring

This document provides a high-level introduction to a Rust-language application and programming infrastructure known as the keyring. All keyring users should read this introduction, which is written for programmer and non-programmer alike.

Secrets

As long as there have been computers, those computers have been storing (and trying to protect) secrets, from passwords to encryption keys to personal information about users. There are literally thousands of programs on the market whose primary job is to keep their user’s secrets both safe from prying eyes and accessible to the right eyes when needed. So great is the need for secure, unguessable secrets in all aspects of our daily life, that password keepers—programs that help you invent and organize your passwords—have become indispensable for all computer and mobile device users.

In any program that makes use of secrets, there are three main layers:

• The user interface layer.
• The naming/organization system for secrets.
• The secure storage system for secrets.

The goal of the keyring infrastructure is to provide a plug-and-play system of components that handle the bottom two of these three layers, leaving programmers free to focus on the interface layer in what they are building.

Naming Secrets

A common approach to naming secrets is to use the answers to two questions: who wants the secret, and who owns the secret?

• The entity wanting the secret is typically an application of some kind. For example, this might be an interactive website or an app that descrypts and displays an encrypted document.
• The entity owning the secret is typically an account belonging to the person who made up the secret. For example, this might be the login name for a website or a person’s email address.

Keyring uses this approach to naming secrets, calling the answer to the “who wants it” question the service and the answer to the “who owns it” question the user. The standard term used by all keyring software for a “named secret” is an entry, so each entry is identified by its service and its user, both of which are strings.

Storing Secrets

In computer jargon, labeled secrets are often called credentials, so the systems that store them are called credential stores. Credential stores are typically full-fledged password keepers in their own right, having their own user interface (for authenticating users and getting permission to share passwords), their own way of labeling/organizing secrets, and their own secure storage system. In addition, most credential stores offer an API layer that allows other applications to use them for password storage.

The keyring infrastructure works by standardizing an API for talking to credential stores. First, a developer builds a credential-store module for keyring which bridges the gap between the keyring-standard API and a specific credential store’s API. Once that’s done, all keyring client programs can use that module to store their entries in that credential store.

Keyring credential-store modules exist for the built-in OS credential managers on Mac, Win, Linux, and Android, and also for the Secret Service API which is implemented by many password keepers on many OSes. The latest release of the keyring CLI should always contain an up-to-date list of available stores.

The Keyring Ecosystem

The keyring ecosystem has three parts:

• The keyring sample applications, described further in this document, provide the ability to store and retrieve secrets from any keyring-compatible credential store. These applications include a Rust-based command-line interface (sources here), a Python module (sources here), and a Tauri v2-based Keyring Demo application (sources here, iOS/macOS beta here, Android beta available by sending email to keyring-demo at brotsky.com).
• The keyring-core module, described further in this document, which provides the keyring APIs used to build both client applications which create and use entries and the credential stores which keep them safe.
• The keyring-compatible credential stores, which provide the secure storage for keyring-based applications. As mentioned above, the latest release of the Rust-based CLI should contain an up-to-date list of the credential stores available for use in keyring-based applications.

Developers of client applications that use the keyring will be most interested in the keyring applications (for testing purposes) and the client API in the keyring-core. They may also use one of the keyring applications to diagnose credential problems encountered in the field.

Developers of credential store modules for the keyring will be most interested in the keyring applications (for testing purposes) and the credential storage APIs in the keyring-core. Once their credential stores are ready for use, they should submit a PR to the keyring CLI repo that makes their store available in the application.