{"id":13513031,"url":"https://github.com/Yubico/yubico-pam","last_synced_at":"2025-03-31T00:30:48.867Z","repository":{"id":870498,"uuid":"1346154","full_name":"Yubico/yubico-pam","owner":"Yubico","description":"Yubico Pluggable Authentication Module (PAM)","archived":true,"fork":false,"pushed_at":"2024-11-19T16:19:33.000Z","size":889,"stargazers_count":709,"open_issues_count":60,"forks_count":122,"subscribers_count":79,"default_branch":"master","last_synced_at":"2025-03-05T02:04:14.209Z","etag":null,"topics":["c","pam-module","yubikey"],"latest_commit_sha":null,"homepage":"https://developers.yubico.com/yubico-pam","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":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2011-02-09T12:00:31.000Z","updated_at":"2025-03-04T10:11:45.000Z","dependencies_parsed_at":"2024-12-24T11:09:15.551Z","dependency_job_id":"6fd33edd-81fa-49a6-9844-b3026cdb0995","html_url":"https://github.com/Yubico/yubico-pam","commit_stats":{"total_commits":720,"total_committers":59,"mean_commits":"12.203389830508474","dds":0.6208333333333333,"last_synced_commit":"5719a2f859144948de7b67b6d706d6ed403b219f"},"previous_names":[],"tags_count":44,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yubico%2Fyubico-pam","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yubico%2Fyubico-pam/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yubico%2Fyubico-pam/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yubico%2Fyubico-pam/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Yubico","download_url":"https://codeload.github.com/Yubico/yubico-pam/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246399816,"owners_count":20770907,"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":["c","pam-module","yubikey"],"created_at":"2024-08-01T04:00:36.655Z","updated_at":"2025-03-31T00:30:48.314Z","avatar_url":"https://github.com/Yubico.png","language":"C","funding_links":[],"categories":["Tools","C"],"sub_categories":["Third-party Tools"],"readme":"== Yubico PAM module\n\nThe Yubico PAM module provides an easy way to integrate the YubiKey\ninto your existing user authentication infrastructure. PAM is used by\nGNU/Linux, Solaris and Mac OS X for user authentication, and by other\nspecialized applications such as NCSA MyProxy.\n\nStatus and Roadmap\n------------------\n\nThe module is working for multi-user systems. The primary mode of\noperation is by doing online validation using a YubiKey validation\nservice (such as the YubiCloud, or a private one configured using\nthe 'urllist' parameter).\n\nIn version 2.6, offline validation was also made possible through\nthe use of HMAC-SHA1 Challenge-Response found in YubiKey 2.2 and\nlater. This has introduced a dependency of libykpers-1 from the\nykpersonalize package. Pass `--without-cr` to `configure` to avoid\nthis dependency.\n\nThe development community is co-ordinated via\nhttps://github.com/Yubico/yubico-pam[the GitHub project page].\n\nThe project is licensed under a BSD license. See the file COPYING for\nexact wording. For any copyright year range specified as YYYY-ZZZZ in\nthis package note that the range specifies every single year in that\nclosed interval.\n\n\nBuilding from Git\n-----------------\n\nSkip to the next section if you are using an official packaged\nversion.\n\nYou may check out the sources using Git with the following command:\n\n------\n$ git clone https://github.com/Yubico/yubico-pam.git\n------\n\nThis will create the directory `yubico-pam`.\n\nAutoconf, automake, libtool, asciidoc, xsltproc and docbook-xsl must be installed to create a\ncompilable source tree.\n\nGenerate the build system using:\n\n------\n$ cd yubico-pam\n$ autoreconf --install\n------\n\n\n=== Building\n\nYou will need to have https://developers.yubico.com/yubico-c-client[libykclient]\n(ykclient.h, libykclient.so) and libpam-dev (security/pam_appl.h, libpam.so)\ninstalled. It in turn requires cURL, which you need to have installed, and\nhttps://developers.yubico.com/yubico-c[libyubikey].\n\nThe Challenge-Response offline authentication requires libykpers-1\nfrom the \nhttps://developers.yubico.com/yubikey-personalization[yubikey-personalization]\nproject:\n\nThe selftests require perl with the module Net::LDAP::Server installed.\n\nThe build system uses Autoconf, to set up the build system run:\n\n ./configure\n\nUse --without-ldap to disable ldap support.\n\nThen build the code, run the self-test and install the binaries:\n\n make check install\n\n \n== Installation\n\n=== Fedora/EPEL\n\nThere is already a package in Fedora/EPEL of yubico-pam that can be installed\nby using yum:\n\n $ sudo yum install pam_yubico\n\n\n=== Ubuntu PPA\n\nThere is an Ubuntu PPA (Personal Package Archive) for yubico-pam that\ncan be installed using the following commands on reasonably modern\nUbuntu platforms :\n\n  $ sudo add-apt-repository ppa:yubico/stable\n  $ sudo apt-get update\n  $ sudo apt-get install libpam-yubico\n\nSee the file `/usr/share/doc/libpam-yubico/README.Debian` after installing.\n\n\n=== FreeBSD ports\n\nyubico-pam and the supporting Yubico packages have corresponding FreeBSD ports. To install:\n\n  $ cd /usr/ports/security/pam_yubico\n  $ make install clean\n\nAdvanced configuration notes are available http://mjslabs.com/yubihow.html[here].\n\n\nConfiguration\n-------------\n\nInstall it in your PAM setup by adding a line to an appropriate file\nin `/etc/pam.d/`:\n\n----\nauth sufficient pam_yubico.so id=[Your API Client ID] debug\n----\n\nand move pam_yubico.so into /lib/security/ (or wherever PAM modules\nlive in your system) :\n\n----\nmv /usr/local/lib/security/pam_yubico.so /lib/security/\n----\n\nFor more information, see the project documentation.\n\nSupported PAM module parameters are:\n\n[horizontal]\nauthfile::\nTo indicate the location of the file that holds the\nmappings of YubiKey token IDs to user names.\n\nid:: \nYour API Client ID in the Yubico validation server.\nIf you want to use the default YubiCloud service, \ngo https://upgrade.yubico.com/getapikey[here].\n\nkey::\nTo indicate your client key in base64 format.\nThe client key is also known as API key, and provides\nintegrity in the communication between the client (you)\nand the validation server.\nIf you want to get one for use with the default YubiCloud\nservice, go https://upgrade.yubico.com/getapikey[here].\n\ndebug:: to enable debug output.\n\ndebug_file:: filename to write debug to, file must exist and\nbe a regular file. stdout is default.\n\nalwaysok::\nto enable all authentication attempts to succeed\n(aka presentation mode).\n\ntry_first_pass::\nBefore prompting the user for their password, the module\nfirst tries the previous stacked module´s password in case\nthat satisfies this module as well.\n\nuse_first_pass::\nThe argument use_first_pass forces the module to use a previous\nstacked modules password and will never prompt the user - if no\npassword is available or the password is not appropriate, the user\nwill be denied access.\n\nalways_prompt::\nIf set, don't attempt to do a lookup to determine if the user has a\nYubiKey configured but instead prompt for one no matter what. This\nis useful in the case where ldap_bind_as_user is enabled but this\nmodule is being used to read the user's password (in a YubiKey+OTP\nauth scenario).\n\nnullok::\nIf set, don't fail when there are no tokens declared for the user\nin the authorization mapping files or in LDAP.\nThis can be used to make YubiKey authentication optional unless\nthe user has associated tokens.\n\nldap_starttls::\nIf set, issue a STARTTLS command to the LDAP connection before\nattempting to bind to it. This is a common setup for servers\nthat only listen on port 389 but still require TLS.\n\nldap_bind_as_user::\nIf set, use the user logging in to bind to LDAP. This will use the\npassword provided by the user via PAM. If this is set, ldapdn\nand uid_attr must also be set.  Enabling this will cause\n'ldap_bind_user' and 'ldap_bind_password' to be ignored\n\nurllist::\nList  of  URL  templates to be used. This is set by calling\nykclient_set_url_bases. The list should be in the format :\n`https://server/wsapi/2.0/verify;https://server/wsapi/2.0/verify`\n\nurl::\nThis option should not be used, please use the urllist\noption instead.\nSpecify the URL template to use, this is set by calling\nyubikey_client_set_url_template, which defaults to:\n`https://api.yubico.com/wsapi/verify?id=%d\u0026otp=%s`\nor\n`https://api.yubico.com/wsapi/2.0/verify?id=%d\u0026otp=%s`\ndepending on your version of yubico-c-client.\n\ncapath::\nspecify the path where X509 certificates are stored. This is\nrequired if 'https' or 'ldaps' are used in 'url' and 'ldap_uri'\nrespectively.\n\ncainfo::\nOption to allow usage of a CA bundle instead of path.\n\nproxy::\nspecify a proxy to connect to the validation server. Valid schemes are\nhttp://, https://, socks4://, socks4a://, socks5:// or socks5h://.\nSocks5h asks the proxy to do the dns resolving. If no scheme or port is\nspecified HTTP proxy port 1080 will be used.\n\nverbose_otp::\n   This argument is used to show the OTP (One-Time Password) when it\n   is entered, i.e. to enable terminal echo of entered characters.\n   You are advised to not use this, if you are using two factor\n   authentication because that will display your password on the\n   screen.\n   This requires the service using the PAM module to\n   display custom fields. This option can not be used with OpenSSH.\n\nldap_uri:: specify the LDAP server URI (e.g. ldap://localhost).\n\nldapserver::\nspecify the LDAP server host (default LDAP port is used).\n_Deprecated. Use \"ldap_uri\" instead._\n\nldapdn::\nspecify the dn where the users are stored\n(eg: ou=users,dc=domain,dc=com).\n\nldap_clientcertfile::\nThe path to a client cert file to use when talking to the LDAP\nserver.  Note this requires 'ldap_clientkeyfile' to be set as well.\n\nldap_clientkeyfile::\nThe path to a key to be used with the client cert when talking to\nthe LDAP server.  Note this requires 'ldap_clientcertfile' to be\nset as well.\n\nldap_bind_user::\nThe user to attempt a LDAP bind as.\n\nldap_bind_password::\nThe password to use on LDAP bind.\n\nldap_filter::\nAn LDAP filter to use for attempting to find the correct object in LDAP. In this string `%u` will be replaced with the username.\n\nldap_cacertfile::\nCA certifcate file for the LDAP connection.\n\nuser_attr:: specify the LDAP attribute used to store user names (eg:cn).\n\nyubi_attr::  specify the LDAP attribute used to store the YubiKey ID.\n\nyubi_attr_prefix::\nspecify the prefix of the LDAP attribute's value, in case\nof a generic attribute, used to store several types of IDs.\n\ntoken_id_length::\nLength of ID prefixing the OTP (this is 12 if using the\nYubiCloud).\n\nmode::\nMode of operation. Use \"client\" for online validation with\na YubiKey validation service such as the YubiCloud, or use\n\"challenge-response\" for offline validation using YubiKeys\nwith HMAC-SHA-1 Challenge-Response configurations. See the\nman-page ykpamcfg(1) for further details on how to configure\noffline Challenge-Response validation.\n\nchalresp_path::\nDirectory that is used to store the challenge files in case of a system-wide\nconfiguration (in contrast to challenge files being stored in a user's home\ndirectory). This location should be only readable and writable by root. Refer\nto `Authentication_Using_Challenge-Response.adoc` for more information about\nsuch a setup.\n\nmysql_server::\nHostname/Adress of mysql server to use for mapping.\n\nmysql_port::\nNetwork port of mysql server.\n\nmysql_user::\nUser for accessing the mysql database.\n\nmysql_password::\nPassword for the mysql user.\n\nmysql_database::\nThe mysql database to use.\n\nIf you are using \"debug\" you may find it useful to create a\nworld-writable log file:\n\n[source, sh]\n----\ntouch /var/run/pam-debug.log\nchmod go+w /var/run/pam-debug.log\n----\n\nNOTE: Please remember, physical access to systems often allows the circumvention of security controls. If an attacker has physical access to your system (such as a laptop left in a hotel room) and can boot into single user mode, they can disable yubico-pam in your system configuration.\n\n\nAuthorization Mapping Files\n---------------------------\nA mapping must be made between the YubiKey token ID and the user ID it is\nattached to. There are two ways to do this, either centrally in one file, or\nindividually, where users can create the mapping in their home directories.\nIf the central authorization mapping file is being used, user home directory\nmappings will not be used and the opposite applies if user home directory\nmappings are being used, the central authorization mappings file will not\nbe used.\n\n\n=== Central authorization mapping\nCreate a `/etc/yubikey_mappings`, the file must contain a user name and the\nYubiKey token ID separated by colons (same format as the passwd file) for\neach user you want to allow onto the system using a YubiKey.\n\nThe mappings should look like this, one per line:\n\n \u003cfirst user name\u003e:\u003cYubiKey token ID1\u003e:\u003cYubiKey token ID2\u003e:….\n \u003csecond user name\u003e:\u003cYubiKey token ID3\u003e:\u003cYubiKey token ID4\u003e:….\n\nNow add `authfile=/etc/yubikey_mappings` to your PAM configuration line, so it\nlooks like:\n\n auth sufficient pam_yubico.so id=[Your API Client ID] authfile=/etc/yubikey_mappings\n\n \n=== Individual authorization mapping by user\nEach user creates a `~/.yubico/authorized_yubikeys` file inside of their home\ndirectory and places the mapping in that file, the file must have only one\nline:\n\n\n \u003cuser name\u003e:\u003cYubiKey token ID1\u003e:\u003cYubiKey token ID2\u003e\n\n\nThis is much the same concept as the SSH authorized_keys file.\n\n\nObtaining the YubiKey token ID (a.k.a. public ID)\n-------------------------------------------------\n\nYou can obtain the YubiKey token ID in several ways. One is by\nremoving the last 32 characters of any OTP (One Time Password)\ngenerated with your YubiKey. Another is by using the\nhttp://demo.yubico.com/php-yubico/Modhex_Calculator.php[modhex calculator].\n\nEnter your YubiKey OTP and convert it, your YubiKey token ID is 12\ncharacters and listed as:\n\n   Modhex encoded: XXXXXXX\n\nNot sure what that last bit meant? Here is how to get a copy of your OTP.\n\n=== Fast way\n. Open a terminal\n. Press the YubiKey's button\n  It will output an OTP into the shell:\n+\n[source, sh]\n------\n$ cccccccgklgcvnkcvnnegrnhgrjkhlkfhdkclfncvlgj\nbash: cccccccgklgcvnkcvnnegrnhgrjkhlkfhdkclfncvlgj: command not found\n------\n+\nThis can be pasted into the Modhex_Calculator page.\n\n=== Harder way\nThis requires you to have the pam module enabled with 'debug' turned on. When\nprompted for the YubiKey press the button. The pam module will print out debug\ninformation including the OTP and ID of your token to the shell -- copy the ID\ninto your config file and you should be up and going.\n\n------\nYubiKey for `youruser':\n[pam_yubico.c:pam_sm_authenticate(867)] conv returned 44 bytes\n[pam_yubico.c:pam_sm_authenticate(885)] Skipping first 0 bytes. Length is 44, token_id set to 12 and token OTP always 32.\n[pam_yubico.c:pam_sm_authenticate(892)] OTP: ccccccclabcabkhbdncicglfltnukadfoifadfhhhhfe ID: cccccclabcab\n------\n\n\nYubico PAM module and SELinux.\n------------------------------\nUsers with SELinux in enforcing mode (the default on Fedora 17+) may experience\nlogin problems with services including those validated via\npolkit-agent-helper-1, sshd and login.\n\nThis is https://bugzilla.redhat.com/show_bug.cgi?id=841693#c3[documented in Red Hat bugzilla]\nincluding a work around for ssh (Equivalent files could be created for\nother services). Systems in 'permissive' mode will generate AVC warnings but\nauthentication will succeed.\n\nTo determine if you have SELinux enforcing or not run the `sestatus` command.\n\nExamples\n--------\n\nIf you want to use the YubiKey to authenticate you on Linux console\nlogins, add the following to the top of `/etc/pam.d/login`:\n\n   auth sufficient pam_yubico.so id=[Your API Client ID] debug\n\nOpenVPN and ActiveDirectory\n---------------------------\nSee Michael Ludvig's sample Active Directory schema extensions for YubiKey public ID attribute storage / association with a particular user account:  https://github.com/mludvig/yubikey-ldap/tree/master/microsoft-schema\n\ncreate file '/etc/pam.d/openvpn':\n\n   auth  required  pam_yubico.so ldap_uri=ldap://contoso.com debug id=[Your API ID] yubi_attr=YubiKeyID\n      ldapdn=DC=contoso,DC=com\n      ldap_filter=(\u0026(sAMAccountName=%u)(objectClass=user)(memberOf=CN=somegroup,DC=contoso,DC=com))\n      [ldap_bind_user=CN=binduser,OU=Service Accounts,DC=contoso,DC=com] ldap_bind_password=bind_password try_first_pass\n   account required  pam_yubico.so\n\ncreate file 'openvpn.conf'\n\n   plugin openvpn-plugin-auth-pam.so openvpn\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FYubico%2Fyubico-pam","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FYubico%2Fyubico-pam","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FYubico%2Fyubico-pam/lists"}