package ch.odi.pam;
   
   
   /**
    * Java native interface to PAM.
    * Loads the native libjaaspam.so.
    *  
    * @author Ortwin Gl?ck
    */
  public class Pam {
      // keeps the pam handle returned by libpam.so    
      private long pam_handle = 0L;
      private PamCallback callback;
      
      static {
          System.loadLibrary("jaas-pam");
      }
      
      /**
       * 
       * @param serviceName The service name corresponding to a PAM service in /etc/pam.d
       * @param user The username or <code>null</code>.
       * @param callback The callback that will get messages from PAM during authenticate.
       */
      public Pam(String serviceName, String user, PamCallback callback) {
          this.callback = callback;
          // exactly one thread is allowed to call pam_start() of libpam.so
          synchronized (Pam.class) {
              int code = pam_start(serviceName, user);
              if (code != PamConstants.PAM_SUCCESS) throw new PamError("PAM error code: "+ code);
          }
      }
  
      /**
       * Frees all resources associated with this objects. Calling methods on this
       * object after a call to end() will lead to undefined results!
       */
      public void end() {
          // exactly one thread is allowed to call pam_end() of libpam.so
          synchronized (Pam.class) {
              if (pam_handle != 0L) {
                  pam_end(pam_handle);
                  pam_handle = 0L;
              }
          }
      }
      
      protected void finalize() throws Throwable {
          end();
      }
  
      /**
       * This function is used to obtain the value of the indicated item_type. Upon success returns
       * the value of the corresponding item. 
       *
       * @param item_type see setStringItem
       * @return The item or <code>null</code> on error
       */
      public String getItem(int item_type) {
          return pam_get_str_item(pam_handle, item_type);
      }
      
      /**
       * This function is used to (re)set the value of an item.
       * 
       * @param item_type
       * PAM_SERVICE
       *  The service name (which identifies that PAM stack that libpam will use to authenticate the 
       *  program).
       *
       * PAM_USER
       *  The username of the entity under who's identity service will be given. That is, following
       *  authentication, PAM_USER identifies the local entity that gets to use the service. 
       *  Note, this value can be mapped from something (eg., "anonymous") to something else
       *  (eg. "guest119") by any module in the PAM stack. As such an application should consult
       *  the value of PAM_USER after each call to a pam_*() function.
       *
       * PAM_USER_PROMPT
       *  The string used when prompting for a user's name. The default value for this string 
       *  is "Please enter username: ".
       *
       * PAM_TTY
       *  The terminal name: prefixed by /dev/ if it is a device file; for graphical, X-based, 
       *  applications the value for this item should be the $DISPLAY variable.
       *
       * PAM_RUSER
       *  The requesting entity: user's username for a locally requesting user or a remote requesting
       *  user - generally an application or module will attempt to supply the value that is most
       *  strongly authenticated (a local account before a remote one. The level of trust in this
       *  value is embodied in the actual authentication stack associated with the application, so
       *  it is ultimately at the discretion of the system administrator. It should generally match
       *  the current PAM_RHOST value. That is, "PAM_RUSER@PAM_RHOST" should always identify the
       *  requesting user. In some cases, PAM_RUSER may be NULL. In such situations, it is unclear
       *  who the requesting entity is.
       *
       * PAM_RHOST
       *  The requesting hostname (the hostname of the machine from which the PAM_RUSER entity is
       *  requesting service). That is "PAM_RUSER@PAM_RHOST" does identify the requesting user.
       *  "luser@localhost" or "evil@evilcom.com" are valid "PAM_RUSER@PAM_RHOST" examples. 
      *  In some applications, PAM_RHOST may be NULL. In such situations, it is unclear where the
      *  authentication request is originating from.
      * @param item the value to set
      * @return
      * A successful call to this function returns PAM_SUCCESS. However, the application should
      * expect at least one the following errors:
      *
      * PAM_SYSTEM_ERR
      *  The pam_handle_t passed as a first argument to this function was invalid.
      *  
      * PAM_PERM_DENIED
      *  An attempt was made to replace the conversation structure with a NULL value.
      *  
      * PAM_BUF_ERR
      *  The function ran out of memory making a copy of the item.
      *  
      * PAM_BAD_ITEM
      *  The application attempted to set an undefined or inaccessible item. 
      */
     public int setItem(int item_type, String item) {
         return pam_set_str_item(pam_handle, item_type, item);
     }
     
     /**
      * This function serves as an interface to the authentication mechanisms of the loaded modules.
      * 
      * @param flags The single optional flag, which may be logically OR'd with PAM_SILENT, 
      * takes the following value, PAM_DISALLOW_NULL_AUTHTOK.
      * @return The value returned by this function is one of the following:
      * PAM_SUCCESS
      *  The user was authenticated 
      * 
      * PAM_AUTH_ERR
      *  The user was not authenticated
      *  
      * PAM_CRED_INSUFFICIENT
      *  For some reason the application does not have sufficient credentials to authenticate the user.
      *  
      * PAM_AUTHINFO_UNAVAIL
      *  The modules were not able to access the authentication information. This might be due to a 
      *  network or hardware failure etc.
      *  
      * PAM_USER_UNKNOWN
      *  The supplied username is not known to the authentication service
      *  
      * PAM_MAXTRIES
      *  One or more of the authentication modules has reached its limit of tries authenticating
      *  the user. Do not try again.
      *
      * If one or more of the authentication modules fails to load, for whatever reason, this 
      * function will return PAM_ABORT. 
      */
     public int authenticate(int flags) {
         /*
          * The authenticate method isn't synchronized because it blocks
          * all other threads on PAM_FAIL_DELAY function (about 2 seconds).
          * Take care that the pam auth modules are thread-safe.
          * e.g.
          * pam_unix.so alias pam_unix_auth.so can make trouble
          * if old password encryption is used.
          * 
          * <pre>
          * # SIGSEGV (0xb) at pc=0x400e8423, pid=24690, tid=12697890
          * C [libc.so.6+0x67423] strlen+0x33
          * C [pam_unix_auth.so+0x572d] _unix_verify_password+0x1dd
          * </pre>
          */
         return pam_authenticate(pam_handle, flags);
     }
     
     /**
      * The same as calling authencicate(0).
      * 
      * @return
      */
     public int authenticate() {
         return authenticate(0);
     }
     
     /**
      * This function is typically called after the user has been authenticated. It establishes
      * whether the user's account is healthy. That is to say, whether the user's account is still
      * active and whether the user is permitted to gain access to the system at this time. 
      * @param flags Valid flags, any one of which, may be logically OR'd with PAM_SILENT, and are 
      * the same as those applicable to the flags argument of authenticate.
      * @return The normal response from this function is PAM_SUCCESS, however, specific failures are
      * indicated by the following error returns:
      * PAM_AUTHTOK_EXPIRED
      *  The user is valid but their authentication token has expired. The correct response to this
      *  return-value is to require that the user satisfies the pam_chauthtok() function before
      *  obtaining service. It may not be possible for some applications to do this. In such cases,
      *  the user should be denied access until such time as they can update their password.
      *
      * PAM_ACCT_EXPIRED
      *  The user is no longer permitted to access the system.
      *  
      * PAM_AUTH_ERR
      *  There was an authentication error.
      *
      * PAM_PERM_DENIED
      *  The user is not permitted to gain access at this time.
      *  
      * PAM_USER_UNKNOWN
      *  The user is not known to a module's account management component.
      */
     public int accountManagement(int flags) {
         return pam_acct_mgmt(pam_handle, flags);
     }
     
     /**
      * The same as calling accountManagement(0).
      * @return
      */
     public int accountManagement() {
         return accountManagement(0);
     }
     
     /**
      * This function is used to set the module-specific credentials of the user. It is usually 
      * called after the user has been authenticated, after the account management function has 
      * been called but before a session has been opened for the user.
      * 
      * A credential is something that the user possesses. It is some property, such as a 
      * Kerberos ticket, or a supplementary group membership that make up the uniqueness of a 
      * given user. On a Linux (or UN*X system) the user's UID and GID's are credentials too. 
      * However, it has been decided that these properties (along with the default supplementary 
      * groups of which the user is a member) are credentials that should be set directly by the 
      * application and not by PAM.
      * 
      * This function simply calls the pam_sm_setcred functions of each of the loaded modules. 
      * @param flags Valid flags, any one of which, may be logically OR'd with PAM_SILENT, are:
      * PAM_ESTABLISH_CRED
      *  Set the credentials for the authentication service,
      *  
      * PAM_DELETE_CRED
      *  Delete the credentials associated with the authentication service,
      *  
      * PAM_REINITIALIZE_CRED
      * Reinitialize the user credentials, and
      *  
      * PAM_REFRESH_CRED
      *  Extend the lifetime of the user credentials. 
      *
      * @return A successful return is signalled with PAM_SUCCESS. Errors that are especially 
      * relevant to this function are the following:
      *
      * PAM_CRED_UNAVAIL
      *  A module cannot retrieve the user's credentials.
      *  
      * PAM_CRED_EXPIRED
      *  The user's credentials have expired.
      *  
      * PAM_USER_UNKNOWN
      *  The user is not known to an authentication module.
      *  
      * PAM_CRED_ERR
      *  A module was unable to set the credentials of the user. 
      */
     public int setCredentials(int flags) {
         return pam_setcred(pam_handle, flags);
     }
     
     /**
      * This function is used to change the authentication token for a given user (as indicated by
      * the state of this object). 
      *
      * @param flags The following is a valid but optional flag which may be logically
      * OR'd with PAM_SILENT,
      *
      * PAM_CHANGE_EXPIRED_AUTHTOK
      *  This argument indicates to the modules that the users authentication token (password)
      *  should only be changed if it has expired. 
      *  Note, if this argument is not passed, the application requires that all authentication 
      *  tokens are to be changed.
      * @return PAM_SUCCESS is the only successful return value, valid error-returns are:
      *
      * PAM_AUTHTOK_ERR
      *  A module was unable to obtain the new authentication token.
      *
      * PAM_AUTHTOK_RECOVERY_ERR
      *  A module was unable to obtain the old authentication token.
      *
      * PAM_AUTHTOK_LOCK_BUSY
      *  One or more of the modules was unable to change the authentication token since it is currently locked.
      *
      * PAM_AUTHTOK_DISABLE_AGING
      *  Authentication token aging has been disabled for at least one of the modules.
      *
      * PAM_PERM_DENIED
      *  Permission denied.
      *
      * PAM_TRY_AGAIN
      *  Not all of the modules were in a position to update the authentication token(s). In such a case none of the user's authentication tokens are updated.
      *
      * PAM_USER_UNKNOWN
      *  The user is not known to the authentication token changing service. 
      */
     public int changeAuthToken(int flags) {
         return pam_chauthtok(pam_handle, flags);
     }
     
     /**
      * This function is used to indicate that an authenticated session has begun. It is used to 
      * inform the modules that the user is currently in a session. It should be possible for the 
      * Linux-PAM library to open a session and close the same session (see section below) from 
      * different applications.
      *
      * Currently, this function simply calls each of the corresponding functions of the loaded 
      * modules. 
      * 
      * @param flags The only valid flag is PAM_SILENT and this is, of course, optional.
      * @return If any of the required loaded modules are unable to open a session for the user, 
      * this function will return PAM_SESSION_ERR.
      */
     public int openSession(int flags) {
         return pam_open_session(pam_handle, flags);
     }
     
     /**
      * This function is used to indicate that an authenticated session has ended. It is used to 
      * inform the modules that the user is exiting a session. It should be possible for the 
      * Linux-PAM library to open a session and close the same session from different applications.
      * 
      * This function simply calls each of the corresponding functions of the loaded modules in the
      * same order that they were invoked with openSession. 
      * 
      * @param flags The only valid flag is PAM_SILENT and this is, of course, optional.
      * @return If any of the required loaded modules are unable to close a session for the user, 
      * this function will return PAM_SESSION_ERR.
      */
     public int closeSession(int flags) {
         return pam_close_session(pam_handle, flags);
     }
     
     public String getError(int errorCode) {
         return pam_strerror(pam_handle, errorCode);
     }
     
     // Called back by the native library
     private int conversation(PamMessage[] messages, PamResponse[] responses) {
         try {
             int ret = callback.handle(messages, responses);
             return ret;
         } catch (Throwable th) {
             // do not propagate exceptions back to native code, but use a nice
             // return code
             th.printStackTrace();
             return PamConstants.PAM_CONV_ERR;
         }
     }
      
     // native interface
     private native int pam_start(String serviceName, String user);
     private native void pam_end(long handle);
     private native String pam_get_str_item(long handle, int item);
     private native int pam_set_str_item(long handle, int item, String value);
     private native int pam_authenticate(long handle, int flags);
     private native String pam_strerror(long handle, int errnum);
     private native int pam_acct_mgmt(long handle, int flags);
     private native int pam_setcred(long handle, int flags);
     private native int pam_chauthtok(long handle, int flags);
     private native int pam_open_session(long handle, int flags);
     private native int pam_close_session(long handle, int flags);
 }