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

Add docs from the wiki.

Browse Source
This commit is contained in:
Simon Josefsson 2014-04-30 11:03:40 +02:00
parent 35e84d867b
commit 76b241ff04
10 changed files with 1689 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

193
doc/LocalAuthenticationUsingChallengeResponse.txt Normal file
View File

@ -0,0 +1,193 @@
Local Authentication Using Challenge Response
---------------------------------------------
The PAM module can utilize the HMAC-SHA1 Challenge-Response mode found
in YubiKeys starting with version 2.2 for offline authentication.
This mode is useful if you don't have a stable network connection to
the YubiCloud.
The ykpamcfg utility currently outputs the state information to a file
in the current user's home directory ("$HOME/.yubico/challenge-123456"
for a YubiKey with serial number API readout enabled, and
"$HOME/.yubico/challenge" for one without).
The PAM module supports a system wide directory for these state files
(in case the user's home directories are encrypted), but in a system
wide directory, the 'challenge' part should be replaced with the
username. Example: /var/yubico/challenges/alice-123456.
To use the system-wide mode, you currently have to move the generated
state files manually and configure the PAM module accordingly.
The following process is tested on Ubuntu 12.04.
First install the package:
------
$ sudo apt-get install libpam-yubico
------
You will get a question about the PAM configuration line. Enter this
line:
------
mode=challenge-response
------
The next question will be about which PAM modules to enable. Don't
enable anything just yet, because you need to program your YubiKey
first.
If you have already installed the package or want to reconfigure it,
you may use this command:
------
$ sudo dpkg-reconfigure libpam-yubico
------
The next step is to add a challenge-response slot to your YubiKey. If
you have a normal YubiKey with OTP functionality on the first slot,
you could add Challenge-Response on the second slot. You could have
CR on the first slot, if you want.
First, program a YubiKey for challenge response on Slot 2:
------
$ ykpersonalize -2 -ochal-resp -ochal-hmac -ohmac-lt64 -oserial-api-visible
...
Commit? (y/n) [n]: y
$
------
Now, set the current user to require this YubiKey for logon:
------
$ mkdir $HOME/.yubico
$ ykpamcfg -2 -v
...
Stored initial challenge and expected response in '/home/alice/.yubico/challenge-123456'.
$
------
If your /home/user folder is encrypted you should move the challenge file in a different path (i.e. /etc/yubico) and then set the right permission for the user to create the files. To do this do as follow:
------
$ mkdir /etc/yubico
$ chmod +t /etc/yubico
$ chmod 777 /etc/yubico
$ mv /home/user/.yubico/challenge-####### /etc/yubico/username-#######
...
It is important that you name the file with the username of the user that is going to use the Yubikey
------
Finally we tell the pam module where to look for the challenge file
------
$ emacs /etc/pam.d/common-auth
...
and edit the following line as follow:
auth required pam_yubico.so mode=challenge-response chalresp_path=/etc/yubico
------
Then back to the PAM configuration step, first make sure you have a
root terminal available to be able to disable YubiKey login in case of
issues.
------
$ sudo -s
------
Then run the "pam-auth-update" command and enable the Yubico PAM
module.
------
$ sudo pam-auth-update
------
You should now be able to authenticate using YubiKey
Challenge-Reseponse together with a password like this:
-----
jas@latte:~$ sudo -s
[sudo] password for jas:
root@latte:~#
-----
Now remove the YubiKey and try again (in a new terminal to avoid sudo
caching), and you should not be able to login.
For debugging, you can make the PAM configuration line:
-----
mode=challenge-response debug
-----
and then create a log file:
------
# touch /var/run/pam-debug.log
# chmod go+w /var/run/pam-debug.log
------
and then tail the file. For successful logins it should print
something like this:
------
[pam_yubico.c:parse_cfg(721)] called.
[pam_yubico.c:parse_cfg(722)] flags 32768 argc 2
[pam_yubico.c:parse_cfg(724)] argv[0]=mode=challenge-response
[pam_yubico.c:parse_cfg(724)] argv[1]=debug
[pam_yubico.c:parse_cfg(725)] id=-1
[pam_yubico.c:parse_cfg(726)] key=(null)
[pam_yubico.c:parse_cfg(727)] debug=1
[pam_yubico.c:parse_cfg(728)] alwaysok=0
[pam_yubico.c:parse_cfg(729)] verbose_otp=0
[pam_yubico.c:parse_cfg(730)] try_first_pass=0
[pam_yubico.c:parse_cfg(731)] use_first_pass=0
[pam_yubico.c:parse_cfg(732)] authfile=(null)
[pam_yubico.c:parse_cfg(733)] ldapserver=(null)
[pam_yubico.c:parse_cfg(734)] ldap_uri=(null)
[pam_yubico.c:parse_cfg(735)] ldapdn=(null)
[pam_yubico.c:parse_cfg(736)] user_attr=(null)
[pam_yubico.c:parse_cfg(737)] yubi_attr=(null)
[pam_yubico.c:parse_cfg(738)] yubi_attr_prefix=(null)
[pam_yubico.c:parse_cfg(739)] url=(null)
[pam_yubico.c:parse_cfg(740)] capath=(null)
[pam_yubico.c:parse_cfg(741)] token_id_length=12
[pam_yubico.c:parse_cfg(742)] mode=chresp
[pam_yubico.c:parse_cfg(743)] chalresp_path=(null)
[pam_yubico.c:pam_sm_authenticate(775)] get user returned: jas
[pam_yubico.c:do_challenge_response(493)] Loading challenge from file /home/jas/.yubico/challenge-1077187
[util.c:load_chalresp_state(269)] Challenge: 23001a190724abf46c8022b008ccb65673dd634ecb150613771ec87f37850284d80dd5f8c8e56affb6da2e952b16682160e7f3ac4f816b64126bd9556e5be1, response: 63d4a679ed15335ffd4253e7609963bcdb0834d4, slot: 2
[pam_yubico.c:do_challenge_response(566)] Got the expected response, generating new challenge (63 bytes).
[pam_yubico.c:do_challenge_response(629)] Challenge-response success!
------
and if there is no YubiKey in the machine it will look like this:
------
[pam_yubico.c:parse_cfg(721)] called.
[pam_yubico.c:parse_cfg(722)] flags 32768 argc 2
[pam_yubico.c:parse_cfg(724)] argv[0]=mode=challenge-response
[pam_yubico.c:parse_cfg(724)] argv[1]=debug
[pam_yubico.c:parse_cfg(725)] id=-1
[pam_yubico.c:parse_cfg(726)] key=(null)
[pam_yubico.c:parse_cfg(727)] debug=1
[pam_yubico.c:parse_cfg(728)] alwaysok=0
[pam_yubico.c:parse_cfg(729)] verbose_otp=0
[pam_yubico.c:parse_cfg(730)] try_first_pass=0
[pam_yubico.c:parse_cfg(731)] use_first_pass=0
[pam_yubico.c:parse_cfg(732)] authfile=(null)
[pam_yubico.c:parse_cfg(733)] ldapserver=(null)
[pam_yubico.c:parse_cfg(734)] ldap_uri=(null)
[pam_yubico.c:parse_cfg(735)] ldapdn=(null)
[pam_yubico.c:parse_cfg(736)] user_attr=(null)
[pam_yubico.c:parse_cfg(737)] yubi_attr=(null)
[pam_yubico.c:parse_cfg(738)] yubi_attr_prefix=(null)
[pam_yubico.c:parse_cfg(739)] url=(null)
[pam_yubico.c:parse_cfg(740)] capath=(null)
[pam_yubico.c:parse_cfg(741)] token_id_length=12
[pam_yubico.c:parse_cfg(742)] mode=chresp
[pam_yubico.c:parse_cfg(743)] chalresp_path=(null)
[pam_yubico.c:pam_sm_authenticate(775)] get user returned: jas
[pam_yubico.c:do_challenge_response(478)] Failed initializing YubiKey
[pam_yubico.c:do_challenge_response(640)] Yubikey core error: no yubikey present
------

87
doc/MacOSXChallengeResponse.txt Normal file
View File

@ -0,0 +1,87 @@
# Setting up your YubiKey for challenge response authentication (on Max OS X)
This article explains the process to get the challenge-response 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 should apply to other operating systems, too.
### Getting yubico-pam
First you will have to install yubico-pam and its dependencies required for challenge-response authentication. Use your 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 install yubico-pam:
sudo port install yubico-pam
**Note**: This will probably not work in non-superuser installations of MacPorts, because it needs to place the yubico PAM module into `/usr/lib/pam`.
### Configuring your YubiKey
The next step would be to set up your YubiKey for challenge-response authentication, if you haven't done so already. Although this is possible with the command line `ykpersonalize` tool, the GUI "YubiKey Personalization Tool" is a more comfortable way to do this.
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.
2. Click Challenge-Response
3. Select HMAC-SHA1 mode
Apparently Yubico-OTP mode doesn't work with yubico-pam at the moment.
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)
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.
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!
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.
8. Click "Write Configuration"
### Configuring your user account to accept the YubiKey
After setting up your YubiKey you need to configure your account to accept this YubiKey for authentication. To do this, open a terminal and run
# create the directory where ykpamcfg will store the initial challenge
mkdir -m0700 -p ~/.yubico
# get the initial challenge from the YubiKey
ykpamcfg -2
If you used slot 1 above, replace -2 with -1. If you configured your YubiKey to require a button press the LED on the YubiKey will start blinking; press the button to send a challenge-response response. `ykpamcfg` should finish successfully telling you that it stored the initial challenge somewhere inside your home directory:
> Stored initial challenge and expected response in '/path/to/your/home/.yubico/challenge-KEYID'.
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 home directory. The PAM module will later open this file, read the challenge, send it to the connected YubiKey and check whether its answer matches the one on file. If it does, it generates a new challenge, asks the YubiKey for the correct response for this 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 .yubico directory in your home with mode 0700).
[1]: This is also the reason why you should avoid having copies of the 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 [Pluggable 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 required, optional and/or sufficient to authenticate a user. Using PAM you can for example set up multiple-factor authentication, by chaining multiple required modules.
PAM is configured through files in `/etc/pam.d` on most systems. Each file in this directory is used for a specific service, i.e. the file `/etc/pam.d/sudo` is used to authenticate users for the `sudo` program. Debian, for example, uses include directives in these files to have a central place to configure authentication; in this case we are not using this on purpose, because challenge-response authentication doesn't work remotely (e.g. via SSH), so we only want to configure it for services we use when on site.
The file format in these files is documented in `man 5 pam.conf`; it basically looks like this:
function-class control-flag module-path arguments
where
* `function-class` is one of `auth`, `account`, `session`, and `password`. Since we only care about authentication with the YubiKey and yubico-pam only handles authentication, we will always be using `auth` here.
* `control-flag` is one of `required`, `sufficient`, `optional` and some other values depending on your PAM implementation. If we want to make YubiKey challenge-response mandatory but combined with other methods (e.g. password), we can use `required`, if we want successful challenge-response to be enough to authenticate a user, we can use `sufficient`. `optional` is not really of any use for us in this case.
* `module-path` selects the module to be used for this authentication step. This is used as filename in a directory where pam libraries are expected, on OS X e.g. `/usr/lib/pam`, `/usr/lib/security` on some other systems. We want `pam_yubico.so` in this case, which will load `/usr/lib/pam/pam_yubico.so`.
* `arguments` are passed to the pam module and can be used to configure its behavior. See "Supported PAM module parameters" in [README](https://github.com/Yubico/yubico-pam/blob/master/README) for a list of possible values. Since we want to use challenge-response, we add `mode=challenge-response` and to debug the setup initially also `debug`, separated by spaces. `debug` can safely be removed later.
**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 revert your changes in case something goes wrong!
So, if we wanted to use the YubiKey to allow us to sudo without typing a password, we would add
auth sufficient pam_yubico.so mode=challenge-response debug
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 line. The whole file might look something like this (example taken from OS X):
# sudo: auth account password session
auth sufficient pam_yubico.so mode=challenge-response debug
auth required pam_opendirectory.so
account required pam_permit.so
password required pam_deny.so
session required pam_permit.so
If we wanted to require successful challenge-response authentication in addition to the usual password, we can change the `sufficient` in the line we added to `required`.
**Note**: In theory you can configure pretty much any service you use locally to use challenge-response authentication. In practice, I had problems configuring challenge-response into the login window of OS X. Keep a rescue disk or a remote root terminal available when attempting such configurations, just in case something goes wrong and you need to restore the PAM configuration to an old state.
**Note #2**: On Debian it started working for me after accidentally getting the file-rights correctly. `755` for `~/.yubico` & `600` for the files therein. Otherwise the module can't find, read and/or write to the appropriate files. Your clue is the following debug messages.
[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(664)] Challenge response failed: No such file or directory

33
doc/TwoFactorPAMConfiguration.txt Normal file
View File

@ -0,0 +1,33 @@
PAM configuration is somewhat complex, but a typical use-case is to
require both a password and Yubikey to allow access. This can be
achieved by a PAM configuration like this:
```
auth requisite pam_yubico.so id=42
auth required pam_unix.so use_first_pass
```
The first line makes pam_yubico check the OTP. Use either a per-user
file called ~/.yubico/authorized_yubikeys, or a system wide file called
/etc/yubikey_mappings to specify which Yubikeys that can be used to log
in as specific users. See the https://github.com/Yubico/yubico-pam/wiki/ReadMe for more details about this.
The "use_first_pass" on the next line says that the password the pam_unix
module should check should be received from the earlier PAM modules
and that the module should not query for passwords.
Of course, if you use username/password verification from a SQL
database or LDAP, you need to change the second line above. But the
module you use needs to support "use_first_pass" for this to work.
Most modules support this.
Be sure to comment out any other 'auth' lines in your PAM configuration,
unless you want those. For example, Debian contains a
'@include common-auth' which would confuse the configuration.
To log in, you now need to enter both your Unix password and enter an
OTP using your Yubikey. When prompted for the password, enter the Unix
password first and then (without pressing enter) push the button on your
Yubikey.
If it doesn't work, enable debugging (see https://github.com/Yubico/yubico-pam/wiki/ReadMe) and try again.

278
doc/UbuntuFreeRadiusYubiKey.txt Normal file
View File

@ -0,0 +1,278 @@
Ubuntu FreeRadius YubiKey
-------------------------
Create and login to a fresh Ubuntu 10.04 LTS machine:
------
vmbuilder kvm ubuntu \
--dest /var/lib/libvirt/images/freeradius \
--proxy http://192.168.1.2/ubuntu \
--rootsize 10000 \
--mem 600 \
--suite lucid \
--flavour virtual \
--addpkg unattended-upgrades \
--addpkg openssh-server \
--addpkg avahi-daemon \
--addpkg acpid \
--ssh-key /root/.ssh/authorized_keys \
--libvirt qemu:///system \
--hostname freeradius \
--bridge br0 \
--debug
ssh -l root freeradius.local
------
Install and configure software :
--------------------------------
------
apt-get install build-essential wget
apt-get install libpam0g-dev libykclient3 libykclient-dev
------
Install PAM module:
------
wget http://yubico-pam.googlecode.com/files/pam_yubico-2.4.tar.gz
tar xfz pam_yubico-2.4.tar.gz
cd pam_yubico-2.4
./configure
make check install
ln -s /usr/local/lib/security/pam_yubico.so /lib/security/
------
Setup PAM debug log file:
------
touch /var/run/pam-debug.log
chmod go+w /var/run/pam-debug.log
tail -F /var/run/pam-debug.log &
------
Install FreeRadius:
------
apt-get install freeradius
/etc/init.d/freeradius stop
------
Next we configure FreeRadius. First add this to /etc/freeradius/users:
------
DEFAULT Auth-Type = pam
------
Then comment out 'pap' and uncomment 'pam' from
/etc/freeradius/sites-available/default.
Add to the top of /etc/pam.d/radiusd:
------
auth sufficient pam_yubico.so id=1 debug authfile=/etc/yubikey_mapping
------
If you want to use HMAC signing, specify the 'key=' field too, like this:
------
auth sufficient pam_yubico.so id=1 key=b64foo debug authfile=/etc/yubikey_mapping
------
Create a file /etc/yubikey_mapping (ccccccccltnc is Alice's YubiKey's public ID) :
------
alice:ccccccccltnc
------
Create a Unix account 'alice': XXX should not be necessary??
------
adduser --disabled-password alice
------
Just press RET and finally 'y RET' on the prompts.
Start radiusd:
------
LD_PRELOAD=/lib/libpam.so.0 freeradius -X
------
Testing authentication :
------------------------
Confirm that it works with radtest (use a real OTP from Alice's YubiKey) :
------
radtest alice ccccccccltncdjjifceergtnukivgiujhgehgnkrfcef 127.0.0.1 0 testing123
------
Output should be like this:
------
Sending Access-Request of id 69 to 127.0.0.1 port 1812
User-Name = "alice"
User-Password = "ccccccccltncdjjifceergtnukivgiujhgehgnkrfcef"
NAS-IP-Address = 127.0.1.1
NAS-Port = 0
rad_recv: Access-Accept packet from host 127.0.0.1 port 1812, id=69, length=20
------
PAM debug output should be like this:
------
[pam_yubico.c:parse_cfg(404)] called.
[pam_yubico.c:parse_cfg(405)] flags 0 argc 3
[pam_yubico.c:parse_cfg(407)] argv[0]=id=1
[pam_yubico.c:parse_cfg(407)] argv[1]=debug
[pam_yubico.c:parse_cfg(407)] argv[2]=authfile=/etc/yubikey_mapping
[pam_yubico.c:parse_cfg(408)] id=1
[pam_yubico.c:parse_cfg(409)] key=(null)
[pam_yubico.c:parse_cfg(410)] debug=1
[pam_yubico.c:parse_cfg(411)] alwaysok=0
[pam_yubico.c:parse_cfg(412)] verbose_otp=0
[pam_yubico.c:parse_cfg(413)] try_first_pass=0
[pam_yubico.c:parse_cfg(414)] use_first_pass=0
[pam_yubico.c:parse_cfg(415)] authfile=/etc/yubikey_mapping
[pam_yubico.c:parse_cfg(416)] ldapserver=(null)
[pam_yubico.c:parse_cfg(417)] ldap_uri=(null)
[pam_yubico.c:parse_cfg(418)] ldapdn=(null)
[pam_yubico.c:parse_cfg(419)] user_attr=(null)
[pam_yubico.c:parse_cfg(420)] yubi_attr=(null)
[pam_yubico.c:pam_sm_authenticate(452)] get user returned: alice
[pam_yubico.c:pam_sm_authenticate(542)] conv returned: ccccccccltncdjjifceergtnukivgiujhgehgnkrfcef
[pam_yubico.c:pam_sm_authenticate(558)] OTP: ccccccccltncdjjifceergtnukivgiujhgehgnkrfcef ID: ccccccccltnc
[pam_yubico.c:pam_sm_authenticate(583)] ykclient return value (0): Success
[pam_yubico.c:check_user_token(117)] Authorization line: alice:ccccccccltnc
[pam_yubico.c:check_user_token(121)] Matched user: alice
[pam_yubico.c:check_user_token(125)] Authorization token: ccccccccltnc
[pam_yubico.c:check_user_token(128)] Match user/token as alice/ccccccccltnc
[pam_yubico.c:pam_sm_authenticate(625)] done. [Success]
------
FreeRadius debug output should be like this:
------
rad_recv: Access-Request packet from host 127.0.0.1 port 38575, id=69, length=89
User-Name = "alice"
User-Password = "ccccccccltncdjjifceergtnukivgiujhgehgnkrfcef"
NAS-IP-Address = 127.0.1.1
NAS-Port = 0
+- entering group authorize {...}
++[preprocess] returns ok
++[chap] returns noop
++[mschap] returns noop
[suffix] No '@' in User-Name = "alice", looking up realm NULL
[suffix] No such realm "NULL"
++[suffix] returns noop
[eap] No EAP-Message, not doing EAP
++[eap] returns noop
[files] users: Matched entry DEFAULT at line 204
++[files] returns ok
++[expiration] returns noop
++[logintime] returns noop
Found Auth-Type = PAM
+- entering group authenticate {...}
pam_pass: using pamauth string <radiusd> for pam.conf lookup
pam_pass: authentication succeeded for <alice>
++[pam] returns ok
+- entering group post-auth {...}
++[exec] returns noop
Sending Access-Accept of id 69 to 127.0.0.1 port 38575
Finished request 0.
Going to the next request
Waking up in 4.9 seconds.
Cleaning up request 0 ID 69 with timestamp +17
Ready to process requests.
------
Testing a OTP replay :
----------------------
Run the command again, with the _same_ OTP :
------
radtest alice ccccccccltncdjjifceergtnukivgiujhgehgnkrfcef 127.0.0.1 0 testing123
------
Then output should be like this, since the OTP was replayed:
------
Sending Access-Request of id 32 to 127.0.0.1 port 1812
User-Name = "alice"
User-Password = "ccccccccltncdjjifceergtnukivgiujhgehgnkrfcef"
NAS-IP-Address = 127.0.1.1
NAS-Port = 0
rad_recv: Access-Reject packet from host 127.0.0.1 port 1812, id=32, length=20
------
PAM debug log:
------
[pam_yubico.c:parse_cfg(404)] called.
[pam_yubico.c:parse_cfg(405)] flags 0 argc 3
[pam_yubico.c:parse_cfg(407)] argv[0]=id=1
[pam_yubico.c:parse_cfg(407)] argv[1]=debug
[pam_yubico.c:parse_cfg(407)] argv[2]=authfile=/etc/yubikey_mapping
[pam_yubico.c:parse_cfg(408)] id=1
[pam_yubico.c:parse_cfg(409)] key=(null)
[pam_yubico.c:parse_cfg(410)] debug=1
[pam_yubico.c:parse_cfg(411)] alwaysok=0
[pam_yubico.c:parse_cfg(412)] verbose_otp=0
[pam_yubico.c:parse_cfg(413)] try_first_pass=0
[pam_yubico.c:parse_cfg(414)] use_first_pass=0
[pam_yubico.c:parse_cfg(415)] authfile=/etc/yubikey_mapping
[pam_yubico.c:parse_cfg(416)] ldapserver=(null)
[pam_yubico.c:parse_cfg(417)] ldap_uri=(null)
[pam_yubico.c:parse_cfg(418)] ldapdn=(null)
[pam_yubico.c:parse_cfg(419)] user_attr=(null)
[pam_yubico.c:parse_cfg(420)] yubi_attr=(null)
[pam_yubico.c:pam_sm_authenticate(452)] get user returned: alice
[pam_yubico.c:pam_sm_authenticate(542)] conv returned: ccccccccltncdjjifceergtnukivgiujhgehgnkrfcef
[pam_yubico.c:pam_sm_authenticate(558)] OTP: ccccccccltncdjjifceergtnukivgiujhgehgnkrfcef ID: ccccccccltnc
[pam_yubico.c:pam_sm_authenticate(583)] ykclient return value (2): Yubikey OTP was replayed (REPLAYED_OTP)
[pam_yubico.c:pam_sm_authenticate(625)] done. [Authentication failure]
------
FreeRadius debug log:
------
rad_recv: Access-Request packet from host 127.0.0.1 port 55170, id=32, length=89
User-Name = "alice"
User-Password = "ccccccccltncdjjifceergtnukivgiujhgehgnkrfcef"
NAS-IP-Address = 127.0.1.1
NAS-Port = 0
+- entering group authorize {...}
++[preprocess] returns ok
++[chap] returns noop
++[mschap] returns noop
[suffix] No '@' in User-Name = "alice", looking up realm NULL
[suffix] No such realm "NULL"
++[suffix] returns noop
[eap] No EAP-Message, not doing EAP
++[eap] returns noop
[files] users: Matched entry DEFAULT at line 204
++[files] returns ok
++[expiration] returns noop
++[logintime] returns noop
Found Auth-Type = PAM
+- entering group authenticate {...}
pam_pass: using pamauth string <radiusd> for pam.conf lookup
pam_pass: function pam_authenticate FAILED for <alice>. Reason: Permission denied
++[pam] returns reject
Failed to authenticate the user.
Using Post-Auth-Type Reject
+- entering group REJECT {...}
[attr_filter.access_reject] expand: %{User-Name} -> alice
attr_filter: Matched entry DEFAULT at line 11
++[attr_filter.access_reject] returns updated
Delaying reject of request 1 for 1 seconds
Going to the next request
Waking up in 0.5 seconds.
Sending delayed reject for request 1
Sending Access-Reject of id 32 to 127.0.0.1 port 55170
Waking up in 4.9 seconds.
Cleaning up request 1 ID 32 with timestamp +66
Ready to process requests.
------

202
doc/YubiKeyAndFreeRADIUSviaPAM.txt Normal file
View File

@ -0,0 +1,202 @@
Yubico PAM Two-factor configuration guide
-----------------------------------------
Step by Step Guide for Configuration of Yubico PAM module to provide Two-factor
legacy Username + password + YubiKey OTP authentication for RADIUS server.
Introduction
------------
The purpose of this document is to guide readers through the configuration
steps to enable two factor authentication using YubiKey and RADIUS server on
Linux platform. This document assumes that the reader has advance knowledge
and experience in Linux system administration, particularly how to configure
PAM authentication mechanism on a Linux platform.
Although this configuration guide focuses on configuration of radiusd daemon for
local authentication using the custom database (we have used /etc/passwd),
radiusd can be configured easily to use centralized LDAP database for
authentication or any popular directory service by configuring appropriate PAM
modules in radiusd PAM configuration file.
Details
-------
Prerequisites
-------------
Successful configuration of the Yubico PAM module to support two factor
authentication for RADIUS requires following prerequisites:
* Operating System: Any Unix operating system which supports PAM
(Pluggable Authentication Module)
(http://www.kernel.org/pub/linux/libs/pam/)
* Complier : GNU GCC complier (http://gcc.gnu.org/)
* FreeRADIUS: FreeRADIUS Version: 1.1.7 *or later*
(http://freeradius.org/download.html)
* Yubico PAM Module: Yubico PAM Module Version 1.8
(http://opensource.yubico.com/yubico-pam/)
Configuration
-------------
We assume that FreeRADIUS is already installed on the server.
Configuration of FreeRADIUS server to support PAM authentication :
------------------------------------------------------------------
* Edit the radiusd configuration file “/etc/raddb/radiusd.conf” to make
following changes:
------
* Change user and group to “root” to provide the root privileges to
radiusd daemon so that it can call and use pam modules for authentication.
NOTE: Generally, it is not a good security practice to assign root
privileges to a user for a daemon. However, since use of PAM requires root
privileges, this is a mandatory step here.
* In “authenticate” section uncomment pam to direct radiusd daemon to use PAM
module for authentication
------
* Edit the client configuration file “/etc/raddb/clients.conf”
------
Add sample client for testing
------
* Edit the user configuration file “/etc/raddb/users” to make following change:
------
Change "DEFAULT Auth-Type = System" to "DEFAULT Auth-Type = pam" for using
PAM modules for user authentication
------
Installation of pam_yubico module :
-----------------------------------
Build instructions for pam_yubico are available in the README.
(https://github.com/Yubico/yubico-pam/wiki/ReadMe)
Configuration of pam_yubico module :
------------------------------------
Configuration instructions for pam_yubico are also available in the README.
(https://github.com/Yubico/yubico-pam/wiki/ReadMe)
_Make sure you set your system up for either central authorization mapping,
or user level mapping, as this will control which users can connect to the
system using RADIUS._
Configuration of modified pam_yubico.so module at administrative level :
------------------------------------------------------------------------
Append the following line to the beginning of /etc/pam.d/radiusd file:
------
auth required pam_yubico.so id=16 debug authfile=/etc/yubikey_mappings
------
After the above configuration changes, whenever a user connects to the
server using any RADIUS client, the PAM authentication interface will pass
the control to Yubico PAM module.
The Yubico PAM module first checks the presence of authfile argument in PAM
configuration. If authfile argument is present, it parses the corresponding
mapping file and verifies the username with corresponding YubiKey PublicID
as configured in the mapping file.
If valid, the Yubico PAM module extracts the OTP string and sends it to the
Yubico authentication server or else it reports failure. If authfile argument
is present but the mapping file is not present at the provided path PAM
module reports failure. After successful verification of OTP Yubico PAM module
from the Yubico authentication server, a success code is returned.
User Level :
------------
Although, user level configuration of pam_yubico is possible, this might not
be a desired configuration option in case of radisud daemon in most enterprise.
Configuration of selinux policy to create exception for radiusd daemon :
-----------------------------------------------------------------------
Local effective selinux policy must be updated to provide sufficient
privileges to radiusd daemon on system resources. Please follow the steps below
to configure effective selinux policy for radiusd daemon:
* Start the radiusd daemon
* Test the RADIUS authentication with the test case provided in “Testing the
configuration” section below
* As radiusd daemon doesn’t have sufficient selinux privileges to access the
system resources required for using pam modules, the RADIUS authentication
will fail.
* This will create the logs in either “/var/log/messages” or in
“/var/log/audit/audit.log” depending on the selinux configuration.
* We can use audit2allow utility to provide selinux privileges to radiusd by
using following sequence of commands:
------
[root@testsrv ~]# audit2allow -m local -l -i /var/log/messages > local.te
[root@testsrv ~]# checkmodule -M -m -o local.mod local.te
[root@testsrv ~]# semodule_package -o local.pp -m local.mod
[root@testsrv ~]# semodule -i local.pp
------
For more selinux policy updating information and explanation of above commands
please visit the following website:
http://fedora.redhat.com/docs/selinux-faq-fc5/#id2961385
Test Setup :
------------
Our test environment is as follows:
* Operating System: Fedora release 8 (Werewolf)
* FreeRADIUS Server : FreeRADIUS Version 1.1.7
* Yubico PAM: pam_yubico Version 1.8
* "/etc/pam.d/radiusd" file:
------
auth required pam_yubico.so authfile=/etc/yubikeyid id=16 debug
auth include system-auth
account required pam_nologin.so
account include system-auth
password include system-auth
session include system-auth
------
Testing the configuration :
---------------------------
We have tested the pam_yubico configuration on following Linux sever platforms:
Fedora 8:
* Operating system: Fedora release 8 (Werewolf)
* FreeRADIUS Server : FreeRADIUS Version 1.1.7
* Yubico PAM: pam_yubico Version 1.8
Fedora 6:
* Operating system: Fedora Core release 6 (Zod)
* FreeRADIUS Server : FreeRADIUS Version 1.1.7
* Yubico PAM: pam_yubico Version 1.8
To test the RADIUS two factor authentication with YubiKey, we can use
“radtest” radius client. The command is as follows:
------
[root@testsrv ~]# radtest {username} \
{password followed by YubiKey generated OTP} \
{radius-server}:{radius server port} \
{nas-port-number} \
{secret/ppphint/nasname}
[root@testsrv ~]# radtest test test123vrkvit...bekkjc 127.0.0.1 0 testing123
------
Note :
------
The FreeRADIUS server version 1.1.3 seems to have problems regarding memory
management and it may result in Segmentation Fault if configured with Yubico
PAM module. We recommend using FreeRADIUS server version 1.1.7 or above.

223
doc/YubiKeyAndFreeRADIUSwithsinglefactorauthenticationviaPAM.txt Normal file
View File

@ -0,0 +1,223 @@
Yubico PAM Single-factor configuration guide
--------------------------------------------
Step by Step Guide for Configuration of Yubico PAM module to provide single
factor YubiKey OTP authentication for RADIUS server.
Introduction
------------
The purpose of this document is to guide readers through the configuration
steps to enable single factor authentication using YubiKey and RADIUS server
on Linux platform. This document assumes that the reader has advance knowledge
and experience in Linux system administration, particularly how to configure
PAM authentication mechanism on a Linux platform.
Details
-------
Prerequisites
-------------
Successful configuration of the Yubico PAM module to support single factor
authentication for RADIUS requires following prerequisites:
* Operating System: Any Unix operating system which supports PAM
(Pluggable Authentication Module)
(http://www.kernel.org/pub/linux/libs/pam/)
* Complier : GNU GCC complier (http://gcc.gnu.org/)
* FreeRADIUS: FreeRADIUS Version: 1.1.7 or *later*
(http://freeradius.org/download.html)
* Yubico PAM Module: Yubico PAM Module Version 1.8
(http://opensource.yubico.com/yubico-pam/)
Configuration
-------------
Configuration of FreeRADIUS server to support PAM authentication :
------------------------------------------------------------------
* Edit the radiusd configuration file “/etc/raddb/radiusd.conf” to make
following changes:
------
* Change user and group to “root” to provide the root privileges to
radiusd daemon so that it can call and use pam modules for authentication.
NOTE: Generally, it is not a good security practice to assign root
privileges to a user for a daemon. However, since use of PAM requires root
privileges, this is a mandatory step here.
* In “authenticate” section uncomment pam to direct radiusd daemon to use PAM
module for authentication
------
* Edit the client configuration file “/etc/raddb/clients.conf”
------
Add sample client for testing
------
* Edit the user configuration file “/etc/raddb/users” to make following change:
------
Change "DEFAULT Auth-Type = System" to "DEFAULT Auth-Type = pam" for using
PAM modules for user authentication
------
Installation of pam_yubico module :
-----------------------------------
Build instructions for pam_yubico are available in the README.
(https://github.com/Yubico/yubico-pam/wiki/ReadMe)
Configuration of pam_yubico module :
------------------------------------
Configuration instructions for pam_yubico are also available in the README.
(https://github.com/Yubico/yubico-pam/wiki/ReadMe)
_Make sure you set your system up for either central authorization mapping,
or user level mapping, as this will control which users can connect to the
system using RADIUS._
Configuration of modified pam_yubico.so module at administrative level :
------------------------------------------------------------------------
Append the following line to the beginning of /etc/pam.d/radiusd file:
------
auth required pam_yubico.so id=16 debug authfile=/etc/yubikey_mappings
------
After the above configuration changes, whenever a user connects to the
server using any RADIUS client, the PAM authentication interface will pass
the control to Yubico PAM module.
The Yubico PAM module first checks the presence of authfile argument in PAM
configuration. If authfile argument is present, it parses the corresponding
mapping file and verifies the username with corresponding YubiKey PublicID
as configured in the mapping file.
If valid, the Yubico PAM module extracts the OTP string and sends it to the
Yubico authentication server or else it reports failure. If authfile argument
is present but the mapping file is not present at the provided path PAM
module reports failure. After successful verification of OTP Yubico PAM module
from the Yubico authentication server, a success code is returned.
User Level :
------------
Although, user level configuration of pam_yubico is possible, this might not
be a desired configuration option in case of radisud daemon in most enterprise.
Configuration of selinux policy to create exception for radiusd daemon :
-----------------------------------------------------------------------
Local effective selinux policy must be updated to provide sufficient
privileges to radiusd daemon on system resources. Please follow the steps below
to configure effective selinux policy for radiusd daemon:
* Start the radiusd daemon
* Test the RADIUS authentication with the test case provided in “Testing the
configuration” section below
* As radiusd daemon doesn’t have sufficient selinux privileges to access the
system resources required for using pam modules, the RADIUS authentication
will fail.
* This will create the logs in either “/var/log/messages” or in
“/var/log/audit/audit.log” depending on the selinux configuration.
* We can use audit2allow utility to provide selinux privileges to radiusd by
using following sequence of commands:
------
[root@testsrv ~]# audit2allow -m local -l -i /var/log/messages > local.te
[root@testsrv ~]# checkmodule -M -m -o local.mod local.te
[root@testsrv ~]# semodule_package -o local.pp -m local.mod
[root@testsrv ~]# semodule -i local.pp
------
For more selinux policy updating information and explanation of above commands
please visit the following website:
http://fedora.redhat.com/docs/selinux-faq-fc5/#id2961385
Configuration of FreeRADIUS PAM file :
--------------------------------------
FreeRADIUS server first authorizes presence of user in the configured database
and then authenticates it.
In a single factor YubiKey authentication, we must provide a PAM mechanism to
authorize the presence of user.
We are using “pam_listfile.so” PAM module to provide a PAM mechanism to
authorize the presence of user. For this, we need to provide a file containing
authorized user names to the “pam_listfile.so” file. This file should contain
user names with only one user name on each line as follows:
For example:
------
paul
------
The user_name file must be created/updated manually before configuration of
Yubico PAM module for RADIUS authentication. Once this file is ready, we need
to edit the FreeRADIUS PAM configuration file “/etc/pam.d/radiusd” and replace
its contents with following lines:
------
auth sufficient pam_yubico.so id=16 debug authfile=/etc/yubikeyid
account required pam_listfile.so onerr=fail item=user sense=allow file=<Absolute path of file containing user names>
------
Test Setup :
------------
Our test environment is as follows:
* Operating System: Fedora release 8 (Werewolf)
* FreeRADIUS Server : FreeRADIUS Version 1.1.7 and Version 2.1.3
* Yubico PAM: pam_yubico Version 1.8
* "/etc/pam.d/radiusd" file:
------
auth sufficient pam_yubico.so id=16 debug authfile=/etc/yubikeyid
account required pam_listfile.so onerr=fail item=user sense=allow file=/etc/yubicousers
------
Testing the configuration :
---------------------------
We have tested the pam_yubico configuration on following Linux sever platforms:
* Fedora 8:
------
* Operating system: Fedora release 8 (Werewolf)
* FreeRADIUS Server : FreeRADIUS Version 1.1.7 and Version 2.1.3
* Yubico PAM: pam_yubico Version 1.8
------
* Fedora 6:
------
* Operating system: Fedora Core release 6 (Zod)
* FreeRADIUS Server : FreeRADIUS Version 1.1.7 and Version 2.1.3
* Yubico PAM: pam_yubico Version 1.8
------
To test the RADIUS single factor authentication with YubiKey, we can use
“radtest” radius client. The command is as follows:
------
[root@testsrv ~]# radtest {username} \
{password followed by YubiKey generated OTP} \
{radius-server}:{radius server port} \
{nas-port-number} \
{secret/ppphint/nasname}
[root@testsrv ~]# radtest test vrkvfefuitvfvgu...ildbdk 127.0.0.1 0 testing123
------
Note :
------
The FreeRADIUS server version 1.1.3 seems to have problems regarding memory
management and it may result in Segmentation Fault if configured with Yubico
PAM module. We recommend using FreeRADIUS server version 1.1.7 or above.

328
doc/YubiKeyAndOpenVPNviaPAM.txt Normal file
View File

@ -0,0 +1,328 @@
Introduction
------------
The purpose of this document is to guide readers through the configuration steps to use two factor authentication for OpenVPN using YubiKey. This document assumes that the reader has advanced knowledge and experience in Linux system administration, particularly for how PAM authentication mechanism is configured on a Linux platform.
Details
-------
Prerequisites
-------------
Successful configuration of the Yubico PAM module to support two factor authentication for OpenVPN has the following prerequisites:
* Operating System: Any Unix operating system which supports PAM (Pluggable Authentication Module)
(http://www.kernel.org/pub/linux/libs/pam/)
* Complier : GNU GCC complier (http://gcc.gnu.org/)
* Yubico PAM Module: Yubico PAM Module Version 1.8. (http://opensource.yubico.com/yubico-pam/)
* OpenVPN: OpenVPN Version 2.0.9. (http://openvpn.net/index.php/downloads.html)
* FreeRADIUS: FreeRADIUS Version: 1.1.7 or later. (http://freeradius.org/download.html)
* Pam_Radius: pam_radius Version 1.3.17. (ftp://ftp.freeradius.org/pub/radius/pam_radius-1.3.17.tar.gz)
Configuration
-------------
There are two ways OpenVPN can be configured to support two factor authentication with YubiKey.
A) OpenVPN Configuration without FreeRADIUS support:
----------------------------------------------------
In this mode of configuration, OpenVPN server will be authenticating users
by verifying username and user’s password against system password file
“/etc/passwd” and verifying OTP (one time password generated from YubiKey)
against Yubico’s OTP validation server.
We assume that OpenVPN server is already installed on the server.
a) Configuration of OpenVPN server to support PAM authentication:
-----------------------------------------------------------------
* Edit the OpenVPN server configuration file “/etc/openvpn/server.conf”
to add the following three lines to enable PAM modules for username
and password authentication:
------
plugin <Absolute path of “openvpn-auth-pam.so” file> <PAM configuration file name for OpenVPN
client-cert-not-required
username-as-common-name
------
(For e.g.: plugin /usr/lib/openvpn/plugin/lib/openvpn-auth-pam.so openvpn)
* Edit the OpenVPN client configuration file “/etc/openvpn/client.conf” to
add following line to configure OpenVPN client for prompting username and
password:
------
auth-user-pass
------
b) Installation of pam_yubico module:
-------------------------------------
Build instructions for pam_yubico are available in the README:
https://github.com/Yubico/yubico-pam/wiki/ReadMe
c) Configuration of pam_yubico module:
--------------------------------------
*) Configuration for user and YubiKey PublicID mapping
There are two ways of user and YubiKey PublicID (token ID) mapping.
It can be either done at administrative level or at individual user level.
Administrative Level
--------------------
In Administrative level, system administrators hold right to configure
the user and YubiKey PublicID mapping. Administrators can achieve this
by creating a new file that contains information about the username and
the corresponding PublicIDs of YubiKey(s) assigned.
This file contains user name that is allowed to connect to the system
using RADIUS and the PublicID of the YubiKey(s) assigned to that
particular user.
A user can be assigned multiple YubiKeys and this multikey mapping is
supported by this file. However, presently there is no logic coded to
detect or prevent use of same YubiKey ID for multiple users.
Each record in the file should begin on a new line. The parameters in
each record are separated by “:” character similar to /etc/passwd.
The contents of this file are as follows:
------
<user name>:<YubiKey PublicID>:<YubiKey PublicID>: ….
<user name>:<YubiKey PublicID >:<YubiKey PublicID>:…..
------
e.g.:
------
paul:indvnvlcbdre:ldvglinuddek
simon:uturrufnjder:hjturefjtehv
kurt:ertbhunjimko
------
The mapping file must be created/updated manually before configuration
of Yubico PAM module for OpenVPN authentication.
Configuration of modified pam_yubico.so module at administrative level:
-----------------------------------------------------------------------
Append the following line to the beginning of /etc/pam.d/radiusd file:
------
auth required pam_yubico.so id=16 debug authfile=/path/to/mapping/file
------
After the above configuration changes, whenever a user connects to the
server using any RADIUS client, the PAM authentication interface will
pass the control to Yubico PAM module.
The Yubico PAM module first checks the presence of authfile argument
in PAM configuration. If authfile argument is present, it parses the
corresponding mapping file and verifies the username with corresponding
YubiKey PublicID as configured in the mapping file. If valid, the Yubico
PAM module extracts the OTP string and sends it to the Yubico
authentication server or else it reports failure. If authfile argument
is present but the mapping file is not present at the provided path PAM
module reports failure.
After successful verification of OTP Yubico PAM module from the Yubico
authentication server, a success code is returned.
User Level:
-----------
Although, user level configuration of pam_yubico is possible, this might
not be a desired configuration option in case of OpenVPN daemon in most
enterprise.
ii) Configuration of PAM modules for OpenVPN:
---------------------------------------------
To configure PAM modules for OpenVPN, create a file named
“/etc/pam.d/openvpn” (file name must be one which is specified
in “/etc/openvpn/server.conf“ along with “plugin” directive)
and list all the PAM modules in this files accordingly.
d) Test Setup:
--------------
Our test environment is as follows:
i) Operating System: Fedora release 8 (Werewolf)
ii) OpenVPN Server : OpenVPN Version 2.0.9
iii) Yubico PAM: pam_yubico Version 1.8
iv) "/etc/pam.d/openvpn" file:
------
auth required pam_yubico.so authfile=/etc/yubikeyid id=16 debug
auth include system-auth
account required pam_nologin.so
account include system-auth
password include system-auth
session include system-auth
------
e) Testing the configuration:
-----------------------------
We have tested the pam_yubico configuration on following Linux sever platforms:
i) Fedora 8:
Operating system: Fedora release 8 (Werewolf),
OpenVPN Server : OpenVPN Version 2.0.9,
Yubico PAM: pam_yubico Version 1.8
ii) Fedora 6:
Operating system: Fedora Core release 6 (Zod),
OpenVPN Server: OpenVPN Version 2.0.9,
Yubico PAM: pam_yubico version 1.8
To test the configuration, first create a couple of test users on the
system where OpenVPN server is running and configure their YubiKey IDs
accordingly.
Please use the following command for testing:
------
[root@testsrv ~]# openvpn /etc/openvpn/client.conf
------
OpenVPN client will first prompt for username, enter the username.
After that OpenVPN client will prompt for password, enter user’s password
immediately followed by an OTP generated by a YubiKey.
If OpenVPN server is configured for supporting PAM authentication, it
will verify user authentication details even at the startup of OpenVPN
server demon, when it is started using “init.d” script or it is
configured to start at boot time.
To avoid prompting of username and password at the startup of OpenVPN
server demon, we can start OpenVPN Server demon at command line as
follows instead of starting it using “init.d” script:
------
[root@testsrv ~]# /usr/sbin/openvpn --config /etc/openvpn/server.conf --daemon openvpn
------
We can configure OpenVPN server demon to start at boot time by
copying the above command in /etc/rc.local file.
B) OpenVPN Configuration with FreeRADIUS support:
-------------------------------------------------
In this type of configuration, the OpenVPN server will be using
FreeRADIUS server for authenticating users. FreeRADIUS server will
be verifying the authentication information received from OpenVPN
server by verifying the username and user’s password against system
password file “/etc/passwd” (or by other means supported by FreeRADIUS)
and verifying the OTP (one time password) generated by a YubiKey
with the Yubico’s OTP validation server.
To configure OpenVPN with FreeRADIUS support, please follow the steps below:
* Follow all the steps mentioned in the section “OpenVPN Configuration without FreeRADIUS support” to configure OpenVPN server to support PAM authentication.
* Install and configure FreeRADIUS server for two factor authentication using following wiki link:
https://github.com/Yubico/yubico-pam/wiki/YubiKeyAndFreeRADIUSviaPAM
* Install and configure pam_radius_auth.so and copy it to /lib/security directory
* Create a file “/etc/pam.d/openvpn” (file name must be the one which is specified
in “/etc/openvpn/server.conf “ along with “plugin” directive) and copy the following
contents to the file:
------
account required pam_radius_auth.so
account required pam_radius_auth.so
auth required pam_radius_auth.so no_warn try_first_pass
------
* Create a file “/etc/raddb/server” to configure FreeRADIUS server that is
used by pam_radius_auth PAM module. The content for the file is as follows:
------
<RADIUS server fully qualified domain name/IP Address> <Shared Secret>
<RADIUS server fully qualified domain name/IP Address> <Shared Secret>
.
.
.
------
e.g.:
------
freeradius.example.com Admin456
------
We can configure failover support for RADIUS server by creating additional
RADIUS server entries per line of “/etc/raddb/server” file.
A) Test Setup:
--------------
Our test environment is as follows:
i) Operating System: Fedora release 8 (Werewolf)
ii) FreeRADIUS Server : FreeRADIUS Version 1.1.7
iii) Pam_Radius: pam_radius_auth 1.3.17
iv) Yubico PAM: pam_yubico Version 1.8
iv) "/etc/pam.d/openvpn" file:
------
account required pam_radius_auth.so
account required pam_radius_auth.so
auth required pam_radius_auth.so no_warn try_first_pass
------
B) Testing the configuration:
-----------------------------
We have tested the pam_yubico configuration on following Linux sever platforms:
i) Fedora 8:
Operating system: Fedora release 8 (Werewolf),
OpenVPN Server : OpenVPN Version 2.0.9,
Yubico PAM: pam_yubico Version 1.8,
FreeRADIUS Server: FreeRADIUS Server Version 1.1.7,
Pam_radius: pam_radius_auth Version 1.3.17
ii) Fedora 6 :
Operating system: Fedora Core release 6 (Zod),
OpenVPN Server: OpenVPN Version 2.0.9,
Yubico PAM: pam_yubico version 1.8,
FreeRADIUS Server: FreeRADIUS Server Version 1.1.7,
Pam_radius: pam_radius_auth Version 1.3.17
To test the configuration, first create a couple of test users
on the system where FreeRADIUS server is running and configure
their YubiKey IDs accordingly.
Please use the following command for testing:
------
[root@varsha ~]# openvpn /etc/openvpn/client.conf
------
OpenVPN client will first prompt for username, enter the username.
After that OpenVPN client will prompt for password, enter user’s
password immediately followed by an OTP generated by a YubiKey.
_Note:_
-------
_Please use OpenVPN server Version 2.0.9 (Latest Stable Version), as older and newer beta versions have problems with PAM libraries. RADIUS authentication will fail if it is configured with older or latest beta versions of OpenVPN Server._

