1== Setting up your YubiKey for challenge response authentication on Max OS X == 2 3This article explains the process to get the challenge-response 4authentication possible with newer YubiKeys working on Mac OS X. Since 5Mac OS X uses PAM like most other Unix/POSIX systems do, most of this 6should apply to other operating systems, too. 7 8=== Getting yubico-pam === 9 10First you will have to install yubico-pam and its dependencies 11required for challenge-response authentication. Use your 12distribution's package manager to get it, or build from source. If 13you're on OS X you can use http://www.macports.org[MacPorts] to 14install yubico-pam: 15 16 sudo port install yubico-pam 17 18NOTE: This will probably not work in non-superuser installations 19 of MacPorts, because it needs to place the yubico PAM module into 20 `/usr/lib/pam`. 21 22=== Configuring your YubiKey === 23 24The next step would be to set up your YubiKey for challenge-response 25authentication, if you haven't done so already. Although this is 26possible with the command line `ykpersonalize` tool, the GUI "YubiKey 27Personalization Tool" is a more comfortable way to do this. 28 291. Plug in your YubiKey and start the YubiKey Personalization Tool 30+ 31NOTE: YubiKey Personalization Tool shows whether your YubiKey supports challenge-response in the lower right. 322. Click 'Challenge-Response' 333. Select HMAC-SHA1 mode. Apparently Yubico-OTP mode doesn't work with yubico-pam at the moment. 344. Select the configuration slot you want to use 35(this text assumes slot two, but it should be easy enough to adapt the instructions if you prefer slot 1) 365. Select whether you want to require pressing the button for authentication 37+ 38NOTE: If you enable this, you will have to press the button twice for each authentication with yubico-pam. This is because the PAM module does not only send the challenge on file and checks whether the response matches, but also generates a new challenge-response pair on success. 396. Use 'Variable input' as HMAC-SHA1 mode 40+ 41WARNING: Using 'Fixed 64 byte input' for this value made my YubiKey always return the same response regardless of what the challenge was. Since this defies the purpose of challenge-response think twice and test before you use this! 427. Generate a secret key 43You won't need this key again, it's sufficient to have it on your YubiKey. Note that the YubiKey Personalization Tool by default logs the key to configuration_log.csv in your home directory. Consider turning this off in the settings before writing or shredding the file after writing. 448. Click 'Write Configuration' 45 46=== Configuring your user account to accept the YubiKey === 47 48After setting up your YubiKey you need to configure your account to 49accept this YubiKey for authentication. To do this, open a terminal 50and run 51 52 # create the directory where ykpamcfg will store the initial challenge 53 mkdir -m0700 -p ~/.yubico 54 # get the initial challenge from the YubiKey 55 ykpamcfg -2 56 57If you used slot 1 above, replace -2 with -1. If you configured your 58YubiKey to require a button press the LED on the YubiKey will start 59blinking; press the button to send a challenge-response 60response. `ykpamcfg` should finish successfully telling you that it 61stored the initial challenge somewhere inside your home directory: 62 63---- 64Stored initial challenge and expected response in '/path/to/your/home/.yubico/challenge-KEYID'. 65---- 66 67This step will create a file with a challenge and the expected 68response (that can only be generated with the secret 69key footnote:[This is also the reason why you should avoid having copies of the key in other places than your YubiKey!] ) 70in your home directory. The PAM module will later open this file, read the 71challenge, send it to the connected YubiKey and check whether its 72answer matches the one on file. If it does, it generates a new 73challenge, asks the YubiKey for the correct response for this 74challenge and writes both into the file. This also means that you need 75to keep this file secure from other users (which is why we created the 76.yubico directory in your home with mode 0700). 77 78=== Configuring your system to use Yubico PAM for authentication === 79 80Linux, Solaris, OS X and most BSD variants use the 81http://en.wikipedia.org/wiki/Pluggable_Authentication_Modules[Pluggable 82Authentication Modules] (PAM) framework to handle authentication. 83Using PAM you can specify which 84modules are used for authentication of users and which of them are 85required, optional and/or sufficient to authenticate a user. Using PAM 86you can for example set up multiple-factor authentication, by chaining 87multiple required modules. 88 89PAM is configured through files in `/etc/pam.d` on most systems. Each 90file in this directory is used for a specific service, i.e. the file 91`/etc/pam.d/sudo` is used to authenticate users for the `sudo` 92program. Debian, for example, uses include directives in these files 93to have a central place to configure authentication; in this case we 94are not using this on purpose, because challenge-response 95authentication doesn't work remotely (e.g. via SSH), so we only want 96to configure it for services we use when on site. 97 98The file format in these files is documented in `man 5 pam.conf`; it 99looks like this: 100 101 function-class control-flag module-path arguments 102 103where 104 105[horizontal] 106*function-class*:: is one of `auth`, `account`, `session`, and 107 `password`. Since we only care about authentication with the YubiKey 108 and yubico-pam only handles authentication, we will always be using 109 `auth` here. 110 111*control-flag*:: is one of `required`, `sufficient`, `optional` and 112 some other values depending on your PAM implementation. If we want 113 to make YubiKey challenge-response mandatory but combined with other 114 methods (e.g. password), we can use `required`, if we want 115 successful challenge-response to be enough to authenticate a user, 116 we can use `sufficient`. `optional` is not of any use for us 117 in this case. 118 119*module-path*:: selects the module to be used for this authentication 120 step. This is used as filename in a directory where pam libraries 121 are expected, on OS X e.g. `/usr/lib/pam`, `/usr/lib/security` on 122 some other systems. We want `pam_yubico.so` in this case, which will 123 load `/usr/lib/pam/pam_yubico.so`. 124 125*arguments*:: are passed to the pam module and can be used to 126 configure its behavior. See 'Supported PAM module parameters' in 127 https://github.com/Yubico/yubico-pam/blob/master/README[README] 128 for a list of possible values. Since we want to use 129 challenge-response, we add `mode=challenge-response` and to debug 130 the setup initially also `debug`, separated by spaces. `debug` can 131 safely be removed later. 132 133 134WARNING: If you misconfigure your PAM modules here you might lose 135 your ability to sudo! Always keep a root shell open to be able to 136 revert your changes in case something goes wrong! 137 138So, if we wanted to use the YubiKey to allow us to sudo without typing 139a password, we would add 140 141---- 142auth sufficient pam_yubico.so mode=challenge-response debug 143---- 144 145To get this working on the loginwindow for local interactive login add 146the `pam_yubico.so` to the `pam.d` file authorization as the first 147line. The whole file might look something like this (example taken 148from OS X): 149 150---- 151# sudo: auth account password session 152auth sufficient pam_yubico.so mode=challenge-response debug 153auth required pam_opendirectory.so 154account required pam_permit.so 155password required pam_deny.so 156session required pam_permit.so 157---- 158 159If we wanted to require successful challenge-response authentication 160in addition to the usual password, we can change the `sufficient` in 161the line we added to `required`. 162 163NOTE: In theory you can configure pretty much any service you use 164 locally to use challenge-response authentication. In practice, I had 165 problems configuring challenge-response into the login window of OS 166 X. Keep a rescue disk or a remote root terminal available when 167 attempting such configurations, just in case something goes wrong 168 and you need to restore the PAM configuration to an old state. 169 170NOTE: On Debian it started working for me after accidentally 171 getting the file-rights correctly. `755` for `~/.yubico` & `600` for 172 the files therein. Otherwise the module can't find, read and/or 173 write to the appropriate files. Your clue is the following debug 174 messages. 175 176---- 177[drop_privs.c:restore_privileges(128)] pam_modutil_drop_priv: -1 178[pam_yubico.c:do_challenge_response(542)] could not restore privileges 179[pam_yubico.c:do_challenge_response(664)] Challenge response failed: No such file or directory 180---- 181