{"id":13599914,"url":"https://github.com/nullpo-head/WSL-Hello-sudo","last_synced_at":"2025-04-10T17:32:56.316Z","repository":{"id":25390001,"uuid":"103874990","full_name":"nullpo-head/WSL-Hello-sudo","owner":"nullpo-head","description":"Let's sudo by face recognition of Windows Hello on Windows Subsystem for Linux (WSL). It runs on both WSL 1 and WSL 2. This is a PAM module for Linux on WSL.","archived":false,"fork":false,"pushed_at":"2023-05-21T13:53:55.000Z","size":1696,"stargazers_count":1239,"open_issues_count":32,"forks_count":52,"subscribers_count":14,"default_branch":"master","last_synced_at":"2025-04-08T20:18:32.412Z","etag":null,"topics":["linux-pam","wsl"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nullpo-head.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2017-09-18T01:05:26.000Z","updated_at":"2025-04-08T08:58:35.000Z","dependencies_parsed_at":"2024-04-17T04:44:29.104Z","dependency_job_id":"f4286d7d-f79a-4e66-8e23-0376b1d346bc","html_url":"https://github.com/nullpo-head/WSL-Hello-sudo","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nullpo-head%2FWSL-Hello-sudo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nullpo-head%2FWSL-Hello-sudo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nullpo-head%2FWSL-Hello-sudo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nullpo-head%2FWSL-Hello-sudo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nullpo-head","download_url":"https://codeload.github.com/nullpo-head/WSL-Hello-sudo/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248261995,"owners_count":21074229,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["linux-pam","wsl"],"created_at":"2024-08-01T17:01:17.722Z","updated_at":"2025-04-10T17:32:56.308Z","avatar_url":"https://github.com/nullpo-head.png","language":"Rust","readme":"# WSL Hello sudo\n\n\"WSL Hello sudo\" is a Linux PAM module and companion Windows CLI apps that realize `sudo` by\nbiometric login of [Windows Hello](https://www.microsoft.com/en-us/windows/windows-hello) on Windows Subsystem for Linux (WSL).  \nThis PAM module allows you to authenticate `sudo` via face recognition, fingerprint authentication, and of couse machine-local PIN.\nIt runs in both WSL and WSL 2.\n\nBoth the Linux PAM module and Windows CLI app are written in Rust.\nPlease use it at your own risk. There is no warranty.\n\n![demo](https://github.com/nullpo-head/WSL-Hello-sudo/blob/master/demo.gif)\n\n\"WSL Hello sudo\" actually does __not__ modify your `sudo` command at all. It is a Linux PAM module.  \nPAM, _Plaggable Authentication Module_, is a UNIX's module system that provides user authentication mechanisms to applications such as `sudo` or `su`. \"WSL Hello sudo\" is such a PAM module that lets applications use Windows Hello.\n\n## Installation and Configuration\n\n### Installation\n\nThe installation process is very simple.  \nPlease download the latest release package from GitHub Release and unpack it.  \nRun `install.sh` inside the directory, and follow the instruction of `install.sh`\n\n```ShellSession\n$ wget http://github.com/nullpo-head/WSL-Hello-sudo/releases/latest/download/release.tar.gz\n$ tar xvf release.tar.gz\n$ cd release\n$ ./install.sh\n```\n\nAlthough you don't have to care about the detailed installation process,  \n`install.sh` does following things.\n\n1. Copy a small Windows CLI app that launches Windows Hello to `C:\\Users\\your_account\\pam_wsl_hello` (default location)  \n2. Install a PAM module to your WSL system.\n3. Create config files in `/etc/pam_wsl_hello/`\n4. Create a pam-configs entry in `/usr/share/pam-configs/` for automatic PAM configuration\n5. Create `uninstall.sh`\n\n### Configuration\n\n\"WSL Hello sudo\" is not a fork of `sudo` but a PAM module. You have to adjust the PAM configuration to make it effective.\n\n#### Automatic configuration\nOn Ubuntu, you can use `sudo pam-auth-update` to show a list of installed PAM authentication modules, and select the ones you want to use for authentication (which will also affect sudo etc.)\n\nThe install scripts will install the required configuration. If you're not using the install script, you can copy the pam-config file from the release tarball to `/usr/share/pam-configs/`.\n\n#### Manual configuration\n\nIf for some reason you do not want to use automatic configuration, you can configure `/etc/pam.d/sudo` manually.\nI strongly recommend to set password of root first so that you can switch to it by `su`, in case you make some typo in the config of `sudo`.  \nAdd `auth sufficient pam_wsl_hello.so` to the top line of your `/etc/pam.d/sudo` like the following example  \n\n```\n#%PAM-1.0\n\nauth       sufficient pam_wsl_hello.so\nsession    required   pam_env.so readenv=1 user_readenv=0\nsession    required   pam_env.so readenv=1 envfile=/etc/default/locale user_readenv=0\n@include common-auth\n@include common-account\n@include common-session-noninteractive\n```\nEven if you fail to authenticate via Windows Hello, `sudo` moves on to the regular password authentication by this setting with `sufficient`.  \n\nOther applications that authenticate users such as `su` can also utilize Windows Hello by this module.  \nEven so, __I strongly recommend you to make either `sudo` or `su` free from this module to prevent from being locked out__\n\n## Troubleshooting\n\n### Windows Hello window appears in background.\n\nThe Windows Hello dialog sometimes appears in background.\nIn some cases, it even fails to recognize your face with some weird error message.\nIt seems a bug of Windows API. In that case, restarting Windows a couple of times might solve the problem.\n\n### \"Windows Hello is not invoked! `sudo` just prompts password!\"\n\nMaybe some error is happening. Unfortunately, `sudo` suppresses error messages from PAM modules.  \nTo debug \"WSL Hello sudo\", make it effective for `su` instead of `sudo`. `su` shows error messages from PAM modules,\nso you can see what is going on.\n\nFor your information, the setting for `su` will be like the example below.\nI will show only relevant two lines.\n```\nauth       sufficient pam_rootok.so\nauth       sufficient pam_wsl_hello.so  \n```\n\n## Build\n\nBoth the Linux PAM module and the Windows CLI apps of \"WSL Hello sudo\" are written in Rust.\nSo, only `cargo` is required to build it.\n\nTo build \"WSL Hello sudo\", make sure you're in WSL and then just run `make`.\n\n```ShellSession\n$ git clone https://github.com/nullpo-head/WSL-Hello-sudo.git\n$ cd WSL-Hello-sudo\n$ make\n```\n\n## Internals\n\nWindows Hello maintains RSA key-pairs for each Windows user in its TPM hardware, and tells success of authentication by signing given contents by the private key.\nTo utilize its API, \"WSL Hello sudo\" contains small Windows CLI apps that return public key and signed signature of given content.\nOn the other hand, the PAM module of \"WSL Hello sudo\" remembers the public keys of each Windows user who corresponds to each Linux user.\nSo, the PAM module authenticates the given Linux user by the following process.\n\n0. The PAM module is launched by `sudo` and receives a Linux user to be authenticated\n1. The PAM module launches the companion Windows app and sends a random value via WSL's interop bridge\n2. The companion Windows app invokes Windows Hello\n3. Windows Hello makes a signature of the given input by the private key of the current Windows user\n4. The companion Windows app returns the signature\n5. The PAM module verifies the signature by the public key of the Windows user who corresponds to the given Linux user.\n","funding_links":[],"categories":["Rust","WSL Tools","Windows"],"sub_categories":["10. GUI Apps","Containers"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnullpo-head%2FWSL-Hello-sudo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnullpo-head%2FWSL-Hello-sudo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnullpo-head%2FWSL-Hello-sudo/lists"}