sbuild  1.6.10
Public Types | Public Member Functions | Static Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
sbuild::auth Class Referenceabstract

Authentication handler. More...

#include <sbuild-auth.h>

+ Inheritance diagram for sbuild::auth:
+ Collaboration diagram for sbuild::auth:

Public Types

enum  status { STATUS_NONE, STATUS_USER, STATUS_FAIL }
 Authentication status. More...
 
enum  error_code {
  HOSTNAME, USER, GROUP, AUTHENTICATION,
  AUTHORISATION, PAM_DOUBLE_INIT, PAM, PAM_END
}
 Error codes. More...
 
typedef custom_error< error_codeerror
 Exception type.
 
typedef std::shared_ptr< authptr
 A shared_ptr to a auth object.
 

Public Member Functions

virtual ~auth ()
 The destructor.
 
std::string const & get_service () const
 Get the PAM service name. More...
 
uid_t get_uid () const
 Get the uid of the user. More...
 
gid_t get_gid () const
 Get the gid of the user. More...
 
std::string const & get_user () const
 Get the name of the user. More...
 
void set_user (uid_t uid)
 Set the name of the user. More...
 
void set_user (std::string const &user)
 Set the name of the user. More...
 
string_list const & get_command () const
 Get the command to run in the session. More...
 
void set_command (string_list const &command)
 Set the command to run in the session. More...
 
std::string const & get_home () const
 Get the home directory. More...
 
std::string const & get_wd () const
 Get the working directory. More...
 
void set_wd (std::string const &wd)
 Set the working directory. More...
 
std::string const & get_shell () const
 Get the name of the shell. More...
 
environment const & get_user_environment () const
 Get the user environment to use in the session. More...
 
void set_user_environment (char **environment)
 Set the user environment to use in the session. More...
 
void set_user_environment (environment const &environment)
 Set the user environment to use in the session. More...
 
environment get_minimal_environment () const
 Get the minimal environment. More...
 
environment get_complete_environment () const
 Get the complete environment. More...
 
virtual environment get_auth_environment () const =0
 Get the PAM environment. More...
 
uid_t get_ruid () const
 Get the "remote uid" of the user. More...
 
gid_t get_rgid () const
 Get the "remote gid" of the user. More...
 
std::string const & get_ruser () const
 Get the "remote" name of the user. More...
 
void set_ruser (uid_t ruid)
 Set the "remote" name of the user. More...
 
void set_ruser (std::string const &ruser)
 Set the "remote" name of the user. More...
 
std::string const & get_rgroup () const
 Get the "remote" name of the group. More...
 
virtual void start ()
 Start the PAM system. More...
 
virtual void stop ()
 Stop the PAM system. More...
 
virtual void authenticate (status auth_status)
 Perform PAM authentication. More...
 
virtual void setupenv ()
 Import the user environment into PAM. More...
 
virtual void account ()
 Do PAM account management (authorisation). More...
 
virtual void cred_establish ()
 Use PAM to establish credentials. More...
 
virtual void cred_delete ()
 Use PAM to delete credentials. More...
 
virtual void open_session ()
 Open a PAM session. More...
 
virtual void close_session ()
 Close a PAM session. More...
 
