{"id":23129570,"url":"https://github.com/yubico/pam-u2f","last_synced_at":"2025-05-15T08:08:57.894Z","repository":{"id":24429033,"uuid":"27830459","full_name":"Yubico/pam-u2f","owner":"Yubico","description":"Pluggable Authentication Module (PAM) for U2F and FIDO2","archived":false,"fork":false,"pushed_at":"2025-03-27T12:45:23.000Z","size":705,"stargazers_count":568,"open_issues_count":16,"forks_count":86,"subscribers_count":54,"default_branch":"main","last_synced_at":"2025-04-02T09:54:48.101Z","etag":null,"topics":["fido2","pam-module","u2f","yubikey"],"latest_commit_sha":null,"homepage":"https://developers.yubico.com/pam-u2f/","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Yubico.png","metadata":{"files":{"readme":"README","changelog":"NEWS","contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":"AUTHORS","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-12-10T17:12:52.000Z","updated_at":"2025-03-27T23:38:05.000Z","dependencies_parsed_at":"2024-01-16T13:31:58.657Z","dependency_job_id":"78cf72e9-a661-4cdf-9f2b-f5bbaf4a492e","html_url":"https://github.com/Yubico/pam-u2f","commit_stats":null,"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yubico%2Fpam-u2f","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yubico%2Fpam-u2f/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yubico%2Fpam-u2f/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yubico%2Fpam-u2f/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Yubico","download_url":"https://codeload.github.com/Yubico/pam-u2f/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248027407,"owners_count":21035594,"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":["fido2","pam-module","u2f","yubikey"],"created_at":"2024-12-17T10:09:53.239Z","updated_at":"2025-04-09T11:05:21.745Z","avatar_url":"https://github.com/Yubico.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"= Pluggable Authentication Module (PAM) Universal 2nd Factor (U2F)\n\nimage:https://github.com/yubico/pam-u2f/workflows/linux/badge.svg[\"Linux Build Status (github actions)\", link=\"https://github.com/Yubico/pam-u2f/actions\"]\nimage:https://github.com/yubico/pam-u2f/workflows/macos/badge.svg[\"macOS Build Status (github actions)\", link=\"https://github.com/Yubico/pam-u2f/actions\"]\nimage:https://github.com/yubico/pam-u2f/workflows/fuzzer/badge.svg[\"Fuzz Status (github actions)\", link=\"https://github.com/Yubico/pam-u2f/actions\"]\n\nThis module implements PAM over U2F and FIDO2, providing an easy way to integrate the\nYubiKey (or other U2F/FIDO2 compliant authenticators) into your existing\ninfrastructure.\n\n== Releases\n\nYou may get signed release source tarballs from Yubico's\nhttps://developers.yubico.com/pam-u2f/Releases[release page].\n\n== Installation\n\npam-u2f comes readily packaged for a number of systems. A non-exhaustive\nlist is available below.\n\n=== Ubuntu\n\n----\n# apt install libpam-u2f pamu2fcfg\n----\n\nAdditionally, Yubico maintains a PPA with up-to-date versions of pam-u2f.\n\n----\n# apt install software-properties-common\n# apt-add-repository ppa:yubico/stable\n# apt update\n# apt install libpam-u2f pamu2fcfg\n----\n\n=== Fedora\n\n----\n# dnf install pam-u2f pamu2fcfg\n----\n\n=== macOS\n\n----\n$ brew install pam-u2f\n----\n\n[[building]]\n== Building from a source tarball\n\nThis project depends on https://developers.yubico.com/libfido2[`libfido2`]\n(\u003e= 1.3.0).\nVersions of this project up to 1.0.8 used `libu2f-host` and\n`libu2f-server`.\n\nOn Ubuntu, the dependencies needed to build the source tarball can be installed\nusing:\n\n----\n# apt install --no-install-recommends --no-install-suggests \\\n    gcc \\\n    libfido2-dev \\\n    libpam-dev \\\n    libssl-dev \\\n    make \\\n    pkg-config\n----\n\nThe project can be built as follows:\n\n----\n$ ./configure\n$ make\n----\n\nOnce the module is built, copy the file `pam_u2f.so` to the correct\ndirectory for your system. Typically `/lib/security/` or\n`/lib/x86_64-linux-gnu/security/`. This is automated by `make install`\nassuming that the pam directory chosen by `configure` is correct. If\nthat is not the case it can be specified with\n`./configure --with-pam-dir=`.\n\n== Building from Git\n\nYou may check out the sources using Git with the following command:\n\n----\n$ git clone https://github.com/Yubico/pam-u2f.git\n----\n\nThis will create a directory 'pam-u2f'. Enter the directory:\n\n----\n$ cd pam-u2f\n----\n\nThis project uses `autoconf`, `automake`, `pkg-config` and `libtool`\nto achieve portability and ease of use.\n`AsciiDoc` and `xsltproc` are used to generate the manpages.\n\nOn Ubuntu, the dependencies needed to build from Git can be installed using:\n\n----\n# apt install --no-install-recommends --no-install-suggests \\\n    asciidoc \\\n    autoconf \\\n    automake \\\n    libfido2-dev \\\n    libpam-dev \\\n    libssl-dev \\\n    libtool \\\n    make \\\n    pkg-config\n----\n\nOn Fedora, the necessary dependencies can be installed using:\n\n----\n# dnf -y install \\\n    asciidoc \\\n    autoconf \\\n    automake \\\n    libfido2-devel \\\n    libtool \\\n    openssl-devel \\\n    pam-devel\n----\n\nGenerate the build system using:\n\n----\n$ autoreconf --install\n----\n\nThen build as usual, see above under \u003c\u003cbuilding,Building from a source tarball\u003e\u003e.\n\n== Building with CMake\n\nA migration of the build system from GNU Autotools to CMake is currently in\nprocess.\nVersions from 1.4.0 and above can be built using CMake.\nGNU Autotools support will be dropped in a future release.\n\nBuilding with CMake requires a slightly different set of\ndependencies, needed both for compiling from a source\ntarball and from Git.\n\nOn Ubuntu, the minimal set of dependencies needed to build with CMake\ncan be installed using:\n\n----\n# apt install --no-install-recommends --no-install-suggests \\\n    asciidoc \\\n    cmake \\\n    gcc \\\n    libfido2-dev \\\n    libpam-dev \\\n    make \\\n    pkg-config\n----\n\nThe project can be built as follows:\n\n----\n$ cmake .\n$ cmake --build .\n$ cmake --build . -t test   # Optional: run unit tests\n----\n\nThe obtained artifacts can be installed as follows:\n\n----\n# cmake --install .\n----\n\n== Service Configuration\n\nCreate a file for a new service in `/etc/pam.d/` or edit an already\nexisting one by adding a line similar to this:\n\n----\nauth sufficient pam_u2f.so debug\n----\n\nFor more information about the syntax of PAM configuration files, please\nsee the manual page for pam.conf(5). Additional \u003c\u003cexamples,example\nconfigurations\u003e\u003e can be found below.\n\nIMPORTANT: An erroneous PAM configuration may lock some or all users\nout of the system or prevent you from gaining root privileges. It is\nrecommended that you start a separate shell with root privileges while\nconfiguring PAM to be able to revert changes if something goes wrong.\nTest your configuration thoroughly before closing the root shell.\n\n[[moduleArguments]]\n=== Module Arguments\n\n[horizontal]\ndebug::\nEnables debug output\n\ndebug_file::\nFilename to write debugging messages to. **If this file is missing,\nnothing will be logged**. This regular file **has to be created by the\nuser** or **must exist and be a regular file** for anything getting\nlogged to it. It is not created by pam-u2f on purpose (for security\nconsiderations). This filename may be alternatively set to \"stderr\"\n(default), \"stdout\", or \"syslog\".\n\norigin=origin::\nSet the relying party ID for the FIDO authentication procedure. If no\nvalue is specified, the identifier \"pam://$HOSTNAME\" is used.\n\nappid=appid::\nSet the https://developers.yubico.com/U2F/App_ID.html[application ID]\nfor the FIDO authentication procedure. If no value is specified, the\nsame value used for origin is taken (\"pam://$HOSTNAME\" if also origin\nis not specified). This setting is only applicable for FIDO credentials\ncreated with pamu2fcfg versions v1.0.8 or earlier. Note that on v1.1.0\nand v1.1.1 of pam-u2f, handling of this setting was temporarily broken\nif the value was not the same as the value of origin.\n\nauthfile=file::\nSet the location of the \u003c\u003cauthMappingFiles,file that holds the mappings of user\nnames to keyHandles and user keys\u003e\u003e. An \u003c\u003cindividualAuth,individual (per user)\nfile\u003e\u003e may be configured relative to the users' home dirs, e.g.\n\".ssh/u2f_keys\". If not specified, the location defaults to\n$XDG_CONFIG_HOME/Yubico/u2f_keys. If $XDG_CONFIG_HOME is not set,\n$HOME/.config/Yubico/u2f_keys is used.\n\nexpand::\nEnables variable expansion within the authfile path: `%u` is expanded to the\nlocal user name (`PAM_USER`) and `%%` is expanded to `%`. Unknown expansion\nsequences result in an authentication error. See also `openasuser`.\n\nauthpending_file=file::\nSet the location of the file that is used for touch request\nnotifications. This file will be opened when pam-u2f starts waiting\nfor a user to touch the FIDO authenticator, and will be closed when it no\nlonger waits for a touch. Use inotify to listen on these events, or a more\nhigh-level tool like\nhttps://github.com/maximbaz/yubikey-touch-detector[yubikey-touch-detector].\nNote that yubikey-touch-detector v1.5.1 and later no longer rely on the\nauthpending file for its detection mechanism. Set an empty value in order to\ndisable this functionality, like so: `authpending_file=`. Default value:\n/var/run/user/$UID/pam-u2f-authpending\n\nnouserok::\nSet to make authentication attempts not fail if the user trying to\nauthenticate is not found inside `authfile`, is found but has no\ncredentials, or if the `authfile` is missing.\n\nopenasuser::\nSetuid to the authenticating user when opening the authfile. Useful\nwhen the user's home is stored on an NFS volume mounted with the\n`root_squash` option (which maps root to nobody which will not be able\nto read the file). Note that after release 1.0.8 this is done by\ndefault when no global authfile (path is absolute) or XDG_CONFIG_HOME\nenvironment variable has been set.\n\nalwaysok::\nSet to enable all authentication attempts to succeed (aka presentation\nmode).\n\nmax_devices=n_devices::\nMaximum number of FIDO authenticators allowed per user (default is 24).\nAuthenticators specified in the authorization mapping file that exceed\nthis value will be ignored.\n\ninteractive::\nSet to prompt a message and wait before testing the presence of a FIDO\nauthenticator. Recommended if your authenticator doesn't have a tactile\ntrigger.\n\n[prompt=your prompt here]::\nSet individual prompt message for interactive mode. Watch the square\nbrackets around this parameter to get spaces correctly recognized by\nPAM.\n\nmanual::\nSet to drop to a manual console where challenges are printed on screen\nand response read from standard input. Useful for debugging and SSH\nsessions without FIDO support from the SSH client/server. If enabled,\ninteractive mode becomes redundant and has no effect.\n\ncue::\nSet to prompt a message to remind to touch the FIDO authenticator.\n\n[cue_prompt=your prompt here]::\nSet individual prompt message for the cue option. Watch the square\nbrackets around this parameter to get spaces correctly recognized by\nPAM.\n\nnodetect::\nSet to skip detecting if a suitable FIDO authenticator is inserted before\nperforming the full tactile authentication. This detection was created\nto avoid emitting the \"cue\" message if no suitable token exists,\nbecause doing so leaks information about the authentication stack if a\ntoken is inserted but not configured for the authenticating user.\nHowever, it was found that versions of `libu2f-host` 1.1.5 or less has\nbuggy iteration/sleep behavior which causes a 1-second delay to occur\nfor this initial detection. For this reason, as well as the\npossibility of hypothetical tokens that do not tolerate this double\nauthentication, the \"nodetect\" option was added.\n\nuserpresence=int::\nIf 1, request user presence during authentication. If 0, do not\nrequest user presence during authentication. If omitted, fallback to\nthe authenticator's default behaviour.\n\nuserverification=int::\nIf 1, request user verification during authentication (e.g. biometrics).\nIf 0, do not request user verification during authentication. If omitted,\nfallback to the authenticator's default behaviour. If enabled, an\nauthenticator with support for FIDO2 user verification is required.\n\npinverification=int::\nIf 1, request PIN verification during authentication. If 0, do not\nrequest PIN verification during authentication. If omitted, fallback to\nthe authenticator's default behaviour. If enabled, an authenticator\nwith support for a FIDO2 PIN is required.\n\nsshformat::\nUse credentials produced by versions of OpenSSH that have support for\nFIDO authenticators. It is not possible to mix native credentials and SSH\ncredentials. Once this option is enabled all credentials will be parsed\nas SSH.\n\nconf=/path/to/pam_u2f.conf::\nSet an alternative location for the \u003c\u003cconfFile,configuration file\u003e\u003e.\nThe supplied path must be absolute and must correspond to an existing\nregular file.\n\nThe options specified on the module command line override the values\nfrom the \u003c\u003cconfFile,configuration file\u003e\u003e.\n\nIMPORTANT: On dynamic networks (e.g. where hostnames are set by DHCP),\nusers should not rely on the default origin and appid\n(\"pam://$HOSTNAME\") but set those parameters explicitly to the same\nvalue.\n\n[[examples]]\n=== Example Service Configurations\n\n==== Second Factor Authentication\n\nConfigure pam-u2f as a `required` module after your primary authentication\nmodule(s) for use as a second factor. Make sure that the primary authentication\nmethod is not `sufficient` or uses other control values that may preempt\nexecution of pam-u2f.\n\n----\n# Primary authentication method(s) above this line.\nauth required pam_u2f.so authfile=/etc/u2f_mappings cue\n----\n\n==== Passwordless Authentication\n\nFor a passwordless experience, where the authenticator PIN can be used in place\nof the user password, you can insert the below line towards the top of your\nservice configuration. You may need to change the control value to something\nelse if you'd like to execute additional authentication modules after pam-u2f.\n\n----\nauth sufficient pam_u2f.so authfile=/etc/u2f_mappings cue pinverification=1\n# Fallback modules go below this line (e.g. password authentication).\n----\n\n==== Passwordless Authentication using Biometrics\n\nSimilar to the previous configuration but capable of built-in user\nverification, e.g. fingerprint matching using the YubiKey Bio. This example\nfalls back to using PIN verification if the fingerprint does not match or is\notherwise blocked.\n\n----\nauth sufficient pam_u2f.so authfile=/etc/u2f_mappings cue pinverification=0 userverification=1\nauth sufficient pam_u2f.so authfile=/etc/u2f_mappings cue pinverification=1 userverification=0\n# More fallback modules go below this line (e.g. password authentication).\n----\n\n[[authMappingFiles]]\n== Authorization Mapping Files\n\nA mapping must be made between the YubiKey token and the user name,\nsee \u003c\u003cregistration, here\u003e\u003e for details on how to perform the\nregistration using the bundled tool.\n\nThere are two ways to do this, either centrally in one file, or\nindividually, where users can create the mapping in their home\ndirectories. If the central authorization mapping file is being used,\nuser home directory mappings will not be used and the opposite applies\nif user home directory mappings are being used, the central\nauthorization mappings file will not be used.\n\nBy default the mapping file inside a home directory will be opened as\nthe target user, whereas the central file will be opened as `root`. If\nthe `XDG_CONFIG_HOME` variable is set, privileges will not be dropped\nunless the `openasuser` configuration setting is set.\n\nIMPORTANT: Using pam-u2f to secure the login to a computer while\nstoring the mapping file in an encrypted home directory, will result\nin the impossibility of logging into the system. The partition is\ndecrypted after login and the mapping file can not be accessed.\n\n=== Central Authorization Mapping\n\nCreate a file e.g. `/etc/u2f_mappings`. The file must contain a user\nname, and the information obtained during the registration procedure.\n\nThe mappings should look like this, one per line:\n\n \u003cusername1\u003e:\u003cKeyHandle1\u003e,\u003cUserKey1\u003e,\u003cCoseType1\u003e,\u003cOptions1\u003e:\u003cKeyHandle2\u003e,\u003cUserKey2\u003e,\u003cCoseType2\u003e,\u003cOptions2\u003e:...\n \u003cusername2\u003e:\u003cKeyHandle1\u003e,\u003cUserKey1\u003e,\u003cCoseType1\u003e,\u003cOptions1\u003e:\u003cKeyHandle2\u003e,\u003cUserKey2\u003e,\u003cCoseType2\u003e,\u003cOptions2\u003e:...\n\nNow add `authfile=/etc/u2f_mappings` to your PAM configuration line,\nso it looks like:\n\n auth sufficient pam_u2f.so authfile=/etc/u2f_mappings\n\nIf you do not set the `openasuser` setting, the authfile will be\nopened and parsed as `root` so make sure it has the correct owner and\npermissions set.\n\n[[individualAuth]]\n=== Individual Authorization Mapping by User\n\nEach user creates a `.config/Yubico/u2f_keys` (default) file inside\ntheir home directory and places the mapping in that file. You may want\nto specify a different per-user file (relative to the users' home\ndirectory), i.e. `.ssh/u2f_keys`. Bear in mind, setting an absolute path\nhere is possible although very likely a fragile setup, and probably\nnot exhibiting the intended behaviour.\n\nThe file must have only one line:\n\n \u003cusername\u003e:\u003cKeyHandle1\u003e,\u003cUserKey1\u003e,\u003cCoseType1\u003e,\u003cOptions1\u003e:\u003cKeyHandle2\u003e,\u003cUserKey2\u003e,\u003cCoseType2\u003e,\u003cOptions2\u003e:...\n\nThis is much the same concept as the SSH authorized_keys file.\n\nIn this case, pam-u2f will drop privileges and read the mapping file\nas that user. This happens regardless of the `openasuser` option being\nset.\n\nNote that if you set the `XDG_CONFIG_HOME` variable, privileges will not\nbe dropped by default. Consider also setting `openasuser` in that\ncase.\n\n[[registration]]\n=== Obtaining Key Handles and Public Keys\n\nIn order to obtain the required information for the authentication procedure,\na token should be first registered. This can be done by using the command line\nconfiguration tool provided with the module:\n\n----\n$ pamu2fcfg -uusername -opam://myorigin -ipam://myappid\n----\n\nthe tool will register a connected token by using the specified origin\nand appid. If neither are specified they will default to\n`pam://$HOSTNAME`. Additionally, it is possible to set other options\nto require user presence (touch), PIN verification and resident\ncredentials. On success the tool prints to standard output a\nconfiguration line that can be directly used with the module. For\nadditional information on the tool read the relative manpage (`man pamu2fcfg`).\n\nFor authenticator management (e.g. setting a PIN, enrolling fingerprints, and\nmore), please refer to\nhttps://developers.yubico.com/libfido2/Manuals/fido2-token.html[`fido2-token`],\nhttps://developers.yubico.com/yubikey-manager[`yubikey-manager`], or some other\nsuitable tool.\n\n=== SSH Credentials\n\nTo generate SSH credentials OpenSSH version 8.2 or later is required.\nIt is then possible to generate a credential file with:\n\n----\n$ ssh-keygen -t ecdsa-sk -f ./credential.ssh\n----\n\nSupported key types are ecdsa-sk and ed25519-sk. Note that passphrase protected\ncredentials are currently not supported.\n\nTo use this credential the `authfile` parameter should be set to the path of\nthe file `credential.ssh` and the `sshformat` option should also be set. If the\n`authfile` parameter is not set, it defaults to `~/.ssh/id_ecdsa_sk`.\n\n=== Multiple FIDO Authenticators\n\nMultiple FIDO authenticators are supported. If more than one authenticator is\nspecified, authentication against them is attempted sequentially as they are\ndefined in the authorization mapping file. If during an authentication attempt\na connected authenticator is removed or a new one is plugged in, the authentication\nrestarts from the top of the list.\n\n[[confFile]]\n== Configuration file\n\nA configuration file can be used to set the default\n\u003c\u003cmoduleArguments,module arguments\u003e\u003e.\n\n- The file has a `name = value` format, with comments starting with the `#`\n  character.\n\n- White spaces at the beginning of line, end of line, and around the `=` sign\n  are ignored.\n\n- Any `conf` argument in the configuration file is ignored.\n\n- The maximum size for the configuration file is 4 KiB.\n\n- The default path for the configuration file is `/etc/security/pam_u2f.conf`.\n  Note that it may have been set to another value by the distribution. The\n  default file is allowed to not exist. An alternative path may be set in the\n  module command line options.\n\n- The options specified on the module command line override the values from the\n  configuration file.\n\n== SELinux Note\n\nDue to an issue with Fedora Linux, and possibly with other\ndistributions that use SELinux, a system configured with pam-u2f may\nend up in a situation where access to the credentials file is denied.\nIf the `nouserok` option is also set, this will result in a successful\nauthentication within the module, without using the FIDO\nauthenticator.\n\nIn order to correctly update the security context the command\n`fixfiles onboot` should be used on existing installations\n\nMoreover, to allow read access to an authfile or directory placed in a\nnon-standard location, the command\n\n----\n# chcon -R -t auth_home_t /path/to/target\n----\n\nshould be used.\n\nFor more information see\nhttps://access.redhat.com/security/cve/CVE-2020-24612[HERE].\n\n== FIDO U2F vs FIDO2\nAuthenticators that solely support FIDO U2F and not FIDO2, e.g. the YubiKey 4\nseries, can be used only in conjunction with compatible features. Enabling\nincompatible features, such as setting the `+pin` or the `+verification` flags\nin the `authfile` or the corresponding options in the PAM service configuration\ncauses the authenticator to be ignored.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyubico%2Fpam-u2f","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyubico%2Fpam-u2f","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyubico%2Fpam-u2f/lists"}