1Pluggable Authentication Module (PAM) Universal 2nd Factor (U2F) 2================================================================ 3 4image:https://travis-ci.org/Yubico/pam-u2f.svg?branch=master["Build Status", link="https://travis-ci.org/Yubico/pam-u2f"] 5image:https://scan.coverity.com/projects/5711/badge.svg["Coverity Status", link=https://scan.coverity.com/projects/5711] 6 7This module implements PAM over U2F, providing an easy way to integrate the 8YubiKey (or other U2F compliant authenticators) into your existing 9infrastructure. 10 11[[building]] 12Building 13-------- 14 15This project uses 'autoconf', 'automake', 'pkg-config' and 'libtool' 16to achieve portability and ease of use. 17 18In addition, both the Yubico U2F https://developers.yubico.com/libu2f-host['libu2f-host-dev'] and 19https://developers.yubico.com/libu2f-server['libu2f-server-dev'] libaries are needed. 20 21 Debian: apt-get install autoconf automake libtool pkg-config libu2f-host-dev libu2f-server-dev --no-install-recommends 22 23If you downloaded a tarball, build it as follows. 24 25----------- 26 $ ./configure 27 $ make 28----------- 29 30Building from Git 31----------------- 32 33You may check out the sources using Git with the following command: 34 35----------- 36 $ git clone git://github.com/Yubico/pam-u2f.git 37----------- 38 39This will create a directory 'pam-u2f'. Enter the directory: 40 41----------- 42 $ cd pam-u2f 43----------- 44 45'Autoconf', 'automake', 'libtool', and 'libpam' must be installed. 'AsciiDoc' and 'xsltproc' are used to 46generate the manpages. 47 48 Debian: apt-get install autoconf automake libtool libpam-dev libu2f-host-dev libu2f-server-dev asciidoc xsltproc libxml2-utils docbook-xml --no-install-recommends 49 50Generate the build system using: 51 52----------- 53 $ autoreconf --install 54----------- 55 56Then build as usual, see above under <<building,Building>>. 57 58Installation 59------------ 60 61Once the module is built copy the file +pam_u2f.so+ to the correct 62directory for your system. Typically +/lib/security/+ or 63+/lib/x86_64-linux-gnu/security/+. This is automated by +make install+ 64assuming that the pam directory chosen by +configure+ is correct. 65If that is not the case it can be specified with +./configure --with-pam-dir=+. 66 67Create a file for a new service in +/etc/pam.d/+ or edit an already 68existing one by adding a line similar to this: 69 70---- 71auth sufficient pam_u2f.so debug 72---- 73 74Supported parameters for the module are: 75 76[horizontal] 77debug:: 78Enables debug output 79 80debug_file:: 81Filename to write debugging messages to. **If this file is missing, nothing will be logged**. This regular file **has to be created by the user** 82or **must exist and be a regular file** for anything getting logged to it. It is not created by pam-u2f on purpose (for security considerations). 83This filename may be alternatively set to "stderr" (default), "stdout", or "syslog". 84 85origin=origin:: 86Set the origin for the U2F authentication procedure. 87If no value is specified, the origin "pam://$HOSTNAME" is used. 88 89appid=appid:: 90Set the https://developers.yubico.com/U2F/App_ID.html[application ID] for the U2F authentication procedure. 91If no value is specified, the same value used for origin is taken 92("pam://$HOSTNAME" if also origin is not specified). 93 94authfile=file:: 95Set the location of the file that holds the mappings of user names 96to keyHandles and user keys. The format is 97+username:first_keyHandle,first_public_key: 98second_keyHandle,second_public_key:...+ the default location of the 99file is $XDG_CONFIG_HOME/Yubico/u2f_keys. If the environment variable 100is not set, $HOME/.config/Yubico/u2f_keys is used. 101(more on <<files,Authorization Mapping Files>>). An individual (per user) file 102may be configured, see <<individualAuth>>. 103 104authpending_file=file:: 105Set the location of the file that is used for touch request notifications. 106This file will be opened when pam-u2f starts waiting for a user to touch the device, 107and will be closed when it no longer waits for a touch. 108Use inotify to listen on these events, or a more high-level tool like https://github.com/maximbaz/yubikey-touch-detector[yubikey-touch-detector]. 109Set an empty value in order to disable this functionality, like so: `authpending_file=`. 110Default value: /var/run/user/$UID/pam-u2f-authpending 111 112nouserok:: 113Set to enable authentication attempts to succeed even if the user trying to 114authenticate is not found inside authfile or if authfile is missing/malformed. 115 116openasuser:: 117Setuid to the authenticating user when opening the authfile. Useful when the 118user's home is stored on an NFS volume mounted with the root_squash option 119(which maps root to nobody which will not be able to read the file). 120Note that after release 1.0.8 this is done by default when no global 121authfile or XDG_CONFIG_HOME environment variable has been set. 122 123alwaysok:: 124Set to enable all authentication attempts to succeed (aka presentation mode). 125 126max_devices=n_devices:: 127Maximum number of devices allowed per user (default is 24). Devices specified 128in the authentication file that exceed this value will be ignored. 129 130interactive:: 131Set to prompt a message and wait before testing the presence of a U2F device. 132Recommended if your device doesn't have a tactile trigger. 133 134[prompt=your prompt here]:: 135Set individual prompt message for interactive mode. Watch the square brackets 136around this parameter to get spaces correctly recognized by PAM. 137 138manual:: 139Set to drop to a manual console where challenges are printed on screen 140and response read from standard input. Useful for debugging and SSH sessions 141without U2F-support from the SSH client/server. 142If enabled, interactive mode becomes redundant and has no effect. 143 144cue:: 145Set to prompt a message to remind to touch the device. 146 147[cue_prompt=your prompt here]:: 148Set individual prompt message for the cue option. Watch the square brackets 149around this parameter to get spaces correctly recognized by PAM. 150 151nodetect:: 152Set to skip detecting if a suitable U2F token is inserted before performing 153the full tactile authentication. This detection was created to avoid 154emitting the "cue" message if no suitable token exists, because doing so 155leaks information about the authentication stack if a token is inserted but 156not configured for the authenticating user. However, it was found that 157versions of libu2f-user 1.1.5 or less has buggy iteration/sleep behavior 158which causes a 1-second delay to occur for this initial detection. For this 159reason, as well as the possibility of hypothetical tokens that do not 160tolerate this double authentication, the "nodetect" option was added. 161 162userpresence=int:: 163If 1, request user presence during authentication. If 0, do not request user 164presence during authentication. Otherwise, fallback to the authenticator's 165default behaviour. 166 167userverification=int:: 168If 1, request user verification during authentication. If 0, do not request 169user verification during authentication. Otherwise, fallback to the 170authenticator's default behaviour. 171 172pinverification=int:: 173If 1, request PIN verification during authentication. If 0, do not request 174PIN verification during authentication. Otherwise, fallback to the 175authenticator's default behaviour. 176 177[[files]] 178Authorization Mapping Files 179--------------------------- 180A mapping must be made between the YubiKey token and the user name, 181see <<registration, here>> for details on how to perform the registration 182using the bundled tool. 183 184There are two ways to do this, either centrally in one file, or 185individually, where users can create the mapping in their home directories. 186If the central authorization mapping file is being used, user home directory 187mappings will not be used and the opposite applies if user home directory 188mappings are being used, the central authorization mappings file will not 189be used. 190 191By default the mapping file inside a home directory will be opened as 192the target user, whereas the central file will be opened as `root`. If 193the `XDG_CONFIG_HOME` variable is set, privileges will not be dropped 194unless the `openasuser` configuration setting is set. 195 196IMPORTANT: Using pam-u2f to secure the login to a computer while 197storing the mapping file in an encrypted home directory, will result 198in the impossibility of logging into the system. The partition is 199decrypted after login and the mapping file can not be accessed. 200 201== Central authorization mapping 202Create a file e.g. `/etc/u2f_mappings`., The file must contain 203a user name, the number of registered Yubikeys and the information 204obtained during the registration procedure. 205 206The mappings should look like this, one per line: 207 208 <username1>:<KeyHandle1>,<UserKey1>:<KeyHandle2>,<UserKey2>:... 209 <username2>:<KeyHandle1>,<UserKey1>:<KeyHandle2>,<UserKey2>:... 210 211Now add `authfile=/etc/u2f_mappings` to your PAM configuration line, so it 212looks like: 213 214 auth sufficient pam_u2f.so authfile=/etc/u2f_mappings 215 216If you do not set the `openasuser` setting, the authfile will be opened 217and parsed as `root` so make sure it has the correct owner and 218permissions set. 219 220IMPORTANT: On dynamics networks (e.g. where hostnames are set by DHCP), 221users should not rely on the default origin and appid ("pam://$HOSTNAME") 222but set those parameters explicitly to the same value. 223 224[[individualAuth]] 225== Individual authorization mapping by user 226Each user creates a `.config/Yubico/u2f_keys` (default) file inside their 227home directory and places the mapping in that file. You may want to specify 228a different per user file (relative to the users' home dir), i.e. 229`.ssh/u2f_keys`. Bear in mind, setting an absolute path here is possible although 230very likely a fragile setup, and probably not exhibiting the intended behaviour. 231 232The file must have only one line: 233 234 <username>:<KeyHandle1>,<UserKey1>:<KeyHandle2>,<UserKey2>:... 235 236This is much the same concept as the SSH authorized_keys file. 237 238In this case, pam-u2f will drop privileges and read the mapping file 239as that user. This happens regardless of the `openasuser` option being 240set. 241 242Note that if you set the XDG_CONFIG_HOME variable, privileges will not 243be dropped by default. Consider also setting `openasuser` in that case. 244 245[[registration]] 246Obtaining key-handles and public keys 247------------------------------------- 248 249In order to obtain the required information for the authentication procedure, 250a token should be first registered. This can be done by using the command line 251configuration tool provided with the module: 252 253---- 254$ pamu2fcfg -uusername -opam://myorigin -ipam://myappid 255---- 256 257the tool will register a connected token by using the specified origin and 258appid. If neither are specified they will default to +pam://$HOSTNAME+. 259During the U2F registration, the user is required to touch the token. 260On success the tool prints to standard output a configuration line that 261can be directly used with the module. For additional information on the 262tool read the relative manpage (+man pamu2fcfg+) 263 264[[devices]] 265Multiple Devices 266---------------- 267 268Multiple devices are supported. If more than one device is specified, 269authentication against them is attempted sequentially as they are defined 270in the configuration file of the module. If during an authentication 271attempt a connected device is removed or a new device is plugged in, 272the authentication restarts from the top of the list. 273
