- Main Page
- Namespaces
- Classes
- Files
- Directories
- Related Pages

- Class List
- Class Hierarchy
- Class Members

# sbuild::auth Class Reference

Authentication handler. More...

`#include <sbuild-auth.h>`

Inheritance diagram for sbuild::auth:

[legend]
Collaboration diagram for sbuild::auth:

[legend]
List of all members.

## Public Types
typedef custom_error< error_code > | error
| Exception type.
typedef std::tr1::shared_ptr< auth_conv > | conv_ptr
| A shared_ptr to an auth_conv object.
| STATUS_NONE
| Authentication is not required.
| STATUS_USER
| Authentication is required by the user.
| STATUS_FAIL
| Authentication has failed.
| VERBOSITY_QUIET
| Only print essential messages.
| VERBOSITY_NORMAL
| Print messages (the default).
| VERBOSITY_VERBOSE
| Print all messages.
| HOSTNAME
| Failed to get hostname.
| USER
| User not found.
| AUTHENTICATION
| Authentication failed.
| AUTHORISATION
| Authorisation failed.
| PAM_DOUBLE_INIT
| PAM was already initialised.
| PAM
| PAM error.
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, AUTHENTICATION, AUTHORISATION, PAM_DOUBLE_INIT, PAM }
| Error codes. More...
## 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.
std::string const & | get_ruser () const
| Get the "remote" name of the user.
verbosity | get_verbosity () const
| Get the message verbosity.
void | set_verbosity (verbosity verbosity)
| Set the message verbosity.
conv_ptr & | get_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.
std::string | ruser
| The user 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

- start
- authenticate
- setupenv
- account
- cred_establish
- open_session

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

- close_session
- cred_delete
- stop

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.

typedef custom_error<error_code> sbuild::auth::error

Exception type.

Reimplemented in sbuild::session.

## Member Enumeration Documentation

enum sbuild::auth::error_code

Error codes.

Enumerator:

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

Reimplemented in sbuild::session.

enum sbuild::auth::status

Authentication status.

Enumerator:

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

enum sbuild::auth::verbosity

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.

auth::~auth | ( |  | ) | `[virtual]`

The destructor.

## Member Function Documentation

void auth::account | ( |  | ) |

Do PAM account management (authorisation).

An error will be thrown on failure.

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.

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.

void auth::close_session | ( |  | ) |

Close a PAM session.

An error will be thrown on failure.

void auth::cred_delete | ( |  | ) |

Use PAM to delete credentials.

An error will be thrown on failure.

void auth::cred_establish | ( |  | ) |

Use PAM to establish credentials.

An error will be thrown on failure.

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

Check if authentication is required.

This default implementation always requires authentication.

Reimplemented in sbuild::session.

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.

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

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.

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.

environment auth::get_pam_environment | ( |  | ) | const

Get the PAM environment.

This is the environment as set by PAM modules.

Returns:
  an environment list.

uid_t auth::get_ruid | ( |  | ) | const

Get the "remote uid" of the user.

This is the uid which is requesting authentication.

Returns:
  a uid.

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.

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

Get the PAM service name.

Returns:
  the service name.

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.

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.

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.

auth::verbosity auth::get_verbosity | ( |  | ) | const

Get the message verbosity.

Returns the verbosity level.

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.

void auth::open_session | ( |  | ) |

Open a PAM session.

An error will be thrown on failure.

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.

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.

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, and dchroot::session_base.

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.

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.

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

Set the message verbosity.

Parameters:

  | verbosity | the verbosity level.

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

Set the working directory.

This is the working directory to set in the session.

Parameters:

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

Todo:
  Support custom filtering of the environment, rather than hardcoding. Use regular expressions. Also add additional per-chroot environment filtering, and an "environment-filter" option in the config file.

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.

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.

## Member Data Documentation

string_list sbuild::auth::command`[private]`

The command to run.

conv_ptr sbuild::auth::conv`[private]`

The PAM conversation handler.

gid_t sbuild::auth::gid`[private]`

The gid to run as.

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

The home directory.

verbosity sbuild::auth::message_verbosity`[private]`

The message verbosity.

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

The PAM handle.

uid_t sbuild::auth::ruid`[private]`

The uid requesting authentication.

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

The user name requesting authentication.

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

The PAM service name.

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

The user shell to run.

uid_t sbuild::auth::uid`[private]`

The uid to run as.

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

The user name to run as.

environment sbuild::auth::user_environment`[private]`

The user environment to set.

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

The directory to run in.

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

- sbuild/sbuild-auth.h
- sbuild/sbuild-auth.cc