rooty/yubico-pam
1
0
Fork 0
mirror of https://github.com/Yubico/yubico-pam.git synced 2025-02-26 21:54:15 +01:00
Code Issues Projects Releases Wiki Activity

Update MacOS_X_Challenge-Response.adoc

Browse Source
This commit is contained in:
Henrik Stråth 2014-10-31 14:37:35 +01:00
parent e2f9a7b95c
commit 499412c6e8
1 changed files with 48 additions and 50 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

98
doc/MacOS_X_Challenge-Response.adoc
View File

@ -1,51 +1,50 @@
Setting up your YubiKey for challenge response authentication on Max OS X == Setting up your YubiKey for challenge response authentication on Max OS X ==
-------------------------------------------------------------------------
This article explains the process to get the challenge-response This article explains the process to get the challenge-response
authentication possible with newer YubiKeys working on Mac OS X. Since authentication possible with newer YubiKeys working on Mac OS X. Since
Mac OS X uses PAM like most other Unix/POSIX systems do, most of this Mac OS X uses PAM like most other Unix/POSIX systems do, most of this
should apply to other operating systems, too. should apply to other operating systems, too.
Getting yubico-pam === Getting yubico-pam ===
------------------
First you will have to install yubico-pam and its dependencies First you will have to install yubico-pam and its dependencies
required for challenge-response authentication. Use your required for challenge-response authentication. Use your
distribution's package manager to get it, or build from source. If distribution's package manager to get it, or build from source. If
you're on OS X you can use [MacPorts](http://www.macports.org/) to you're on OS X you can use http://www.macports.org[MacPorts] to
install yubico-pam: install yubico-pam:
sudo port install yubico-pam sudo port install yubico-pam
**Note**: This will probably not work in non-superuser installations NOTE: This will probably not work in non-superuser installations
of MacPorts, because it needs to place the yubico PAM module into of MacPorts, because it needs to place the yubico PAM module into
`/usr/lib/pam`. `/usr/lib/pam`.
Configuring your YubiKey === Configuring your YubiKey ===
------------------------
The next step would be to set up your YubiKey for challenge-response The next step would be to set up your YubiKey for challenge-response
authentication, if you haven't done so already. Although this is authentication, if you haven't done so already. Although this is
possible with the command line `ykpersonalize` tool, the GUI "YubiKey possible with the command line `ykpersonalize` tool, the GUI "YubiKey
Personalization Tool" is a more comfortable way to do this. Personalization Tool" is a more comfortable way to do this.
1. Plug in your YubiKey and start the YubiKey Personalization Tool 1. Plug in your YubiKey and start the YubiKey Personalization Tool
**Note**: YubiKey Personalization Tool shows whether your YubiKey supports challenge-response in the lower right. +
NOTE: YubiKey Personalization Tool shows whether your YubiKey supports challenge-response in the lower right.
2. Click Challenge-Response 2. Click Challenge-Response
3. Select HMAC-SHA1 mode 3. Select HMAC-SHA1 mode
Apparently Yubico-OTP mode doesn't work with yubico-pam at the moment. Apparently Yubico-OTP mode doesn't work with yubico-pam at the moment.
4. Select the configuration slot you want to use 4. Select the configuration slot you want to use
(this text assumes slot two, but it should be easy enough to adapt the instructions if you prefer slot 1) (this text assumes slot two, but it should be easy enough to adapt the instructions if you prefer slot 1)
5. Select whether you want to require pressing the button for authentication 5. Select whether you want to require pressing the button for authentication
**Note**: 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. +
NOTE: 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.
6. Use "Variable input" as HMAC-SHA1 mode 6. Use "Variable input" as HMAC-SHA1 mode
**Warning**: 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! +
WARNING: 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!
7. Generate a secret key 7. Generate a secret key
You 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. You 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.
8. Click "Write Configuration" 8. Click "Write Configuration"
Configuring your user account to accept the YubiKey === Configuring your user account to accept the YubiKey ===
---------------------------------------------------
After setting up your YubiKey you need to configure your account to After setting up your YubiKey you need to configure your account to
accept this YubiKey for authentication. To do this, open a terminal accept this YubiKey for authentication. To do this, open a terminal
@ -62,13 +61,16 @@ blinking; press the button to send a challenge-response
response. `ykpamcfg` should finish successfully telling you that it response. `ykpamcfg` should finish successfully telling you that it
stored the initial challenge somewhere inside your home directory: stored the initial challenge somewhere inside your home directory:
--- ----
> Stored initial challenge and expected response in '/path/to/your/home/.yubico/challenge-KEYID'. Stored initial challenge and expected response in '/path/to/your/home/.yubico/challenge-KEYID'.
--- ----
A footnote footnote:[An example footnote.]
This step will create a file with a challenge and the expected This step will create a file with a challenge and the expected
response (that can only be generated with the secret key[1]) in your response (that can only be generated with the secret
home directory. The PAM module will later open this file, read the key footnote:[This is also the reason why you should avoid having copies of the key in other places than your YubiKey!] )
in your home directory. The PAM module will later open this file, read the
challenge, send it to the connected YubiKey and check whether its challenge, send it to the connected YubiKey and check whether its
answer matches the one on file. If it does, it generates a new answer matches the one on file. If it does, it generates a new
challenge, asks the YubiKey for the correct response for this challenge, asks the YubiKey for the correct response for this
@ -76,16 +78,12 @@ challenge and writes both into the file. This also means that you need
to keep this file secure from other users (which is why we created the to keep this file secure from other users (which is why we created the
.yubico directory in your home with mode 0700). .yubico directory in your home with mode 0700).
[1]: This is also the reason why you should avoid having copies of the === Configuring your system to use Yubico PAM for authentication ===
key in other places than your YubiKey!
Configuring your system to use Yubico PAM for authentication Linux, Solaris, OS X and most BSD variants use the
------------------------------------------------------------ http://en.wikipedia.org/wiki/Pluggable_Authentication_Modules[Pluggable
Authentication Modules] (PAM) framework to handle authentication.
Linux, Solaris, OS X and most BSD variants use the [Pluggable Using PAM you can specify which
Authentication Modules
(PAM)](http://en.wikipedia.org/wiki/Pluggable_Authentication_Modules)
framework to handle authentication. Using PAM you can specify which
modules are used for authentication of users and which of them are modules are used for authentication of users and which of them are
required, optional and/or sufficient to authenticate a user. Using PAM required, optional and/or sufficient to authenticate a user. Using PAM
you can for example set up multiple-factor authentication, by chaining you can for example set up multiple-factor authentication, by chaining
@ -101,7 +99,7 @@ authentication doesn't work remotely (e.g. via SSH), so we only want
to configure it for services we use when on site. to configure it for services we use when on site.
The file format in these files is documented in `man 5 pam.conf`; it The file format in these files is documented in `man 5 pam.conf`; it
basically looks like this: looks like this:
function-class control-flag module-path arguments function-class control-flag module-path arguments
@ -117,7 +115,7 @@ where
to make YubiKey challenge-response mandatory but combined with other to make YubiKey challenge-response mandatory but combined with other
methods (e.g. password), we can use `required`, if we want methods (e.g. password), we can use `required`, if we want
successful challenge-response to be enough to authenticate a user, successful challenge-response to be enough to authenticate a user,
we can use `sufficient`. `optional` is not really of any use for us we can use `sufficient`. `optional` is not of any use for us
in this case. in this case.
* `module-path` selects the module to be used for this authentication * `module-path` selects the module to be used for this authentication
@ -127,57 +125,57 @@ where
load `/usr/lib/pam/pam_yubico.so`. load `/usr/lib/pam/pam_yubico.so`.
* `arguments` are passed to the pam module and can be used to * `arguments` are passed to the pam module and can be used to
configure its behavior. See "Supported PAM module parameters" in configure its behavior. See 'Supported PAM module parameters' in
[README](https://github.com/Yubico/yubico-pam/blob/master/README) [README](https://github.com/Yubico/yubico-pam/blob/master/README)
for a list of possible values. Since we want to use for a list of possible values. Since we want to use
challenge-response, we add `mode=challenge-response` and to debug challenge-response, we add `mode=challenge-response` and to debug
the setup initially also `debug`, separated by spaces. `debug` can the setup initially also `debug`, separated by spaces. `debug` can
safely be removed later. safely be removed later.
**Warning**: If you misconfigure your PAM modules here you might lose WARNING: If you misconfigure your PAM modules here you might lose
your ability to sudo! Always keep a root shell open to be able to your ability to sudo! Always keep a root shell open to be able to
revert your changes in case something goes wrong! revert your changes in case something goes wrong!
So, if we wanted to use the YubiKey to allow us to sudo without typing So, if we wanted to use the YubiKey to allow us to sudo without typing
a password, we would add a password, we would add
--- ----
auth sufficient pam_yubico.so mode=challenge-response debug auth sufficient pam_yubico.so mode=challenge-response debug
--- ----
To get this working on the loginwindow for local interactive login add To get this working on the loginwindow for local interactive login add
the pam_yubico.so to the pam.d file authorization as the first the pam_yubico.so to the pam.d file authorization as the first
line. The whole file might look something like this (example taken line. The whole file might look something like this (example taken
from OS X): from OS X):
--- ----
# sudo: auth account password session # sudo: auth account password session
auth sufficient pam_yubico.so mode=challenge-response debug auth sufficient pam_yubico.so mode=challenge-response debug
auth required pam_opendirectory.so auth required pam_opendirectory.so
account required pam_permit.so account required pam_permit.so
password required pam_deny.so password required pam_deny.so
session required pam_permit.so session required pam_permit.so
--- ----
If we wanted to require successful challenge-response authentication If we wanted to require successful challenge-response authentication
in addition to the usual password, we can change the `sufficient` in in addition to the usual password, we can change the `sufficient` in
the line we added to `required`. the line we added to `required`.
**Note**: In theory you can configure pretty much any service you use NOTE: In theory you can configure pretty much any service you use
locally to use challenge-response authentication. In practice, I had locally to use challenge-response authentication. In practice, I had
problems configuring challenge-response into the login window of OS problems configuring challenge-response into the login window of OS
X. Keep a rescue disk or a remote root terminal available when X. Keep a rescue disk or a remote root terminal available when
attempting such configurations, just in case something goes wrong attempting such configurations, just in case something goes wrong
and you need to restore the PAM configuration to an old state. and you need to restore the PAM configuration to an old state.
**Note #2**: On Debian it started working for me after accidentally NOTE: On Debian it started working for me after accidentally
getting the file-rights correctly. `755` for `~/.yubico` & `600` for getting the file-rights correctly. `755` for `~/.yubico` & `600` for
the files therein. Otherwise the module can't find, read and/or the files therein. Otherwise the module can't find, read and/or
write to the appropriate files. Your clue is the following debug write to the appropriate files. Your clue is the following debug
messages. messages.
--- ----
[drop_privs.c:restore_privileges(128)] pam_modutil_drop_priv: -1 [drop_privs.c:restore_privileges(128)] pam_modutil_drop_priv: -1
[pam_yubico.c:do_challenge_response(542)] could not restore privileges [pam_yubico.c:do_challenge_response(542)] could not restore privileges
[pam_yubico.c:do_challenge_response(664)] Challenge response failed: No such file or directory [pam_yubico.c:do_challenge_response(664)] Challenge response failed: No such file or directory
--- ----