From 98e399c0930857aa11afeea1d26e61affc63698a Mon Sep 17 00:00:00 2001 From: Isaiah Inuwa Date: Wed, 13 Aug 2025 12:46:04 -0500 Subject: [PATCH 1/5] Update names in README. --- README.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index ee05686d..2473ede0 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,8 @@ -🚧 Excuse the mess, work in progress! 🚧 +# credentialsd -# Linux Credential Manager API +A Linux Credential Manager API. + +(Previously called `linux-webauthn-platform-api`.) ## How to run @@ -17,6 +19,8 @@ Package requirements: - libudev - desktop-file-utils +Using the web extension also requires `python3-dbus-next`. + For example, on Ubuntu: ```shell @@ -34,8 +38,8 @@ sudo apt update && sudo apt install \ ### Compiling ```shell -git clone https://github.com/linux-credentials/linux-webauthn-platform-api -cd linux-webauthn-platform-api +git clone https://github.com/linux-credentials/credentialsd +cd credentialsd meson setup build -Dprofile=development ninja -C build ``` From 1ca720e6143e170af7168643eee5b49d2abf3d38 Mon Sep 17 00:00:00 2001 From: Isaiah Inuwa Date: Wed, 13 Aug 2025 12:46:04 -0500 Subject: [PATCH 2/5] Move goals to a separate file. --- GOALS.md | 55 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 54 +++--------------------------------------------------- 2 files changed, 58 insertions(+), 51 deletions(-) create mode 100644 GOALS.md diff --git a/GOALS.md b/GOALS.md new file mode 100644 index 00000000..c2709dc2 --- /dev/null +++ b/GOALS.md @@ -0,0 +1,55 @@ +# Goals + +The goal of this repository is to define a spec for clients (apps, browsers, +etc.) to retrieve user credentials in a uniform way across Linux desktop +environments. + +Some high-level goals: + +- define an API to securely create and retrieve local credentials + (passwords, passkeys, security keys) +- create and retrieve credentials on remote devices (e.g. via CTAP 2 BLE/hybrid + transports) +- Provide a uniform interface for third-party credential providers + (password/passkey managers like GNOME Secrets, Bitwarden, Keepass, LastPass, + etc.) to hook into + +Some nice-to-haves: + +- Design a specification for a platform authenticator. I'm not sure whether this + needs to be specified, or whether it could be considered and implemented as a + first-party credential provider. +- A security key manager (e.g., for setting security key client PIN) + +Some non-goals: + +- Fully integrate with any specific desktop environment. Each desktop + environment (GNOME, KDE, etc.) has its own UI and UX conventions, as well as + system configuration methods (e.g., GNOME Settings), which this API will need to integrate with. + Because of the variation, we intend to leave integration with these other + components to developers more familiar with each of the desktop environments. + For now, we are using bare GTK to build a UI for testing, but any UI + implementation in this repository is for reference purposes. If anyone is + willing to do some of this integration work, feel free to contact us! + +- Create a full-featured password manager. Features like Password syncing, + password generation, rotation, etc. is not part of this specficiation. Other + password manager projects should be able to use this to make their credentials + available to the user uniformly, though. + +- BSD support. While we'd love to help out all open desktop environments, we don't + know enough about any BSD to make it useful for them. Hopefully, the design + process is transparent enough that someone else could design something that + works for BSDs. + +## Current Work + +- April 2025: Added web extension for testing in Firefox. +- March 2025: Integrated libwebauthn to support USB authenticators. +- May 2024: Met with developers in GNOME and systemd to design internals for + securely storing device credentials. +- Jan 2024: Defined the [scenarios](/doc/historical/scenarios.md) that we expect this + API to cover. We are working on extracting [API methods](/doc/api.md) required to + implement the interactions between the client, portal frontend, portal backend, + machine and mobile devices. Once that is done, I intend to convert the API into + a [portal spec](/doc/historical/design-doc.md), making it fit normal D-Bus/portal patterns. diff --git a/README.md b/README.md index 2473ede0..8d4e7b83 100644 --- a/README.md +++ b/README.md @@ -68,57 +68,9 @@ There is also a demo web extension that can be used to test the service in Firef ## Goals -The goal of this repository is to define a spec for clients (apps, browsers, -etc.) to retrieve user credentials in a uniform way across Linux desktop -environments. - -Some high-level goals: - -- define an API to securely create and retrieve local credentials - (passwords, passkeys, security keys) -- create and retrieve credentials on remote devices (e.g. via CTAP 2 BLE/hybrid - transports) -- Provide a uniform interface for third-party credential providers - (password/passkey managers like GNOME Secrets, Bitwarden, Keepass, LastPass, - etc.) to hook into - -Some nice-to-haves: - -- Design a specification for a platform authenticator. I'm not sure whether this - needs to be specified, or whether it could be considered and implemented as a - first-party credential provider. - -Some non-goals: - -- Fully integrate with any specific desktop environment. Each desktop - environment (GNOME, KDE, etc.) has its own UI and UX conventions, as well as - system configuration methods (e.g., GNOME Settings), which this API will need to integrate with. - Because of the variation, we intend to leave integration with these other - components to developers more familiar with each of the desktop environments. - For now, we are using bare GTK to build a UI for testing, but any UI - implementation in this repository is for reference purposes. If anyone is willing to do some of this integration work, feel free to contact us! - -- Create a full-featured password manager. Features like Password syncing, - password generation, rotation, etc. is not part of this specficiation. Other - password manager projects should be able to use this to make their credentials - available to the user uniformly, though. - -- BSD support. While we'd love to help out all open desktop environments, we don't - know enough about any BSD to make it useful for them. Hopefully, the design - process is transparent enough that someone else could design something that - works for BSDs. - -## Current Work - -- April 2025: Added web extension for testing in Firefox. -- March 2025: Integrated libwebauthn to support USB authenticators. -- May 2024: Met with developers in GNOME and systemd to design internals for - securely storing device credentials. -- Jan 2024: Defined the [scenarios](doc/scenarios.md) that we expect this - API to cover. We are working on extracting [API methods](doc/api.md) required to - implement the interactions between the client, portal frontend, portal backend, - machine and mobile devices. Once that is done, I intend to convert the API into - a [portal spec](doc/design-doc.md), making it fit normal D-Bus/portal patterns. +The primary goal of this project is to provide a spec and reference +implementation of an API to mediate access to web credentials, initially local +and remote FIDO2 authenticators. See [GOALS.md](/GOALS.md) for more information. ## Mockups From 2a147564a25da79cedf984ff781bb13e209c3979 Mon Sep 17 00:00:00 2001 From: Isaiah Inuwa Date: Wed, 13 Aug 2025 12:46:04 -0500 Subject: [PATCH 3/5] Move build instructions to a separate file --- BUILDING.md | 147 ++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 79 ++++++++++++++-------------- 2 files changed, 185 insertions(+), 41 deletions(-) create mode 100644 BUILDING.md diff --git a/BUILDING.md b/BUILDING.md new file mode 100644 index 00000000..2a99f0d3 --- /dev/null +++ b/BUILDING.md @@ -0,0 +1,147 @@ +# Prerequisites + +## Build system + +This project uses Meson, Ninja, and Cargo. + +We use Meson 1.5.0+. If your package manager has an older version, you can +install a new version [using the pip module][meson-pip-install]. + +There is currently no documented minimum support Rust version (MSRV), but 1.83+ +should work. + +[meson-pip-install]: https://mesonbuild.com/Quick-guide.html#installation-using-python + +## Package requirements + +- GTK4 +- gettext +- libdbus-1 +- libssl/openssl +- libudev +- desktop-file-utils + +Using the web extension also requires `python3-dbus-next`. + +## Examples + +### Debian/Ubuntu + +```shell +sudo apt update && sudo apt install \ + # Build dependencies + curl git build-essential \ + # Meson/Ninja dependencies + meson ninja-build \ + # project dependencies + libgtk-4-dev gettext libdbus-1-dev libssl-dev libudev-dev \ + # packaging dependencies + desktop-file-utils \ + # web extension dependencies + python3-dbus-next +``` + +### Fedora + +```shell +# Build dependencies +sudo dnf groupinstall "Development Tools" +sudo dnf install \ + curl git \ + # Meson/Ninja dependencies + meson ninja-build \ + # project dependencies + gtk4-devel gettext dbus-devel openssl-devel systemd-udev \ + # packaging dependencies + desktop-file-utils \ + # web extension dependencies + python3-dbus-next +``` + +# For Installing/Testing + +If you are interested in installing the program, you can use `meson install` to install the details. + +```shell +git clone https://github.com/linux-credentials/credentialsd +cd credentialsd +meson setup -Dprefix=/usr/local build-release +cd build-release +meson install +``` + +Note that since it Meson is installing to `/usr/local`, Meson will ask you to use `sudo` to elevate privileges to install. + +The first time you run this, you must log out and log back in again to restart the D-Bus session bus for it to automatically start the D-Bus services on-demand. + +### Testing with Firefox Web Add-On + +Note: If you are testing the Firefox web extension, you will need to link the native messaging manifest to your home directory, since Firefox does not read from `/usr/local`: + +```shell +mkdir -p ~/.mozilla/native-messaging-hosts/ +ln -s /usr/local/lib64/mozilla/native-messaging-hosts/xyz.iinuwa.credentialsd_helper.json ~/.mozilla/native-messaging-hosts/ +``` + +# For Development + +``` +git clone https://github.com/linux-credentials/credentialsd +cd credentialsd +meson setup -Dprofile=development build +ninja -C build +``` + +## Running the server + +To run the required services during development, you need to add some +environment variables. + +```shell +# Run the server, with debug logging enabled +export GSETTINGS_SCHEMA_DIR=build/credentialsd-ui/data +export RUST_LOG=credentialsd=debug,credentials_ui=debug +./build/credentialsd/target/debug/credentialsd & +./build/credentialsd-ui/target/debug/credentialsd-ui +``` + +# For Packaging + +There are a few Meson options to control the build that may be useful for packagers. + +``` +# list available options + +> meson configure +# ... +Project options Default Value Possible Values Description +----------------- ------------- --------------- ----------- +cargo_home The directory to + store files + downloaded by + Cargo +cargo_offline false [true, false] Whether to + perform an + offline build + with Cargo. + Defaults to false + to download + crates from + registries. +profile default [default, The build profile + development] for Credential + Manager. One of + "default" or + "development". +``` + +> TODO: rename `default` profile to `release` to reduce confusion. + +# Running Tests + +Due to some unknown reason, tests hang unless you pass the `--interactive` flag to Meson, available since 1.5.0. + +``` +cd build +meson test --interactive +``` diff --git a/README.md b/README.md index 8d4e7b83..93c8a96f 100644 --- a/README.md +++ b/README.md @@ -4,57 +4,54 @@ A Linux Credential Manager API. (Previously called `linux-webauthn-platform-api`.) -## How to run +## How to install -### Build Requirements +### From packages -This project uses Meson and Ninja. +We have [precompiled RPM packages for Fedora and openSUSE][obs-packages] hosted +by Open Build Services (OBS). We also copy these for released versions to the +[release page][release-page]. -Package requirements: +There are several sub-packages: -- GTK4 -- gettext -- libdbus-1 -- libssl/openssl -- libudev -- desktop-file-utils +- `credentialsd`: The core credential service +- `credentialsd-ui`: The reference implementation of the UI component for + credentialsd. +- `credentialsd-webextension`: Binaries and manifest files required for the + Firefox add-on to function -Using the web extension also requires `python3-dbus-next`. +[obs-packages]: https://build.opensuse.org/package/show/home:MSirringhaus:webauthn_devel/credentialsd +[release-page]: https://github.com/linux-credentials/credentialsd/releases -For example, on Ubuntu: +### From source -```shell -sudo apt update && sudo apt install \ - # Build dependencies - curl git build-essential \ - # Meson/Ninja dependencies - python3 python3-pip python3-setuptools python3-wheel ninja-build \ - # project dependencies - libgtk-4-dev gettext libdbus-1-dev libssl-dev libudev-dev \ - # packaging dependencies - desktop-file-utils \ -``` +Alternatively, you can build the project yourself using the instructions in +[BUILDING.md](/BUILDING.md). -### Compiling +## How to use -```shell -git clone https://github.com/linux-credentials/credentialsd -cd credentialsd -meson setup build -Dprofile=development -ninja -C build -``` +Right now, there are two ways to use this service. -### Running the server +### Experimental Firefox Add-On -```shell -# Run the server, with debug logging enabled -export GSETTINGS_SCHEMA_DIR=build/credentialsd-ui/data -export RUST_LOG=credentialsd=debug,credentials_ui=debug -./build/credentialsd/target/debug/credentialsd & -./build/credentialsd-ui/target/debug/credentialsd-ui -``` +There is an add-on that you can install in Firefox 140+ that allows you to test +`credentialsd` without a custom Firefox build. You can get the XPI from the +[releases page][release-page] for the corresponding version of +`credentialsd-webextension` package that you installed. + +Currently, this add-on only works for https://webauthn.io and +https://demo.yubico.com, but can be used to test various WebAuthn options and +hardware. + +### Experimental Firefox Build + +There is also an experimental Firefox build that contains a patch to interact +with `credentialsd` directly without an add-on. You can access a +[Flatpak package for it on OBS][firefox-patch-flatpak] as well. + +[firefox-patch-flatpak]: https://download.opensuse.org/repositories/home:/MSirringhaus:/webauthn_devel/openSUSE_Factory_flatpak/ -### Clients +## Clients There is a demo client in the `demo_client`. It mimics an RP, saving the created public keys to a local file and verifying assertions against it. @@ -64,7 +61,7 @@ cd demo_client/ ./main.py get ``` -There is also a demo web extension that can be used to test the service in Firefox. Instructions are in [webext/README.md](). +There is also a demo web extension that can be used to test the service in Firefox. Instructions are in [/webext/README.md](). ## Goals @@ -109,4 +106,4 @@ Alternatively, lock out the credential based on incorrect attempts. # License -See the [LICENSE.md](LICENSE.md) file for license rights and limitations (LGPL-3.0-only). +See the [LICENSE.md](/LICENSE.md) file for license rights and limitations (LGPL-3.0-only). From 5f1da41030b5d82320bd555879987ba55b742520 Mon Sep 17 00:00:00 2001 From: Isaiah Inuwa Date: Wed, 13 Aug 2025 13:55:39 -0500 Subject: [PATCH 4/5] Reference build instructions in webext instructions --- webext/README.md | 29 ++++++++++++----------------- 1 file changed, 12 insertions(+), 17 deletions(-) diff --git a/webext/README.md b/webext/README.md index 501968b4..2c0edb19 100644 --- a/webext/README.md +++ b/webext/README.md @@ -1,7 +1,8 @@ This is a web extension that allows browsers to connect to the D-Bus service provided by this project. It can be used for testing. -Currently, this is written only for Firefox; there will be some slight API tweaks required to make this work in Chrome. +Currently, this is written only for Firefox; there will be some slight API +tweaks required to make this work in Chrome. This requires some setup to make it work: @@ -41,16 +42,7 @@ couple of options: ## For Testing -1. Run the install script for the repository: - ```shell - meson setup -Dprofile=default -Dprefix=/usr/local build-release - cd build-release - meson install - mkdir -p ~/.mozilla/native-messaging-hosts/ - ln -s /usr/local/lib64/mozilla/native-messaging-hosts/xyz.iinuwa.credentialsd_helper.json ~/.mozilla/native-messaging-hosts/ - ``` - Note that since it is installing to `/usr/local`, Meson will ask you to use `sudo` to elevate privileges to install. -2. Log out and log back in again to restart the D-Bus session bus. +1. Follow the instructions in the ["For Installing/Testing" section of `BUILDING.md`](/BUILDING.md#for-installing-testing). 2. Open Firefox and go to `about:debugging`. 3. Click "This Firefox" > Load Temporary Extension. Select `/usr/local/share/credentialsd/credentialsd-firefox-helper.xpi`. 4. Navigate to [https://webauthn.io](). @@ -61,11 +53,14 @@ couple of options: (Note: Paths are relative to root of this repository) 1. Copy `webext/app/credential_manager_shim.json` to `~/.mozilla/native-messaging-hosts/credential_manager_shim.json`. -2. In the copied file, replace the `path` key with the absolute path to `webext/app/credential_manager_shim.py` -3. Open Firefox and go to `about:debugging` -4. Click "This Firefox" > Load Temporary Extension. Select `webext/add-on/manifest.json` -5. Build with `ninja -C ./build` and run the following binaries binary to start the D-Bus services. +2. In `webext/app/credential_manager_shim.py`, point the `DBUS_DOC_FILE` + variable to the absolute path to + `contrib/xyz.iinuwa.credentialsd.Credentials.xml`. +3. In the copied file, replace the `path` key with the absolute path to `webext/app/credential_manager_shim.py` +4. Open Firefox and go to `about:debugging` +5. Click "This Firefox" > Load Temporary Extension. Select `webext/add-on/manifest.json` +6. Build with `ninja -C ./build` and run the following binaries binary to start the D-Bus services. - `GSCHEMA_SCHEMA_DIR=build/credentialsd-ui/data ./build/credentialsd-ui/target/debug/credentialsd-ui` - `./build/credentialsd/target/debug/credentialsd` -6. Navigate to [https://webauthn.io](). -7. Run through the registration and creation process. +7. Navigate to [https://webauthn.io](). +8. Run through the registration and creation process. From 04926f6a4d5c60a59d7366c0b6f88211e5aad2c2 Mon Sep 17 00:00:00 2001 From: Isaiah Inuwa Date: Thu, 14 Aug 2025 08:46:12 -0500 Subject: [PATCH 5/5] docs: Address README feedback --- BUILDING.md | 30 +++++++++++++++++++++++------- GOALS.md | 26 +++++++++++++++++++++----- README.md | 14 +++++++------- 3 files changed, 51 insertions(+), 19 deletions(-) diff --git a/BUILDING.md b/BUILDING.md index 2a99f0d3..1864188f 100644 --- a/BUILDING.md +++ b/BUILDING.md @@ -7,7 +7,7 @@ This project uses Meson, Ninja, and Cargo. We use Meson 1.5.0+. If your package manager has an older version, you can install a new version [using the pip module][meson-pip-install]. -There is currently no documented minimum support Rust version (MSRV), but 1.83+ +There is currently no documented minimum support Rust version (MSRV), but 1.85+ should work. [meson-pip-install]: https://mesonbuild.com/Quick-guide.html#installation-using-python @@ -60,7 +60,9 @@ sudo dnf install \ # For Installing/Testing -If you are interested in installing the program, you can use `meson install` to install the details. +If you are interested in installing the program, you can use `meson install` to +install the details. (If you would like to test without installing, you can +follow the [build instructions for development](#for-development) below.) ```shell git clone https://github.com/linux-credentials/credentialsd @@ -70,13 +72,22 @@ cd build-release meson install ``` -Note that since it Meson is installing to `/usr/local`, Meson will ask you to use `sudo` to elevate privileges to install. +Note that since Meson is installing to `/usr/local`, it will ask you to use +`sudo` to elevate privileges to install. -The first time you run this, you must log out and log back in again to restart the D-Bus session bus for it to automatically start the D-Bus services on-demand. +## Running the installed server -### Testing with Firefox Web Add-On +When using the installed server, systemd or D-Bus should take care of starting +the services on demand, so you don't need to start it manually. -Note: If you are testing the Firefox web extension, you will need to link the native messaging manifest to your home directory, since Firefox does not read from `/usr/local`: +The first time you install this, though, you must log out and log back in again +for the service activation files to take effect. + +## Testing installed builds with Firefox Web Add-On + +Note: If you are testing the Firefox web extension, you will need to link the +native messaging manifest to your home directory, since Firefox does not read +from `/usr/local`: ```shell mkdir -p ~/.mozilla/native-messaging-hosts/ @@ -92,7 +103,7 @@ meson setup -Dprofile=development build ninja -C build ``` -## Running the server +## Running the server for development To run the required services during development, you need to add some environment variables. @@ -105,6 +116,11 @@ export RUST_LOG=credentialsd=debug,credentials_ui=debug ./build/credentialsd-ui/target/debug/credentialsd-ui ``` +## Testing development builds with Firefox Web Add-On + +If you are using the Firefox add-on to build, follow the instructions for +development in [`webext/README.md`](/webext/README.md#for-development). + # For Packaging There are a few Meson options to control the build that may be useful for packagers. diff --git a/GOALS.md b/GOALS.md index c2709dc2..e373432a 100644 --- a/GOALS.md +++ b/GOALS.md @@ -1,8 +1,23 @@ # Goals -The goal of this repository is to define a spec for clients (apps, browsers, -etc.) to retrieve user credentials in a uniform way across Linux desktop -environments. +The goal of this repository is to define a spec and implementation for clients +(apps, browsers, etc.) to retrieve user credentials in a uniform way across +Linux desktop environments. + +## Motivation + +Our primary motivation is to get passkey into the hands of users. Passkeys are +growing as a powerful authentication mechanism for users. As the ecosystem +becomes more mature, browsers are deferring access to passkeys to OS APIs on +other platforms, like Windows Hello, Keychain on macOS and iOS, and +Credential Manager on Android. + +On Linux, there is no OS API so handling passkeys is entirely up to the browser, +which is at a disadvantage to the OS in terms of hardware access and desktop +integration. This situation also requires each individual browser or application +to reimplement the same features. We want to change that! + +## Direction Some high-level goals: @@ -25,7 +40,8 @@ Some non-goals: - Fully integrate with any specific desktop environment. Each desktop environment (GNOME, KDE, etc.) has its own UI and UX conventions, as well as - system configuration methods (e.g., GNOME Settings), which this API will need to integrate with. + system configuration methods (e.g., GNOME Settings), which this API will need + to integrate with. Because of the variation, we intend to leave integration with these other components to developers more familiar with each of the desktop environments. For now, we are using bare GTK to build a UI for testing, but any UI @@ -42,7 +58,7 @@ Some non-goals: process is transparent enough that someone else could design something that works for BSDs. -## Current Work +## Progress - April 2025: Added web extension for testing in Firefox. - March 2025: Integrated libwebauthn to support USB authenticators. diff --git a/README.md b/README.md index 93c8a96f..7c9318cc 100644 --- a/README.md +++ b/README.md @@ -4,12 +4,18 @@ A Linux Credential Manager API. (Previously called `linux-webauthn-platform-api`.) +## Goals + +The primary goal of this project is to provide a spec and reference +implementation of an API to mediate access to web credentials, initially local +and remote FIDO2 authenticators. See [GOALS.md](/GOALS.md) for more information. + ## How to install ### From packages We have [precompiled RPM packages for Fedora and openSUSE][obs-packages] hosted -by Open Build Services (OBS). We also copy these for released versions to the +by the Open Build Service (OBS). We also copy these for released versions to the [release page][release-page]. There are several sub-packages: @@ -63,12 +69,6 @@ cd demo_client/ There is also a demo web extension that can be used to test the service in Firefox. Instructions are in [/webext/README.md](). -## Goals - -The primary goal of this project is to provide a spec and reference -implementation of an API to mediate access to web credentials, initially local -and remote FIDO2 authenticators. See [GOALS.md](/GOALS.md) for more information. - ## Mockups Here are some mockups of what this would look like for a user: