Project Page
Download
CA Web Helper Project

DarkSoft News DarkSoft Projects
Intro
-----

This module provides password-less login authentication on local consoles based on X509 
certificates and private keys stored on some personal data holders like USB Sticks, Bluetooth 
mobile phones and etc...

Currently supported two methods of authentication:
1. To provide user certificate and private key in some auto-mountable location using supermount
or automount. It can be usb stick, floppy disk, CD disk, SD card or may be more exotic device.
2. To provide user certificate and private key truth rfcomm bluetooth connection.

Why
---

I'm to lazy to remember passwords. Ok if You are loged there no problems, you can use ssh keys, 
you can use x509 authentication with telnet, ftp, http. Even you can use different programms
which will cache password for You. This module eleminates last place you require your password. 

Requirements
------------
    1. PAM
    2. OpenSSL
    
    For bluetooth support:
    3. Bluez
    4. OpenObex
    5. OpexFTP
    
    All this software can be found on sourceforge!

Arguments
---------
    ca_dir=	- Directory with trusted Certificate Authority certificates
    ca_file=	- File with trusted Certficate Authority certificate chain (/opt/ssl/ca/chain.crt by default)
    crl_dir=	- Directory with revocation lists (/opt/ssl/crl/ by default)
    crl_file=	- File with revocation lists
    key_dir=	- Automountable directory containig user private keys and certificates
    bluetooth	- Enable bluetooth authentication (Slow)

Configuration Files
-------------------
    /etc/x509.securetty	- List of consoles password-less authentication permited for. Simmiliar to
    standard /etc/securetty.

    /etc/x509.config - X509 authentication configuration. Authentication code was taken from 
    bsdftpd-ssl and file have same configuration like bsdftpd-ssl /etc/x509.users file. 
    For format docs please look in bsdftpd folder with original documentation.
    
    /var/spool/x509/ - Temporary folder required for bluetooth authentication. Group and Others 
    must not have any permissions on it.

Notes
-----
    1. Encrypted private keys also supported. In this case will be used standard password dialog.
    
    2. It's possible to autodetect user name, just press enter then promted for user name. But 
    this is not supported by mingetty. Just use agetty with "-n" option. Or (better) use my patch
    for mingetty (available in patches directory). 
    
Compilation
-----------
    Set it Makefile "bt=yes" to permit bluetooth authentication, disabled by default.
    You can edit some default paths in "sslauth.h" header file.

Installation
------------
    Create /etc/x509.securetty, /etc/x509.config files and /var/spool/x509 directory. Then copy
    pam_x509.so in /lib/security. 
    And finally insert appopriate line in /etc/pam.d/login (Do not put it in system-auth!!!)

Related Projects
----------------
    You can also look on "Certificate Authority Web Helper" (http://sourceforge.net/projects/cawh/)
    project. Intended to help mantain your certificate authority.

Configuration Examples
----------------------
    1. /etc/x509.config
	---- File Start -----
	/CN:-r
	---- File End -------
	In this case user provided valid, not expired and not revoked certificate will be able 
	to login under user name corresponded to commonName specified in his certificate.

    2. /etc/x509.securetty
	Can be linked to /etc/securetty to permit logins on same consoles as for root user.

    3. /etc/pam.d/x509-auth
	---- File Start -----
	auth        required      /lib/security/pam_env.so
	auth	    sufficient	  /root/3/pam_x509/pam_x509.so
	auth        required      /lib/security/pam_deny.so
	---- File End -------

	And afterwards you must add to /etc/pam.d/login following line
	auth       sufficient	/lib/security/pam_stack.so service=x509-auth
	in my Mandrake Linux 9.1 all file looks like this:
	---- File Start -----
	auth       required	/lib/security/pam_securetty.so
	auth       required	/lib/security/pam_nologin.so
	auth       sufficient	/lib/security/pam_stack.so service=x509-auth
	auth       required	/lib/security/pam_stack.so service=system-auth
	account    required	/lib/security/pam_stack.so service=system-auth
	password   required	/lib/security/pam_stack.so service=system-auth
	session    required	/lib/security/pam_stack.so service=system-auth
	session    optional	/lib/security/pam_console.so
	---- File End -------

	In this case system try to authorize user with x509 certificate and private key pair. If 
	it fails user promted for password and standard authentication used.
	
	Note
	----
	    This module also can be used not to simplify user's life but for stronger deffence. For
	    example you can require from users to present their certificate/key pair and then ask
	    for password.
    
    
    4. /etc/fstab
	---- File Start -----
	none /mnt/auth supermount dev=/dev/sda,fs=vfat,ro,--,iocharset=utf8,umask=0777 0 0
	---- File End -------
	This string provides automounting support for USB Sticks. Some comments.
	/mnt/auth - Default location module checks for certificates and private keys
	dev=/dev/sda - I haven't SCSI devices on this PC. So my USB Stick reckognized as /dev/sda.
	umask=0777 - It's very important!!! This location must not be seen by other users!!!
	
	SECURITY NOTE
	-------------
	You can want to have certificates and keys not in root directory but in some subdirectories,
	for example /mnt/auth/mycerts. Don't do it!!! It's very insecure. For example if you hold
	your keys on server in directory /home/me/secinfo and very evil hacker know about it. He
	can make mycerts to link on /home/me/secinfo and successfully login under your credentials.
    
    5. Ok. now you must put your certificate and key on your usb stick in root directory with names
    ".key" for private key and .crt" for X509 certificate. "" in both
    cases must be indentical ;)
    
    NOTE
    ----
	Realy you can have multiple certificate on your storage. All will be checked and you will 
	be logged with first accepted. 
	Still it isn't recomended from security point of view to have on one usb stick keys for 
	different computer systems.

Bluetooth Configuration
-----------------------
    Requirements
    ------------
	1. Your bluetooth device must support OBEX protocol. My Siemens S55 do ;)
	2. Kernel bluetooth support. As I know stable (less or more) bluetooth support in kernel 
	since 2.4.21 and there are some patches for older versions.
	    2a. "bluez", "l2cap", "rfcomm" and bluetooth adapter driver modules (hci_usb for most
	    usb adapters) must been loaded.
	3. Bluez: libbluez, bluez-sdp, bluez-utils (rfcomm)
	    2a. Running and configured bluez-sdp(bluetooth) daemon.
	4. OpenObex Library
	5. ObexFTP Libraries
	6. You must bind rfcomm connections to all posible authentication sources (You can do it
	for example from rc.local script).
		rfcomm bind 
		rfcomm bind 
		...
	    Performance Note
	    ----------------
		In this first version of module still multiple bluetooth clients supported it's 
		recomended to use it only for personal (single person) authentication, because of
		establishing connection to bt device is far from fast. 
		I hope this will be fixed in next release.
	    	
	5. Put certificate and key on your device, still 
	
	Stability Notes
	---------------
	As I say before linux bluetooth support is far from mature and something may go wrong. Realy
	in my case:
	    1. Sometimes S55 phone stops to accept bluetooth connection. Restarting of phone fixing
	    this problem.
	    2. Sometimes linux bluetooth driver stop working. In this only solution I find is full
	    restart.
	    
	    I hope 2.6 kernels will have more mature support of bluetooth and all this staff will 
	    work excelent :)
	
	Notes
	-----
	    You can also try to use for bluetooth authentication standard automountable mechanism
	    with siefs file system (available on freshmeat) but it's very-very unstable...
	    



SourceForge Logo