sbuild::auth Class Reference

Authentication handler. More...

#include <sbuild-auth.h>

Inheritance diagram for sbuild::auth:

Inheritance graph
[legend]
Collaboration diagram for sbuild::auth:

Collaboration graph
[legend]

List of all members.

Public Types

enum  status { STATUS_NONE, STATUS_USER, STATUS_FAIL }
 Authentication status. More...
enum  verbosity { VERBOSITY_QUIET, VERBOSITY_NORMAL, VERBOSITY_VERBOSE }
 Message verbosity. More...
enum  error_code {
  HOSTNAME, USER, GROUP, AUTHENTICATION,
  AUTHORISATION, PAM_DOUBLE_INIT, PAM
}
 Error codes. More...
typedef custom_error< error_codeerror
 Exception type.
typedef std::tr1::shared_ptr
< auth_conv
conv_ptr
 A shared_ptr to an auth_conv object.

Public Member Functions

 auth (std::string const &service_name)
 The constructor.
virtual ~auth ()
 The destructor.
std::string const & get_service () const
 Get the PAM service name.
uid_t get_uid () const
 Get the uid of the user.
gid_t get_gid () const
 Get the gid of the user.
std::string const & get_user () const
 Get the name of the user.
void set_user (std::string const &user)
 Set the name of the user.
string_list const & get_command () const
 Get the command to run in the session.
void set_command (string_list const &command)
 Set the command to run in the session.
std::string const & get_home () const
 Get the home directory.
std::string const & get_wd () const
 Get the working directory.
void set_wd (std::string const &wd)
 Set the working directory.
std::string const & get_shell () const
 Get the name of the shell.
environment const & get_environment () const
 Get the environment to use in the session.
void set_environment (char **environment)
 Set the environment to use in the session.
void set_environment (environment const &environment)
 Set the environment to use in the session.
environment get_pam_environment () const
 Get the PAM environment.
uid_t get_ruid () const
 Get the "remote uid" of the user.
gid_t get_rgid () const
 Get the "remote gid" of the user.
std::string const & get_ruser () const
 Get the "remote" name of the user.
std::string const & get_rgroup () const
 Get the "remote" name of the group.
verbosity get_verbosity () const
 Get the message verbosity.
void set_verbosity (verbosity verbosity)
 Set the message verbosity.
conv_ptrget_conv ()
 Get the conversation handler.
void set_conv (conv_ptr &conv)
 Set the conversation handler.
void run ()
 Run a session.
void start ()
 Start the PAM system.
void stop ()
 Stop the PAM system.
void authenticate ()
 Perform PAM authentication.
void setupenv ()
 Import the user environment into PAM.
void account ()
 Do PAM account management (authorisation).
void cred_establish ()
 Use PAM to establish credentials.
void cred_delete ()
 Use PAM to delete credentials.
void open_session ()
 Open a PAM session.
void close_session ()
 Close a PAM session.
status change_auth (status oldauth, status newauth) const
 Set new authentication status.

Protected Member Functions

virtual status get_auth_status () const
 Check if authentication is required.
virtual void run_impl ()=0
 Run session.
const char * pam_strerror (int pam_error)
 Get a description of a PAM error.

Protected Attributes

pam_handle_t * pam
 The PAM handle.

Private Attributes

const std::string service
 The PAM service name.
uid_t uid
 The uid to run as.
gid_t gid
 The gid to run as.
std::string user
 The user name to run as.
string_list command
 The command to run.
std::string home
 The home directory.
std::string wd
 The directory to run in.
std::string shell
 The user shell to run.
environment user_environment
 The user environment to set.
uid_t ruid
 The uid requesting authentication.
gid_t rgid
 The gid requesting authentication.
std::string ruser
 The user name requesting authentication.
std::string rgroup
 The group name requesting authentication.
conv_ptr conv
 The PAM conversation handler.
verbosity message_verbosity
 The message verbosity.


Detailed Description

Authentication handler.

auth handles user authentication, authorisation and session management using the Pluggable Authentication Modules (PAM) library. It is essentially an object-oriented wrapper around PAM.

In order to use PAM correctly, it is important to call several of the methods in the correct order. For example, it is not possible to authorise a user before authenticating a user, and a session may not be started before either of these have occurred.

The correct order is

After the session has finished, or if an error occurred, the corresponding cleanup methods should be called

The run method will handle all this. The run_impl virtual function should be used to provide a session handler to open and close the session for the user. open_session and close_session must still be called.


