Skip to content

Commit bb238e7

Browse files
iinuwaiinuwa
authored
Merge pull request #89 from linux-credentials/readme-update
Update README - Update project name - Move GOALS.md and BUILDING.md as separate files
2 parents 482e654 + 04926f6 commit bb238e7

File tree

4 files changed

+295
-113
lines changed

4 files changed

+295
-113
lines changed

‎BUILDING.md‎

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
# Prerequisites
2+
3+
## Build system
4+
5+
This project uses Meson, Ninja, and Cargo.
6+
7+
We use Meson 1.5.0+. If your package manager has an older version, you can
8+
install a new version [using the pip module][meson-pip-install].
9+
10+
There is currently no documented minimum support Rust version (MSRV), but 1.85+
11+
should work.
12+
13+
[meson-pip-install]: https://mesonbuild.com/Quick-guide.html#installation-using-python
14+
15+
## Package requirements
16+
17+
- GTK4
18+
- gettext
19+
- libdbus-1
20+
- libssl/openssl
21+
- libudev
22+
- desktop-file-utils
23+
24+
Using the web extension also requires `python3-dbus-next`.
25+
26+
## Examples
27+
28+
### Debian/Ubuntu
29+
30+
```shell
31+
sudo apt update && sudo apt install \
32+
# Build dependencies
33+
curl git build-essential \
34+
# Meson/Ninja dependencies
35+
meson ninja-build \
36+
# project dependencies
37+
libgtk-4-dev gettext libdbus-1-dev libssl-dev libudev-dev \
38+
# packaging dependencies
39+
desktop-file-utils \
40+
# web extension dependencies
41+
python3-dbus-next
42+
```
43+
44+
### Fedora
45+
46+
```shell
47+
# Build dependencies
48+
sudo dnf groupinstall "Development Tools"
49+
sudo dnf install \
50+
curl git \
51+
# Meson/Ninja dependencies
52+
meson ninja-build \
53+
# project dependencies
54+
gtk4-devel gettext dbus-devel openssl-devel systemd-udev \
55+
# packaging dependencies
56+
desktop-file-utils \
57+
# web extension dependencies
58+
python3-dbus-next
59+
```
60+
61+
# For Installing/Testing
62+
63+
If you are interested in installing the program, you can use `meson install` to
64+
install the details. (If you would like to test without installing, you can
65+
follow the [build instructions for development](#for-development) below.)
66+
67+
```shell
68+
git clone https://github.com/linux-credentials/credentialsd
69+
cd credentialsd
70+
meson setup -Dprefix=/usr/local build-release
71+
cd build-release
72+
meson install
73+
```
74+
75+
Note that since Meson is installing to `/usr/local`, it will ask you to use
76+
`sudo` to elevate privileges to install.
77+
78+
## Running the installed server
79+
80+
When using the installed server, systemd or D-Bus should take care of starting
81+
the services on demand, so you don't need to start it manually.
82+
83+
The first time you install this, though, you must log out and log back in again
84+
for the service activation files to take effect.
85+
86+
## Testing installed builds with Firefox Web Add-On
87+
88+
Note: If you are testing the Firefox web extension, you will need to link the
89+
native messaging manifest to your home directory, since Firefox does not read
90+
from `/usr/local`:
91+
92+
```shell
93+
mkdir -p ~/.mozilla/native-messaging-hosts/
94+
ln -s /usr/local/lib64/mozilla/native-messaging-hosts/xyz.iinuwa.credentialsd_helper.json ~/.mozilla/native-messaging-hosts/
95+
```
96+
97+
# For Development
98+
99+
```
100+
git clone https://github.com/linux-credentials/credentialsd
101+
cd credentialsd
102+
meson setup -Dprofile=development build
103+
ninja -C build
104+
```
105+
106+
## Running the server for development
107+
108+
To run the required services during development, you need to add some
109+
environment variables.
110+
111+
```shell
112+
# Run the server, with debug logging enabled
113+
export GSETTINGS_SCHEMA_DIR=build/credentialsd-ui/data
114+
export RUST_LOG=credentialsd=debug,credentials_ui=debug
115+
./build/credentialsd/target/debug/credentialsd &
116+
./build/credentialsd-ui/target/debug/credentialsd-ui
117+
```
118+
119+
## Testing development builds with Firefox Web Add-On
120+
121+
If you are using the Firefox add-on to build, follow the instructions for
122+
development in [`webext/README.md`](/webext/README.md#for-development).
123+
124+
# For Packaging
125+
126+
There are a few Meson options to control the build that may be useful for packagers.
127+
128+
```
129+
# list available options
130+
131+
> meson configure
132+
# ...
133+
Project options Default Value Possible Values Description
134+
----------------- ------------- --------------- -----------
135+
cargo_home The directory to
136+
store files
137+
downloaded by
138+
Cargo
139+
cargo_offline false [true, false] Whether to
140+
perform an
141+
offline build
142+
with Cargo.
143+
Defaults to false
144+
to download
145+
crates from
146+
registries.
147+
profile default [default, The build profile
148+
development] for Credential
149+
Manager. One of
150+
"default" or
151+
"development".
152+
```
153+
154+
> TODO: rename `default` profile to `release` to reduce confusion.
155+
156+
# Running Tests
157+
158+
Due to some unknown reason, tests hang unless you pass the `--interactive` flag to Meson, available since 1.5.0.
159+
160+
```
161+
cd build
162+
meson test --interactive
163+
```

‎GOALS.md‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
# Goals
2+
3+
The goal of this repository is to define a spec and implementation for clients
4+
(apps, browsers, etc.) to retrieve user credentials in a uniform way across
5+
Linux desktop environments.
6+
7+
## Motivation
8+
9+
Our primary motivation is to get passkey into the hands of users. Passkeys are
10+
growing as a powerful authentication mechanism for users. As the ecosystem
11+
becomes more mature, browsers are deferring access to passkeys to OS APIs on
12+
other platforms, like Windows Hello, Keychain on macOS and iOS, and
13+
Credential Manager on Android.
14+
15+
On Linux, there is no OS API so handling passkeys is entirely up to the browser,
16+
which is at a disadvantage to the OS in terms of hardware access and desktop
17+
integration. This situation also requires each individual browser or application
18+
to reimplement the same features. We want to change that!
19+
20+
## Direction
21+
22+
Some high-level goals:
23+
24+
- define an API to securely create and retrieve local credentials
25+
(passwords, passkeys, security keys)
26+
- create and retrieve credentials on remote devices (e.g. via CTAP 2 BLE/hybrid
27+
transports)
28+
- Provide a uniform interface for third-party credential providers
29+
(password/passkey managers like GNOME Secrets, Bitwarden, Keepass, LastPass,
30+
etc.) to hook into
31+
32+
Some nice-to-haves:
33+
34+
- Design a specification for a platform authenticator. I'm not sure whether this
35+
needs to be specified, or whether it could be considered and implemented as a
36+
first-party credential provider.
37+
- A security key manager (e.g., for setting security key client PIN)
38+
39+
Some non-goals:
40+
41+
- Fully integrate with any specific desktop environment. Each desktop
42+
environment (GNOME, KDE, etc.) has its own UI and UX conventions, as well as
43+
system configuration methods (e.g., GNOME Settings), which this API will need
44+
to integrate with.
45+
Because of the variation, we intend to leave integration with these other
46+
components to developers more familiar with each of the desktop environments.
47+
For now, we are using bare GTK to build a UI for testing, but any UI
48+
implementation in this repository is for reference purposes. If anyone is
49+
willing to do some of this integration work, feel free to contact us!
50+
51+
- Create a full-featured password manager. Features like Password syncing,
52+
password generation, rotation, etc. is not part of this specficiation. Other
53+
password manager projects should be able to use this to make their credentials
54+
available to the user uniformly, though.
55+
56+
- BSD support. While we'd love to help out all open desktop environments, we don't
57+
know enough about any BSD to make it useful for them. Hopefully, the design
58+
process is transparent enough that someone else could design something that
59+
works for BSDs.
60+
61+
## Progress
62+
63+
- April 2025: Added web extension for testing in Firefox.
64+
- March 2025: Integrated libwebauthn to support USB authenticators.
65+
- May 2024: Met with developers in GNOME and systemd to design internals for
66+
securely storing device credentials.
67+
- Jan 2024: Defined the [scenarios](/doc/historical/scenarios.md) that we expect this
68+
API to cover. We are working on extracting [API methods](/doc/api.md) required to
69+
implement the interactions between the client, portal frontend, portal backend,
70+
machine and mobile devices. Once that is done, I intend to convert the API into
71+
a [portal spec](/doc/historical/design-doc.md), making it fit normal D-Bus/portal patterns.

0 commit comments

Comments
 (0)