diff --git a/BUILDING.md b/BUILDING.md new file mode 100644 index 00000000..1864188f --- /dev/null +++ b/BUILDING.md @@ -0,0 +1,163 @@ +# 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.85+ +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. (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 +cd credentialsd +meson setup -Dprefix=/usr/local build-release +cd build-release +meson install +``` + +Note that since Meson is installing to `/usr/local`, it will ask you to use +`sudo` to elevate privileges to install. + +## Running the installed server + +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. + +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/ +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 for development + +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 +``` + +## 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. + +``` +# 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/GOALS.md b/GOALS.md new file mode 100644 index 00000000..e373432a --- /dev/null +++ b/GOALS.md @@ -0,0 +1,71 @@ +# Goals + +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: + +- 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. + +## Progress + +- 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 ee05686d..7c9318cc 100644 --- a/README.md +++ b/README.md @@ -1,56 +1,63 @@ -🚧 Excuse the mess, work in progress! 🚧 +# credentialsd -# Linux Credential Manager API +A Linux Credential Manager API. -## How to run +(Previously called `linux-webauthn-platform-api`.) -### Build Requirements +## Goals -This project uses Meson and Ninja. +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. -Package requirements: +## How to install -- GTK4 -- gettext -- libdbus-1 -- libssl/openssl -- libudev -- desktop-file-utils +### From packages -For example, on Ubuntu: +We have [precompiled RPM packages for Fedora and openSUSE][obs-packages] hosted +by the Open Build Service (OBS). We also copy these for released versions to the +[release page][release-page]. -```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 \ -``` +There are several sub-packages: -### Compiling +- `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 -```shell -git clone https://github.com/linux-credentials/linux-webauthn-platform-api -cd linux-webauthn-platform-api -meson setup build -Dprofile=development -ninja -C build -``` +[obs-packages]: https://build.opensuse.org/package/show/home:MSirringhaus:webauthn_devel/credentialsd +[release-page]: https://github.com/linux-credentials/credentialsd/releases -### Running the server +### From source -```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 -``` +Alternatively, you can build the project yourself using the instructions in +[BUILDING.md](/BUILDING.md). + +## How to use + +Right now, there are two ways to use this service. -### Clients +### Experimental Firefox Add-On + +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 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. @@ -60,61 +67,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](). - -## 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. +There is also a demo web extension that can be used to test the service in Firefox. Instructions are in [/webext/README.md](). ## Mockups @@ -153,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). 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.