Member Typedef Documentation

typedef std::tr1::shared_ptr<auth_conv> sbuild::auth::conv_ptr

A shared_ptr to an auth_conv object.

Exception type.

Reimplemented in sbuild::session.


Member Enumeration Documentation

Error codes.

Enumerator:
HOSTNAME  Failed to get hostname.
USER  User not found.
GROUP  Group not found.
AUTHENTICATION  Authentication failed.
AUTHORISATION  Authorisation failed.
PAM_DOUBLE_INIT  PAM was already initialised.
PAM  PAM error.

Reimplemented in sbuild::session.

Authentication status.

Enumerator:
STATUS_NONE  Authentication is not required.
STATUS_USER  Authentication is required by the user.
STATUS_FAIL  Authentication has failed.

Message verbosity.

Enumerator:
VERBOSITY_QUIET  Only print essential messages.
VERBOSITY_NORMAL  Print messages (the default).
VERBOSITY_VERBOSE  Print all messages.


Constructor & Destructor Documentation

auth::auth ( std::string const &  service_name  ) 

The constructor.

Parameters:
service_name the PAM service name. This should be a hard-coded constant string literal for safety and security. This is passed to pam_start() when initialising PAM, and is used to load the correct configuration file from /etc/pam.d.

References GROUP, rgid, rgroup, ruid, ruser, set_user(), and USER.

auth::~auth (  )  [virtual]

The destructor.

References sbuild::log_exception_error(), and stop().


Member Function Documentation

void auth::account (  ) 

Do PAM account management (authorisation).

An error will be thrown on failure.

References sbuild::DEBUG_NOTICE, sbuild::DEBUG_WARNING, sbuild::log_debug(), PAM, pam, and pam_strerror().

Referenced by run().

void auth::authenticate (  ) 

Perform PAM authentication.

If required, the user will be prompted to authenticate themselves.

An error will be thrown on failure.

Todo:
Use sysconf(_SC_HOST_NAME_MAX) when libc in a stable release supports it.

References AUTHENTICATION, AUTHORISATION, sbuild::DEBUG_CRITICAL, sbuild::DEBUG_INFO, sbuild::DEBUG_NOTICE, sbuild::DEBUG_WARNING, get_auth_status(), HOSTNAME, sbuild::log_debug(), PAM, pam, pam_strerror(), ruser, service, STATUS_FAIL, STATUS_NONE, STATUS_USER, and user.

Referenced by run().

status sbuild::auth::change_auth ( status  oldauth,
status  newauth 
) const [inline]

Set new authentication status.

If newauth > oldauth, newauth is returned, otherwise oldauth is returned. This is to ensure the authentication status can never be decreased (relaxed).

Parameters:
oldauth the current authentication status.
newauth the new authentication status.
Returns:
the new authentication status.

Referenced by sbuild::session::get_auth_status(), get_auth_status(), and sbuild::session::get_chroot_auth_status().

void auth::close_session (  ) 

Close a PAM session.

An error will be thrown on failure.

References sbuild::DEBUG_NOTICE, sbuild::DEBUG_WARNING, sbuild::log_debug(), PAM, pam, and pam_strerror().

Referenced by sbuild::session::run_impl().

void auth::cred_delete (  ) 

Use PAM to delete credentials.

An error will be thrown on failure.

References sbuild::DEBUG_NOTICE, sbuild::DEBUG_WARNING, sbuild::log_debug(), PAM, pam, and pam_strerror().

Referenced by run().

void auth::cred_establish (  ) 

Use PAM to establish credentials.

An error will be thrown on failure.

References sbuild::DEBUG_NOTICE, sbuild::DEBUG_WARNING, sbuild::log_debug(), PAM, pam, and pam_strerror().

Referenced by run().

auth::status auth::get_auth_status (  )  const [protected, virtual]

Check if authentication is required.

This default implementation always requires authentication.

Reimplemented in sbuild::session.

References change_auth(), STATUS_NONE, and STATUS_USER.

Referenced by authenticate().

string_list const & auth::get_command (  )  const

Get the command to run in the session.

Returns:
the command as string list, each item being a separate argument. If no command has been specified, the list will be empty.

References command.

Referenced by sbuild::session::restore_termios(), sbuild::session::run_child(), and sbuild::session::save_termios().

auth::conv_ptr & auth::get_conv (  ) 

Get the conversation handler.