virtual bool is_initialised () const =0
 Check if PAM is initialised (i.e. More...
 

Static Public Member Functions

static status change_auth (status oldauth, status newauth)
 Set new authentication status. More...
 

Protected Member Functions

 auth (std::string const &service_name)
 The constructor. More...
 
void set_user (passwd const &pwent)
 Set the name of the user. More...
 
void set_ruser (passwd const &rpwent)
 Set the "remote" name of the user. More...
 

Protected 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.
 

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.

A conversation handler must be specified using set_conv before calling any of the functions below.

The correct order is

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

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.

PAM_END 

PAM failed to shut down cleanly.

Authentication status.

Enumerator
STATUS_NONE 

Authentication is not required.

STATUS_USER 

Authentication is required by the user.

STATUS_FAIL 

Authentication has failed.

Constructor & Destructor Documentation

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

The constructor.

Parameters
service_namethe 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 ruid, ruser, set_ruser(), and set_user().

Member Function Documentation

void auth::account ( )
virtual

Do PAM account management (authorisation).

An error will be thrown on failure.

Reimplemented in sbuild::auth_pam.

void auth::authenticate ( status  auth_status)
virtual

Perform PAM authentication.

If auth_status is set to AUTH_USER, the user will be prompted to authenticate themselves. If auth_status is AUTH_NONE, no authentication is required, and if AUTH_FAIL, authentication will fail.

An error will be thrown on failure.

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

Reimplemented in sbuild::auth_pam, and sbuild::auth_null.

static status sbuild::auth::change_auth ( status  oldauth,
status  newauth 
)
inlinestatic

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
oldauththe current authentication status.
newauththe new authentication status.
Returns
the new authentication status.

References is_initialised().

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

+ Here is the caller graph for this function:

void auth::close_session ( )
virtual

Close a PAM session.

An error will be thrown on failure.

Reimplemented in sbuild::auth_pam.

void auth::cred_delete ( )
virtual

Use PAM to delete credentials.

An error will be thrown on failure.

Reimplemented in sbuild::auth_pam.

void auth::cred_establish ( )
virtual

Use PAM to establish credentials.

An error will be thrown on failure.

Reimplemented in sbuild::auth_pam.

virtual environment sbuild::auth::get_auth_environment ( ) const
pure virtual

Get the PAM environment.

This is the environment as set by PAM modules.

Returns
an environment list.

Implemented in sbuild::auth_null, and sbuild::auth_pam.

Referenced by get_complete_environment().

+ Here is the caller graph for this function:

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.

environment auth::get_complete_environment ( ) const

Get the complete environment.

This is the user environment plus essential environment variables which are set if not already present.

Returns
an environment list.

References get_auth_environment(), get_minimal_environment(), get_user_environment(), sbuild::environment::remove(), uid, and user.

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.

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.

environment auth::get_minimal_environment ( ) const

Get the minimal environment.

This is essential environment variables which are set if not already present.

Returns
an environment list.

References sbuild::environment::add(), home, shell, uid, and user.

Referenced by sbuild::auth_null::get_auth_environment(), get_complete_environment(), and sbuild::auth_pam::setupenv().

+ Here is the caller graph for this function:

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.

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.

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.

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.

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).

References 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.

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.

environment const & auth::get_user_environment ( ) const

Get the user environment to use in the session.

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

References user_environment.

Referenced by get_complete_environment().

+ Here is the caller graph for this function:

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.

virtual bool sbuild::auth::is_initialised ( ) const
pure virtual

Check if PAM is initialised (i.e.

start has been called).

Returns
true if initialised, otherwise false.

Implemented in sbuild::auth_pam, and sbuild::auth_null.

Referenced by change_auth().

+ Here is the caller graph for this function:

void auth::open_session ( )
virtual

Open a PAM session.

An error will be thrown on failure.

Reimplemented in sbuild::auth_pam.

void auth::set_command ( string_list const &  command)

Set the command to run in the session.

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

References command.

void auth::set_ruser ( uid_t  ruid)

Set the "remote" name of the user.

This is the user which is requesting authentication.

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
ruidremote user to set as a uid.

References USER.

Referenced by auth(), and set_ruser().

+ Here is the caller graph for this function:

void auth::set_ruser ( std::string const &  ruser)

Set the "remote" name of the user.

This is the user which is requesting authentication.

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
ruserthe remote user name to set.

References set_ruser(), and USER.

void auth::set_ruser ( passwd const &  rpwent)
protected

Set the "remote" name of the user.

This is the user which is requesting authentication.

As a side effect, the ruid, rgid, ruser and rgroup member variables will also be set, so calling the corresponding get methods will now return meaningful values.

Parameters
rpwentremote user to set as a passwd entry.

References sbuild::DEBUG_INFO, GROUP, sbuild::log_debug(), rgid, rgroup, ruid, and ruser.

void auth::set_user ( uid_t  uid)

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
uiduser to set as a uid.

References USER.

Referenced by auth(), and set_user().

+ Here is the caller graph for this function:

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
userthe name to set.

References set_user(), and USER.

void auth::set_user ( passwd const &  pwent)
protected

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
pwentuser to set as a passwd entry.

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

void auth::set_user_environment ( char **  environment)

Set the user environment to use in the session.

Parameters
environmentan environ- or envp-like string vector containing key=value pairs.
void auth::set_user_environment ( environment const &  environment)

Set the user environment to use in the session.

Parameters
environmentan environment list.

References user_environment.

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

Set the working directory.

This is the working directory to set in the session.

Parameters
wdthe current working directory.

References wd.

void auth::setupenv ( )
virtual

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.

Reimplemented in sbuild::auth_pam.

void auth::start ( )
virtual

Start the PAM system.

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

An error will be thrown on failure.

Reimplemented in sbuild::auth_pam, and sbuild::auth_null.

void auth::stop ( )
virtual

Stop the PAM system.

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

An error will be thrown on failure.

Reimplemented in sbuild::auth_pam, and sbuild::auth_null.

Referenced by ~auth().

+ Here is the caller graph for this function:


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