README for OpenFortress_pam_epass ================================= These are utilities for a basic PAM-style authentication with only an ePass1000 hardware token. It may also work on its big brother, ePass2000, but it would be a pitty not to use its public key features instead. Installation: Unpacking of this tarball should be done *inside* the main directory into which the Feitian tar-ball with the Linux SDK is unpacked. Notably, the directories ../include and ../api are assumed to be present as in the SDK. To build, type "make". To install, type "make install" as root. The ePass1000 can be purchased, including a privately pre-installed password for this application, at www.epass.nl. Utilities: welcome_pam_epass_user --> Inserted ePass welcomes a user/realm combi setup_pam_epass --> Setup OpenFortress_pam_epass on inserted ePass destroy_pam_epass --> Remove OpenFortress_pam_epass token securely pam_epass_onetimehmac.so --> The PAM module Assumptions made: The OpenFortress_pam_epass data is usable for challenges by anyone. In other words, the PAM module does not attempt to login to the ePass. The ePass contains a passphrase, also called a PIN. The PIN as setup with epassedit is not compatible with the general idea that seems to arise from ePass1000 documentation. The epassedit tool compresses digits in a BCD-format which is even big-endian for added ugliness. This is how that seems to work: epassedit PIN: 1234 realworld PIN: \x34\x33\x32\x31 Token setup: This is done with the setup_pam_epass application, while a single ePass is plugged into the USB port. This is how it is done: root# setup_pam_epass Setting up the OpenFortress_pam_epass application on ePass #82587a0db2e2e7 We need to login to the ePass as security officer. SO-Passphrase: ************ The application OpenFortress_pam_epass was successfully created. Now use welcome_pam_epass_user to create user/realm combinations. There may be more applications on the same ePass token. The opposite to the above is the destroyer for this application (and only for that): root# destroy_pam_epass Setting up the OpenFortress_pam_epass application on ePass #82587a0db2e2e7 We need to login to the ePass as security officer. SO-Passphrase: ************ The application OpenFortress_pam_epass was successfully destroyed. This ePass token will not be able to login through this application anymore. Note that last line -- you are capable to shread every chance that the token will be used in the future, just by destroying the application. If you setup the application after this is done, you will generate a new token on the ePass device, so it will behave like it is a new one (except, perhaps, that it still has challenge tokens floating around on machines on your net). You can also do this manually, using the epassedit utility. The directory OpenFortress_pam_epass holds all the data related to this application. Users and realms: Authentication takes into account which username and realm exist. A realm is a `scope of authentication' and a user is the name as which someone wants to identify, using PAM. Note that the user is *not* the person requesting access! To welcome a user/realm combination, invoke the welcome_pam_epass_user tool, with arguments describing them. The result will be stored in a file under /etc/pam_epass/onetimehmac, from where the sysadmin or the user can delete it to disallow further access. This is how it normally works: root# welcome_pam_epass_user user=root realm=admin A warm welcome to ePass #82587a0db2e2e7 is about to be created Wrote /etc/pam_epass/onetimehmac/realm=admin/user=root/82587a0db2e2e7 If no realm is provided, "realm=default" will be substituted. The file contains a challenge to the ePass that cannot be simply faked by parties able to read this file. It does not contain the password or other code in plain text. It cannot be taken to another realm, another user. It cannot be used with another token, or when the same token is re-setup after the application is destroyed. It is possible however to carry a token like this over to another system. You could even consider using NFS to share the token over your network. But it would probably not be a good idea to do so; copying these tokens manually when the need arises seems like a better idea. Configuration of PAM: Interesting modules to enhance with an ePass constraint are the commands that grant access, such as su and sudo for (mainly) root access, as well as login, gdm, kdm, xdm for plain system access. In addition, it is interesting to consider adding it to xscreensaver, which takes care of locking the screen after a timeout or after locking the desktop. A single line must be added to get this to work; for example, this line could be added to /etc/pam.d/su: auth required /lib/security/pam_epass_onetimehmac.so realm=admin Some configurations use a /etc/pam.conf file instead, which would work with the following kind of extra line: su auth required /lib/security/pam_epass_onetimehmac.so realm=admin The realm is the same as was entered on the welcome_pam_epass_user command line, and here too the default substitution is "realm=default". Be a little careful; not all applications will process the conversation that this module starts when it needs the passphrase for the ePass. On RedHat 8.0, we noticed good behaviour from all of gdm, su, sudo and login; but xscreensaver did not, so if you unplug the token during "lock screen" you would not be able to login there; you could resolve by logging in on a console (and enter the ePass passphrase there) and then return to the graphical interface. Future extensions: A few extensions to this mechanism are possible. The current PAM module does not verify whether a user is actually working on the console. It would perhaps make sense to enforce that when this module is called, because being relied on behalf of the ePass would otherwise be awkward. A sysadmin could plugin his token and instantly gain access to the root account if the token is setup for "sufficient" authentication. Not sure if this functionality should be in here, or in another module. It could be useful to require a particular token on the PAM configuration file, and not just any token that has been setup with welcome_pam_epass_user for some realm. The unique number stored in the token could be useful there, or one could be fabricated by storing a random number in one of the files under the application. Requiring a particular token, or one from a particular set perhaps, would be useful to allow console admin access (perhaps after a PIN has been entered) to systems and/or realms. It would obviously be stronger to allow public key cryptography. The Windows library that comes with the ePass1000 is not suitable for this, because it performs the cryptographic calculations off-token. The newer model ePass2000 however, would be suitable for this. In general, an approach based on PKCS #11 libraries would seem prudent. The ePass1000 code would ideally also be pushed outward into a library conforming to this standard (but only implement the symmetric crypto parts of it). The current PAM module does not take into account that multiple tokens could be inserted in the USB bus. It would be nice if it would iterate over tokens until it found one that works. Previous issues now resolved: It would be interesting to support entering a PIN (instead of, or in addition to) a password. This could be done with other key numbers, like 3 and 4, in the same application directory on the ePass token. The options to the PAM module could stipulate a specific setup if so desired. -> The PIN is now entered in the course of a PAM conversation. The reliance on installation of these files inside the ePass SDK is not very pleasant. Installation of a development kit is better. -> Installed epassapi.h and .a in a prefix [/usr] is now assumed.