Returns:
a shared_ptr to the handler.

environment const & auth::get_environment (  )  const

Get the environment to use in the session.

Returns:
an environment list (a list of key-value pairs).

References user_environment.

Referenced by sbuild::session::get_login_command().

gid_t auth::get_gid (  )  const

Get the gid of the user.

This is the gid to run as in the session.

Returns:
a gid. This will be 0 if no user was set, or the user is gid 0.

References gid.

Referenced by sbuild::session::run_child().

std::string const & auth::get_home (  )  const

Get the home directory.

This is the $HOME to set in the session, if the user environment is not being preserved.

Returns:
the home directory.

References home.

Referenced by sbuild::session::get_login_directories().

environment auth::get_pam_environment (  )  const

Get the PAM environment.

This is the environment as set by PAM modules.

Returns:
an environment list.

References pam.

Referenced by sbuild::session::get_login_directories(), sbuild::session::get_user_command(), and sbuild::session::run_child().

gid_t auth::get_rgid (  )  const

Get the "remote gid" of the user.

This is the gid which is requesting authentication.

Returns:
a gid.

References rgid.

Referenced by sbuild::session::run_child().

std::string const & auth::get_rgroup (  )  const

Get the "remote" name of the group.

This is the group which is requesting authentication.

Returns:
a group name.

References rgroup.

Referenced by sbuild::session::run_child().

uid_t auth::get_ruid (  )  const

Get the "remote uid" of the user.

This is the uid which is requesting authentication.

Returns:
a uid.

References ruid.

Referenced by sbuild::session::get_chroot_auth_status(), sbuild::session::get_login_command(), sbuild::session::get_user_command(), and sbuild::session::run_child().

std::string const & auth::get_ruser (  )  const

Get the "remote" name of the user.

This is the user which is requesting authentication.

Returns:
a user name.

References ruser.

Referenced by sbuild::session::get_chroot_auth_status(), sbuild::session::get_login_command(), sbuild::session::get_user_command(), and sbuild::session::run_child().

std::string const & auth::get_service (  )  const

Get the PAM service name.

Returns:
the service name.

References service.

std::string const & auth::get_shell (  )  const

Get the name of the shell.

This is the shell to run in the session.

Returns:
the shell. This is typically a full pathname, though the executable name only should also work (the caller will have to search for it).

Reimplemented in sbuild::session.

References shell.

Referenced by sbuild::session::get_shell().

uid_t auth::get_uid (  )  const

Get the uid of the user.

This is the uid to run as in the * session.

Returns:
a uid. This will be 0 if no user was set, or the user is uid 0.

References uid.

Referenced by sbuild::session::get_chroot_auth_status(), sbuild::session::get_login_command(), sbuild::session::get_user_command(), and sbuild::session::run_child().

std::string const & auth::get_user (  )  const

Get the name of the user.

This is the user to run as in the session.

Returns:
the user's name.

References user.

Referenced by sbuild::session::get_login_command(), sbuild::session::get_user_command(), sbuild::session::run_child(), and sbuild::session::setup_chroot().

auth::verbosity auth::get_verbosity (  )  const

Get the message verbosity.

Returns the verbosity level.

References message_verbosity.

Referenced by sbuild::session::get_login_command(), sbuild::session::get_user_command(), and sbuild::session::setup_chroot().

std::string const & auth::get_wd (  )  const

Get the working directory.

This is the working directory to set in the session.

Returns:
the current working directory.

References wd.

Referenced by sbuild::session::get_command_directories(), and sbuild::session::get_login_directories().

void auth::open_session (  ) 

Open a PAM session.

An error will be thrown on failure.

References sbuild::DEBUG_NOTICE, sbuild::DEBUG_WARNING, sbuild::log_debug(), PAM, pam, and pam_strerror().

Referenced by sbuild::session::run_impl().

const char * auth::pam_strerror ( int  pam_error  )  [protected]

Get a description of a PAM error.

Parameters:
pam_error the PAM error number.
Returns:
the description.

References pam.

Referenced by account(), authenticate(), close_session(), cred_delete(), cred_establish(), open_session(), setupenv(), start(), and stop().

void auth::run (  ) 

Run a session.

The user will be asked for authentication if required, and then the run_impl virtual method will be called.

An error will be thrown on failure.

References account(), authenticate(), cred_delete(), cred_establish(), sbuild::DEBUG_INFO, sbuild::log_debug(), pam, run_impl(), setupenv(), start(), and stop().