7
doc/Yubikey-and-SELinux-on-Fedora-18-and-up.txt Normal file
View File

@ -0,0 +1,7 @@
Starting with Fedora 17, SELinux prevents sshd to initiate connections to remote HTTP ports (80 and 443). In SELinux terms: sshd_t is not allowed to name_connect to http_port_t. This broke Yubikey authentication on a system with SELinux in enforcing mode, unless a custom SELinux policy was written and enabled.
Based on a [bugreport](https://bugzilla.redhat.com/show_bug.cgi?id=841693) in Red Hat Bugzilla, a boolean was added to the SELinux policy for Fedora 18 and up, that can be toggled to allow sshd (and some other SELinux types) to connect to remote HTTP ports.
To make a long story short, if you want to use a Yubikey on a system running Fedora 18 or higher (and probably RHEL7, eventually), you'll need to toggle the 'authlogin_yubikey' SELinux boolean, like so:
setsebool -P authlogin_yubikey 1

63
doc/YubikeyAndRadiusViaPAM.txt Normal file
View File

@ -0,0 +1,63 @@
Introduction
------------
The purpose of this page is to collect all information needed to set up a Radius server that can use the pam_yubico module to provide user authentication via Radius.
Details
-------
We currently use FreeRadius. The paths below may be specific to Debian's packages, please update this if you have paths for other systems.
Build pam_yubico and install FreeRadius
---------------------------------------
Build instructions for pam_yubico are found in the pam_yubico ReadMe.
Install FreeRadius from your OS vendor packages:
Debian/Ubuntu:
------
$ sudo apt-get install freeradius
------
== Add a Radius client stanza to /etc/freeradius/clients.conf
For testing, add something like:
------
client 0.0.0.0/0 {
secret = pencil
shortname = radius.yubico.com
}
------
Configure FreeRadius so that it uses PAM
----------------------------------------
In /etc/freeradius/radiusd.conf, check that 'pam' is uncommented in the 'authenticate' section.
Configure PAM for the Radius server
-----------------------------------
The PAM service is 'radiusd', and the configuration file is stored in /etc/pam.d/radiusd. Add something like:
------
auth sufficient pam_yubico.so id=16 debug
------
Start FreeRadius in debug mode and test it
------------------------------------------
As root, run:
------
# /usr/sbin/freeradiusd -X
------
Then invoke a test client as follows:
------
$ radtest yubico vlrlcingbbkrctguicnijbegfjhrdhccefdthcuifkgr 127.0.0.1 0 pencil
------
If you get errors about non-existing user, you may need to create a Unix user 'yubico'. Whether this should be needed or not depends on PAM configuration.

275
doc/YubikeyAndSSHViaPAM.txt Normal file
View File

@ -0,0 +1,275 @@
Introduction
------------
The purpose of this document is to guide readers through the configuration
steps to use two factor authentication for SSH using Yubikey. This document
assumes that the reader has advanced knowledge and experience in Linux
system administration, particularly for how PAM authentication mechanism is
configured on a Linux platform.
Details
-------
Prerequisites
-------------
Successful configuration of the Yubico PAM module to support two factor
authentication requires following prerequisites:
1) Operating System: Any Unix operating system which supports PAM
(Pluggable Authentication Module)
(http://www.kernel.org/pub/linux/libs/pam/)
2) Complier : GNU GCC complier (http://gcc.gnu.org/)
3) Yubico Client C library version 1.5 or later
(http://opensource.yubico.com/yubico-c-client/)
4) Yubico PAM Module: Yubico PAM Module Version 1.7 or later
(http://opensource.yubico.com/yubico-pam/)
System Requirements
-------------------
This document illustrates the configuration steps for Fedora Core 8
operating system. However, there steps should work on most other Linux
distributions.
The Yubico PAM module for SSH can be downloaded from:
http://opensource.yubico.com/yubico-pam/releases.html
The Yubico PAM module support two factor authentication for SSH.
The two factor authentication module verifies the user name and password
for the user and the one time password (OTP) generated by Yubikey assigned
to the user.
Build yubico-c-client and pam_yubico
------------------------------------
Build instructions for yubico-c-client are found in the README:
https://github.com/Yubico/yubico-c-client/wiki/ReadMe
Build instructions for pam_yubico are found in the README:
https://github.com/Yubico/yubico-pam/wiki/ReadMe
Configuration
-------------
Configuration for user and yubikey token ID mapping:
----------------------------------------------------
There are two ways of user and yubikey token ID mapping. It can be either
done at administrative level or at individual user level.
1) Administrative Level:
------------------------
In Administrative level, system administrators hold right to configure the
user and yubikey token ID mapping. Administrators can achieve this by creating
a new file that contains information about the username and the corresponding
IDs of Yubikey(s) assigned.
This file contains user name that is allowed to connect to the system over SSH
and the token id of the Yubikey(s) assigned to that particular user. A user
can be assigned multiple Yubikeys and this multi key mapping is supported by
this file. However, presently there is no logic coded to detect or prevent use
of same Yubikey ID for multiple users.
Each record in the file should begin on a new line. The parameters in each
record are separated by “:” character similar to /etc/passwd.
The contents of this file are as follows:
<user name>:<yubikey token ID>:<yubikey token ID>: ….
<user name>:<yubikey token ID>:<yubikey token ID>:…..
e.g.
--------
paul:indvnvlcbdre:ldvglinuddek
simon:uturrufnjder:hjturefjtehv
kurt:ertbhunjimko
--------
The mapping file must be created/updated manually before configuration of
Yubico PAM module for SSH authentication.
Configuration of modified pam_yubico.so module at administrative level:
-----------------------------------------------------------------------
Append the following line to the beginning of /etc/pam.d/sshd file:
--------
auth required pam_yubico.so id=16 debug authfile=/path/to/mapping/file
--------
Make sure you set id=16 to the correct API-id for the yubico validation server.
After the above configuration changes, whenever a user connects to the server
using any ssh client, the PAM authentication interface will pass the control to
Yubico PAM module. The Yubico PAM module first checks the presence of authfile
argument in PAM configuration. If authfile argument is present, it parses the
corresponding mapping file and verifies the username with corresponding
Yubikey token id as configured in the mapping file. If valid, the Yubico PAM
module extracts the OTP string and sends it to the Yubico authentication server
or else it reports failure. If authfile argument is present but the mapping
file is not present at the provided path PAM module reports failure. After
successful verification of OTP Yubico PAM module from the Yubico
authentication server, a success code is returned.
2) User Level:
--------------
In User level, individual users have the ability to configure yubikey token
ID assigned to them. Users can achieve this by creating a new file
".yubico/authorized_yubikeys" inside their home directories that contains
information about the username and the corresponding IDs of Yubikey(s) assigned
to them. A user can be assigned multiple Yubikeys and the multi key mapping is
supported by this file.
This file must contain only one record. The parameters in the record are
separated by “:” character similar to /etc/passwd. The contents of this file
are as shown below:
<user name>:<yubikey token ID>:<yubikey token ID>: ….
e.g.
------
paul:indvnvlcbdre:ldvglinuddek
------
The .yubico/authorized_yubikeys file must be created/updated manually and must
be placed inside user's home directory before configuration of Yubico PAM
module for SSH authentication.
Configuration of modified pam_yubico.so module at user level:
-------------------------------------------------------------
Append the following line to the beginning of /etc/pam.d/sshd file:
-------
auth required pam_yubico.so id=16 debug
-------
After the above configuration changes, whenever a user connects to the server
using any SSH client, the PAM authentication interface will pass the control
to Yubico PAM module. The Yubico PAM module first verifies the username with
corresponding Yubikey token id as configured in the .yubico/authorized_yubikeys
file that present in the user's home directory who is trying to assess server
through SSH. If valid, the Yubico PAM module extracts the OTP string and sends
it to the Yubico authentication server or else it reports failure. After
successful verification of OTP Yubico PAM module from the Yubico authentication
server, a success code is returned.
3) pam_unix.so configuration:
-----------------------------
Append _try_first_pass_ parameter to the _pam_unix.so_ module to authenticate
the user with password passed from the preceding auth module.
The _pam_unix.so_ module used for authentication is generally located into
_"/etc/pam.d/system-auth"_ for RedHat based Linux system and into
_"/etc/pam.d/common-auth"_ for Debian based Linux systems.
4) SSH configuration:
---------------------
Edit the sshd configuration file _“/etc/ssh/sshd_config”_ to disable challenge-
response passwords. Change _“challenge-response passwords yes”_ to
_“challenge-response passwords no”_.
Test Setup:
-----------
A) Fedora 8:
------------
Test setup for fedora 8 environment is as follows:
• OS Version: Fedora release 8 (Werewolf)
• Kernel Version: Kernel version 2.6.23.1-42.fc8
• OpenSSH Version : openssh-4.7p1-2.fc8
• Yubico PAM Version: pam_yubico-1.7
B) Fedora 6:
------------
Test setup for fedora 6 environment is as follows:
• OS Version: Fedora Core release 6 (Zod)
• Kernel Version: Kernel version 2.6.18-1.2798.fc6
• OpenSSH Version : openssh-4.3p2-10
• Yubico PAM Version: pam_yubico-1.7
PAM configuration:
------------------
PAM configuration files in our testing environment are as follows:
* /etc/pam.d/sshd:
-------
auth required pam_yubico.so authfile=/etc/yubikeyid id=16 debug
auth include system-auth
account required pam_nologin.so
account include system-auth
password include system-auth
session optional pam_keyinit.so force revoke
session include system-auth
session required pam_loginuid.so
-------
* /etc/yubikeyid:
-------
root:indvnvlcbdre:ldvglinuddek
test:ldvglinuddek
-------
* /root/.yubico/authorized_yubikeys:
-------
root:indvnvlcbdre:ldvglinuddek
-------
Please change PAM configuration settings for SSH as shown above and test the
configuration.
Testing the Configuration:
--------------------------
We assume that you have “root” and “test” user configured to access SSH on your
test environment with password “secret” and “pencil” respectively.
Use any standard SSH client for testing (We used SSH command line utility).
Try to login to server with SSH client as configured user:
------
$ ssh -l test localhost
Password: (enter 'pencil' and touch the ldvglinuddek yubikey)
------
------
$ ssh -l root localhost
Password: (enter 'secret' and touch the ldvglinuddek yubikey)
------
------
$ ssh -l root localhost
Password: (enter 'secret' and touch the indvnvlcbdre yubikey)
------