1PAM_U2F(8) 2========== 3:doctype: manpage 4:man source: pam-u2f 5:man manual: PAM U2F Module Manual 6 7== NAME 8pam_u2f - Module for U2F authentication 9 10== SYNOPSIS 11*pam_u2f* [...] 12 13== DESCRIPTION 14The module provides U2F authentication against Yubikeys and other compliant authenticators. 15 16== OPTIONS 17*debug*:: 18Enables debug output 19 20*debug_file*:: 21Filename to write debugging messages to. *If this file is missing, nothing will be logged*. This regular file *has to be created by the user* 22or *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). 23This filename may be alternatively set to "stderr" (default), "stdout", or "syslog". 24 25*origin*=_origin_:: 26Set the origin for the U2F authentication procedure. If no value is specified, the origin "pam://$HOSTNAME" is used. 27 28*appid*=_appid_:: 29Set the application ID for the U2F authentication procedure. If no value is specified, the same value used for origin is taken ("pam://$HOSTNAME" if also origin is not specified). 30 31*authfile*=_file_:: 32Set the location of the file that holds the mappings of user names to keyHandles and user keys. The format is username:keyHandle1,public_key1:keyHandle2,public_key2:... the default location of the file is $XDG_CONFIG_HOME/Yubico/u2f_keys. If the environment variable is not set, $HOME/.config/Yubico/u2f_keys is used. 33An individual (per user) file may be configured relative to the users' home dirs, i.e. ".ssh/u2f_keys". 34 35*authpending_file*=_file_:: 36Set the location of the file that is used for touch request notifications. This file will be opened when pam-u2f starts waiting for a user to touch the device, and will be closed when it no longer waits for a touch. Use inotify to listen on these events, or a more high-level tool like yubikey-touch-detector. Default value: /var/run/user/$UID/pam-u2f-authpending. Set an empty value in order to disable this functionality, like so: "authpending_file=". 37 38*nouserok*:: 39Set to enable authentication attempts to succeed even if the user trying to authenticate is not found inside authfile or if authfile is missing/malformed. 40 41*openasuser*:: 42Setuid to the authenticating user when opening the authfile. Useful when the user's home is stored on an NFS volume mounted with the root_squash option (which maps root to nobody which will not be able to read the file). 43Note that after release 1.0.8 this is done by default when no global authfile or XDG_CONFIG_HOME environment variable has been set. 44 45*alwaysok*:: 46Set to enable all authentication attempts to succeed (aka presentation mode). 47 48*max_devices*=_n_devices_:: 49Maximum number of devices allowed per user (default is 24). Devices specified 50in the authentication file that exceed this value will be ignored. 51 52*interactive*:: 53Set to prompt a message and wait before testing the presence of a U2F device. Recommended if your device doesn't have tactile trigger. 54 55*[prompt=your prompt here]*:: 56Set individual prompt message for interactive mode. Watch the square brackets 57around this parameter to get spaces correctly recognized by PAM. 58 59*manual*:: 60Set to drop to a manual console where challenges are printed on screen and response read from standard input. Useful for debugging and SSH sessions without U2F-support from the SSH client/server. If enabled, interactive mode becomes redundant and has no effect. 61 62*cue*:: 63Set to prompt a message to remind to touch the device. 64 65*[cue_prompt=your prompt here]*:: 66Set individual prompt message for the cue option. Watch the square brackets 67around this parameter to get spaces correctly recognized by PAM. 68 69*nodetect*:: 70Skip detecting if a suitable key is inserted before performing a full authentication. See *NOTES* below. 71 72*userpresence*=_int_:: 73If 1, require user presence during authentication. If 0, do not request user 74presence during authentication. Otherwise, fallback to the authenticator's 75default behaviour. 76 77*userverification*=_int_:: 78If 1, require user verification during authentication. If 0, do not request 79user verification during authentication. Otherwise, fallback to the 80authenticator's default behaviour. 81 82*pinverification*=_int_:: 83If 1, require PIN verification during authentication. If 0, do not request 84PIN verification during authentication. Otherwise, fallback to the 85authenticator's default behaviour. 86 87== EXAMPLES 88 89auth sufficient pam_u2f.so debug origin=pam://$HOSTNAME appid=pam://$HOSTNAME 90 91auth required pam_u2f.so origin=http://example.com appid=http://example.com authfile=/etc/yubikey_mappings 92 93== CAVEATS 94By default the mapping file inside a home directory will be opened as 95the target user, whereas the central file will be opened as "root". If 96the "XDG_CONFIG_HOME" variable is set, privileges will not be dropped 97unless the "openasuser" configuration setting is set. 98 99Using pam-u2f to secure the login to a computer while 100storing the mapping file in an encrypted home directory, will result 101in the impossibility of logging into the system. The partition is 102decrypted after login and the mapping file can not be accessed. 103 104== NOTES 105The "nodetect" option should be used with caution. pam_u2f checks that a 106key configured for the user is inserted before performing the full tactile 107authentication. This detection is done by sending a "check-only" 108authentication request to all inserted tokens to so see if at least one of 109them responds affirmatively to one or more of the keyhandles configured for 110the user. By doing this, pam_u2f can avoid emitting the "cue" prompt (if 111configured), which can cause some confusing UI issues if the cue is emitted 112followed by the underlying library immediately failing the tactile 113authentication. This option is also useful to avoid an unintended 1-second 114delay prior to the tactile authentication caused by versions of libu2f-host 115\<= 1.1.5. 116 117If pam_u2f is configured to "cue" and "nodetect", an attacker can determine 118that pam_u2f is part of the authentication stack by inserting any random 119U2F token and performing an authentication attempt. In this scenario, the 120attacker would see the cue message followed by an immediate failure, 121whereas with detection enabled, the U2F authentication will fail silently. 122Understand that an attacker could choose a U2F token that alerts him or 123her in some way to the "check-only" authentication attempt, so this 124precaution only pushes the issue back a step. 125 126In summary, the detection feature was added to avoid confusing UI issues 127and to prevent leaking information about the authentication stack in very 128specific scenario when "cue" is configured. The "nodetect" option was added 129to avoid buggy sleep behavior in older versions of libu2f-host and for 130hypothetical tokens that do not tolerate the double authentication. 131Detection is performed, and likewise "nodetect" honored, regardless of 132whether "cue" is also specified. 133 134== BUGS 135Report pam-u2f bugs in the issue tracker: https://github.com/Yubico/pam-u2f/issues 136 137== SEE ALSO 138*pam*(7) 139 140The pam-u2f home page: https://developers.yubico.com/pam-u2f/ 141 142YubiKeys can be obtained from Yubico: http://www.yubico.com/ 143