README for nds.c

-----------------------------------------------------------------------------


-----------------------------------------------------------------------------
NAME
       nds - authenticate a user and start a program

SYNOPSIS

       nds (--user <user>) (--exec <command (options ...) | (--silent)>

DESCRIPTION

       The nds program is intended to authenticate a user using the PAM
       subsystem. If the user was properly authenticated nds either starts 
       up a program, returns an exit code or prints the string 'Authenticated'.
       If the user could not be properly authenticated nds will either return
       the appropriate exit code or print the string "Not Authenticated".

       OPTIONS

       -u <user>
       --user <user>

         Specify the username to be user for the PAM authentication. By 
         default the name of the current user is used (the name the remote 
         user specified)

       -s 
       --silent

         This option will force nds to authenticate the user using the PAM 
         subsystem, but will NOT start up a program nor will it generate any
         output (except output generated by the PAM subsystem). It will 
         return 1 on success and 0 if the user could not be autenticated. 
         Used for debugging purposes or to enable authentication over the PAM 
         subsystem within shell scripts.

       -e <'command and parameters>'>
       --exec <'command and parameters>'>

         authenticate the user using the PAM subsystem and start up the 
         specified program (with proper parameters). 

       Note that -e and -s are mutually exclusive.


       PURPOSE

       The program was originally intended to be used as a relaying program,
       to be run by sshd on a relayhost in a DMZ, see figure below:

       user --> Internet --> router --> relayhost --> router --> targethost
                             |                                 |
                             |------------- DMZ ---------------|

       - a user requires some service, let's say a terminal session 

       - the user connects to the relayhost over the Internet using a 
         ssh client, e.g.  'putty' (on Windows platforms) or ssh on Unix
         platforms

       - the sshd on the relayhost will perform authentication. We assume
         that public key authentication is used.

       - if the user has the proper credentials, the program 'nds' will be
         started

       - nds in turn will query the PAM subsystem for proper authentication

       - the PAM subsystem will start up neccessary additional authentication
         mechanisms, e.g. the user could be prompted for a username/password,
         could receive a challenge for which he/she has to generate the proper
         response etc. 

       - if properly authenticated nds will start up its specified program 
         which in turn provides the proper service to the end-user, for 
         example ssh or telnet. 
       

EXAMPLES
 
       CONFIGURATION      

       * Using nds to authenticate against a Novell Domain Server

         Create the file 'nds' in /etc/pam.d with the following content:
         --
         #%PAM-1.0
         auth required pam_ldap.so debug
         --
 
         Set proper values in /etc/openldap/ldap.conf, e.g.:
         --
         host 10.0.0.1
         base o=organisation,c=com
         ssl on
         pam_password nds
         --

       * Using nds to authenticate against the local password file:
         file /etc/pam.d/nds should contain: 
         --
         #%PAM-1.0
         auth requisite pam_unix2.so
         --

         NOTICE: if you want to authenticate against your local database 
                 using pam_unix2.so, your program needs read access for 
                 /etc/shadow. This requires the nds program to run setuid 
                 root (s-rwsr-sr-x)!
 
                 # chown root.nobody nds
                 # chmod +s nds 


       USAGE

       - this example forces an identity and command.

         The system adminstrator should add  a line like this in the users 
         $HOME/.ssh/authorized_keys file:
         --
         command="/usr/local/bin/nds --user test --exec 'ssh box@inside'",\
         no-port-forwarding,no-X11-forwarding,no-agent-forwarding \
         ssh-dss AAAAB3NzaC1kc3 ...
         --
         Note that our example contains line continuation marks, which
         should not be copied over in the actual authorized_keys file.
         Also note that the ssh-dss key is only partially shown and that
         you should provide the proper path to the command.  
              
         When the user connects with the matching private key the command
         'nds' will be executed, which will try to authenticate the user 
         using the user credentials of 'test' and if successful will 
         execute the command 'ssh box@inside'. 


         $ nds

         This will start up the PAM subsystem to authenticate the
         current user. If the user was properly authenticated, the
         string "Authenticated" will be printed else the string
         "Not Authenticated" will be printed.


         $ nds --user jones --exec 'ls -l'

         This will start up the PAM subsystem to authenticate the
         current user, but will use the id 'jones' to authenticate 
         against. If the user was properly authenticated, a long
         listing will be displayed.

-----------------------------------------------------------------------------
Compiling:

   just type 'make'.

Installation:

   copy over the nds binary to your favourite directory
   create the proper /etc/pam.d/nds PAM configuration file, see
   the examples above.