virtual void sbuild::auth::run_impl (  )  [protected, pure virtual]

Run session.

The code to run when authentication and authorisation have been completed.

Implemented in sbuild::session.

Referenced by run().

void auth::set_command ( string_list const &  command  ) 

Set the command to run in the session.

Parameters:
command the command to run. This is a string list, each item being a separate argument.

void auth::set_conv ( conv_ptr conv  ) 

Set the conversation handler.

Parameters:
conv a shared_ptr to the handler.

void auth::set_environment ( environment const &  environment  ) 

Set the environment to use in the session.

Parameters:
environment an environment list.

References user_environment.

void auth::set_environment ( char **  environment  ) 

Set the environment to use in the session.

Parameters:
environment an environ- or envp-like string vector containing key=value pairs.

void auth::set_user ( std::string const &  user  ) 

Set the name of the user.

This is the user to run as in the session.

As a side effect, the uid, gid, home and shell member variables will also be set, so calling the corresponding get methods will now return meaningful values.

Parameters:
user the name to set.

References sbuild::DEBUG_INFO, gid, home, sbuild::log_debug(), shell, uid, and USER.

Referenced by auth().

void auth::set_verbosity ( auth::verbosity  verbosity  ) 

Set the message verbosity.

Parameters:
verbosity the verbosity level.

References message_verbosity.

void auth::set_wd ( std::string const &  wd  ) 

Set the working directory.

This is the working directory to set in the session.

Parameters:
wd the current working directory.

void auth::setupenv (  ) 

Import the user environment into PAM.

If no environment was specified with set_environment, a minimal environment will be created containing HOME, LOGNAME, PATH, TERM and LOGNAME.

An error will be thrown on failure.

Note that the environment is not sanitised in any way. This is the responsibility of the user.

References sbuild::environment::add(), sbuild::DEBUG_INFO, sbuild::DEBUG_NOTICE, sbuild::DEBUG_WARNING, home, sbuild::log_debug(), PAM, pam, pam_strerror(), shell, uid, user, and user_environment.

Referenced by run().

void auth::start (  ) 

Start the PAM system.

No other PAM functions may be called before calling this function.

An error will be thrown on failure.

References sbuild::DEBUG_CRITICAL, sbuild::DEBUG_NOTICE, sbuild::DEBUG_WARNING, sbuild::log_debug(), PAM, pam, PAM_DOUBLE_INIT, pam_strerror(), service, and user.

Referenced by run().

void auth::stop (  ) 

Stop the PAM system.

No other PAM functions may be used after calling this function.

An error will be thrown on failure.

References sbuild::DEBUG_NOTICE, sbuild::DEBUG_WARNING, sbuild::log_debug(), PAM, pam, and pam_strerror().

Referenced by run(), and ~auth().


Member Data Documentation

The PAM conversation handler.

gid_t sbuild::auth::gid [private]

The gid to run as.

Referenced by get_gid(), and set_user().

std::string sbuild::auth::home [private]

The home directory.

Referenced by get_home(), sbuild::session::get_login_directories(), set_user(), and setupenv().

The message verbosity.

Referenced by get_verbosity(), and set_verbosity().

pam_handle_t* sbuild::auth::pam [protected]

gid_t sbuild::auth::rgid [private]

The gid requesting authentication.

Referenced by auth(), and get_rgid().

std::string sbuild::auth::rgroup [private]

The group name requesting authentication.

Referenced by auth(), and get_rgroup().

uid_t sbuild::auth::ruid [private]

The uid requesting authentication.

Referenced by auth(), and get_ruid().

std::string sbuild::auth::ruser [private]

The user name requesting authentication.

Referenced by auth(), authenticate(), and get_ruser().

const std::string sbuild::auth::service [private]

The PAM service name.

Referenced by authenticate(), get_service(), and start().

std::string sbuild::auth::shell [private]

uid_t sbuild::auth::uid [private]

The uid to run as.

Referenced by get_uid(), set_user(), and setupenv().

std::string sbuild::auth::user [private]

The user name to run as.

Referenced by authenticate(), get_user(), setupenv(), and start().

The user environment to set.

Referenced by get_environment(), set_environment(), and setupenv().

std::string sbuild::auth::wd [private]


The documentation for this class was generated from the following files:

Generated on Sun May 17 18:39:14 2009 for sbuild by  doxygen 1.5.9