SbuildAuth

SbuildAuth — authentication handler

Synopsis




            SbuildAuth;
SbuildAuthStatus (*SbuildAuthRequireAuthFunc)
                                            (SbuildAuth *auth);
gboolean    (*SbuildAuthSessionRunFunc)     (SbuildAuth *auth,
                                             GError **error);
            SbuildAuthClass;
enum        SbuildAuthStatus;
enum        SbuildAuthVerbosity;
enum        SbuildAuthError;
#define     SBUILD_AUTH_ERROR
SbuildAuth* sbuild_auth_new                 (void);
const gchar* sbuild_auth_get_service        (const SbuildAuth *restrict auth);
uid_t       sbuild_auth_get_uid             (const SbuildAuth *restrict auth);
gid_t       sbuild_auth_get_gid             (const SbuildAuth *restrict auth);
const char* sbuild_auth_get_user            (const SbuildAuth *restrict auth);
void        sbuild_auth_set_user            (SbuildAuth *auth,
                                             const char *user);
const char* sbuild_auth_get_home            (const SbuildAuth *restrict auth);
const char* sbuild_auth_get_shell           (const SbuildAuth *restrict auth);
char**      sbuild_auth_get_command         (const SbuildAuth *restrict auth);
void        sbuild_auth_set_command         (SbuildAuth *auth,
                                             char **command);
char**      sbuild_auth_get_environment     (const SbuildAuth *restrict auth);
void        sbuild_auth_set_environment     (SbuildAuth *auth,
                                             char **environment);
char**      sbuild_auth_get_pam_environment (const SbuildAuth *restrict auth);
uid_t       sbuild_auth_get_ruid            (const SbuildAuth *restrict auth);
const char* sbuild_auth_get_ruser           (const SbuildAuth *restrict auth);
SbuildAuthVerbosity sbuild_auth_get_verbosity
                                            (const SbuildAuth *restrict auth);
void        sbuild_auth_set_verbosity       (SbuildAuth *auth,
                                             SbuildAuthVerbosity verbosity);
SbuildAuthConv* sbuild_auth_get_conv        (const SbuildAuth *restrict auth);
void        sbuild_auth_set_conv            (SbuildAuth *auth,
                                             SbuildAuthConv *conv);
gboolean    sbuild_auth_start               (SbuildAuth *auth,
                                             GError **error);
gboolean    sbuild_auth_stop                (SbuildAuth *auth,
                                             GError **error);
gboolean    sbuild_auth_authenticate        (SbuildAuth *auth,
                                             GError **error);
gboolean    sbuild_auth_account             (SbuildAuth *auth,
                                             GError **error);
gboolean    sbuild_auth_cred_establish      (SbuildAuth *auth,
                                             GError **error);
gboolean    sbuild_auth_cred_delete         (SbuildAuth *auth,
                                             GError **error);
gboolean    sbuild_auth_open_session        (SbuildAuth *auth,
                                             GError **error);
gboolean    sbuild_auth_close_session       (SbuildAuth *auth,
                                             GError **error);
gboolean    sbuild_auth_setupenv            (SbuildAuth *auth,
                                             GError **error);
gboolean    sbuild_auth_run                 (SbuildAuth *auth,
                                             GError **error);

Object Hierarchy


  GObject
   +----SbuildAuth
         +----SbuildSession

Properties


  "command"              GStrv                 : Read / Write
  "conv"                 SbuildAuthConv        : Read / Write
  "environment"          GStrv                 : Read / Write
  "gid"                  gint                  : Read
  "home"                 gchararray            : Read
  "ruid"                 gint                  : Read
  "ruser"                gchararray            : Read
  "service"              gchararray            : Read / Write / Construct Only
  "shell"                gchararray            : Read
  "uid"                  gint                  : Read
  "user"                 gchararray            : Read / Write
  "verbosity"            SbuildAuthVerbosity   : Read / Write

Signal Prototypes


"require-auth"
            SbuildAuthStatususer_function      (SbuildAuth *sbuildauth,
                                            gpointer user_data);
"session-run"
            gboolean    user_function      (SbuildAuth *sbuildauth,
                                            SbuildErrorPointer *arg1,
                                            gpointer user_data);

Description

SbuildAuth handles user authentication, authorisation and session management using the Pluggable Authentication Modules (PAM) library. It is essentially a GObject 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 occured.

The correct order is - sbuild_auth_start - sbuild_auth_authenticate - sbuild_auth_setupenv - sbuild_auth_account - sbuild_auth_cred_establish - sbuild_auth_close_session

After the session has finished, or if an error occured, the corresponding cleanup methods should be called - sbuild_auth_close_session - sbuild - sbuild_auth_cred_delete - sbuild_auth_stop

The function sbuild_auth_run will handle all this. The session_run vfunc or "session-run" signal should be used to provide a session handler to open and close the session for the user. sbuild_auth_open_session and sbuild_auth_close_session must still be used.

Details

SbuildAuth

typedef struct _SbuildAuth SbuildAuth;

SbuildAuth object.


SbuildAuthRequireAuthFunc ()

SbuildAuthStatus (*SbuildAuthRequireAuthFunc)
                                            (SbuildAuth *auth);

The function prototype required for use with the require_auth virtual function.

auth : an SbuildAuth
Returns : An SbuildAuthStatus to indicate whether authentication is not required, required, or if it has already failed.

SbuildAuthSessionRunFunc ()

gboolean    (*SbuildAuthSessionRunFunc)     (SbuildAuth *auth,
                                             GError **error);

The function prototype required for use with the session_run virtual function.

auth : an SbuildAuth
error : a GError
Returns : TRUE to continue running session handlers, FALSE to abort on error (error must be set appropriately).

SbuildAuthClass

typedef struct {
  GObjectClass              parent;
  SbuildAuthRequireAuthFunc require_auth;
  SbuildAuthSessionRunFunc  session_run;
} SbuildAuthClass;

SbuildAuth class.

GObjectClass parent; the parent class
SbuildAuthRequireAuthFunc require_auth; vfunc to check if authentication is required
SbuildAuthSessionRunFunc session_run; vfunc to run a session

enum SbuildAuthStatus

typedef enum
{
  SBUILD_AUTH_STATUS_NONE,
  SBUILD_AUTH_STATUS_USER,
  SBUILD_AUTH_STATUS_FAIL
} SbuildAuthStatus;

The status of the authentication process.

SBUILD_AUTH_STATUS_NONE No authentication is required.
SBUILD_AUTH_STATUS_USER User authentication is required.
SBUILD_AUTH_STATUS_FAIL Authentication has failed.

enum SbuildAuthVerbosity

typedef enum
{
  SBUILD_AUTH_VERBOSITY_QUIET,
  SBUILD_AUTH_VERBOSITY_NORMAL,
  SBUILD_AUTH_VERBOSITY_VERBOSE
} SbuildAuthVerbosity;

The verbosity level of printed messages.

SBUILD_AUTH_VERBOSITY_QUIET Only print errors and warnings.
SBUILD_AUTH_VERBOSITY_NORMAL Print errors, warnings and important messages.
SBUILD_AUTH_VERBOSITY_VERBOSE Print everything.

enum SbuildAuthError

typedef enum
{
  SBUILD_AUTH_ERROR_PAM_STARTUP,
  SBUILD_AUTH_ERROR_PAM_SET_ITEM,
  SBUILD_AUTH_ERROR_HOSTNAME,
  SBUILD_AUTH_ERROR_PAM_AUTHENTICATE,
  SBUILD_AUTH_ERROR_PAM_PUTENV,
  SBUILD_AUTH_ERROR_PAM_ACCOUNT,
  SBUILD_AUTH_ERROR_PAM_CREDENTIALS,
  SBUILD_AUTH_ERROR_PAM_SESSION_OPEN,
  SBUILD_AUTH_ERROR_PAM_SESSION_CLOSE,
  SBUILD_AUTH_ERROR_PAM_DELETE_CREDENTIALS,
  SBUILD_AUTH_ERROR_PAM_SHUTDOWN,
} SbuildAuthError;

The errors which can occur while loading a configuration file.

SBUILD_AUTH_ERROR_PAM_STARTUP PAM startup failed.
SBUILD_AUTH_ERROR_PAM_SET_ITEM PAM failed to set a configuration item.
SBUILD_AUTH_ERROR_HOSTNAME The system hostname could not be resolved.
SBUILD_AUTH_ERROR_PAM_AUTHENTICATE PAM user authentication failed.
SBUILD_AUTH_ERROR_PAM_PUTENV PAM failed to set an environment variable.
SBUILD_AUTH_ERROR_PAM_ACCOUNT PAM user authorisation failed.
SBUILD_AUTH_ERROR_PAM_CREDENTIALS PAM failed to establish the user's credentials.
SBUILD_AUTH_ERROR_PAM_SESSION_OPEN PAM failed to open a session.
SBUILD_AUTH_ERROR_PAM_SESSION_CLOSE PAM failed to close a session.
SBUILD_AUTH_ERROR_PAM_DELETE_CREDENTIALS PAM failed to delete the user's credentials.
SBUILD_AUTH_ERROR_PAM_SHUTDOWN PAM shutdown failed.

SBUILD_AUTH_ERROR

#define SBUILD_AUTH_ERROR sbuild_auth_error_quark()

The error domain for sbuild authentication errors.


sbuild_auth_new ()

SbuildAuth* sbuild_auth_new                 (void);

Creates a new SbuildAuth.

Returns : the newly created SbuildAuth.

sbuild_auth_get_service ()

const gchar* sbuild_auth_get_service        (const SbuildAuth *restrict auth);

Get the PAM service name. This is passed to pam_start() when initialising PAM. It must be set during object construction, and MUST be a hard-coded (constant) string literal for security reasons.

auth : an SbuildAuth
Returns : a string. This string points to internally allocated storage and must not be freed, modified or stored.

sbuild_auth_get_uid ()

uid_t       sbuild_auth_get_uid             (const SbuildAuth *restrict auth);

Get the uid of the user. This is the uid to run as in the session.

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

sbuild_auth_get_gid ()

gid_t       sbuild_auth_get_gid             (const SbuildAuth *restrict auth);

Get the gid of the user. This is the gid to run as in the session.

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

sbuild_auth_get_user ()

const char* sbuild_auth_get_user            (const SbuildAuth *restrict auth);

Get the name of the user. This is the user to run as in the session.

auth : an SbuildAuth
Returns : a string. This string points to internally allocated storage and must not be freed, modified or stored.

sbuild_auth_set_user ()

void        sbuild_auth_set_user            (SbuildAuth *auth,
                                             const char *user);

Get 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" properties will also be set.

auth : an SbuildAuth.
user : the name to set.

sbuild_auth_get_home ()

const char* sbuild_auth_get_home            (const SbuildAuth *restrict auth);

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

auth : an SbuildAuth
Returns : a string. This string points to internally allocated storage and must not be freed, modified or stored.

sbuild_auth_get_shell ()

const char* sbuild_auth_get_shell           (const SbuildAuth *restrict auth);

Get the name of the shell. This is the shell to run as in the session.

auth : an SbuildAuth
Returns : a string. This string points to internally allocated storage and must not be freed, modified or stored.

sbuild_auth_get_command ()

char**      sbuild_auth_get_command         (const SbuildAuth *restrict auth);

Get the command to run in the session.

auth : an SbuildAuth
Returns : a string vector. This string vector points to internally allocated storage and must not be freed, modified or stored.

sbuild_auth_set_command ()

void        sbuild_auth_set_command         (SbuildAuth *auth,
                                             char **command);

Set the command to run in the session.

auth : an SbuildAuth.
command : the command to set.

sbuild_auth_get_environment ()

char**      sbuild_auth_get_environment     (const SbuildAuth *restrict auth);

Get the environment to use in auth.

auth : an SbuildAuth
Returns : a string vector. This string vector points to internally allocated storage and must not be freed, modified or stored.

sbuild_auth_set_environment ()

void        sbuild_auth_set_environment     (SbuildAuth *auth,
                                             char **environment);

Set the environment to use in auth.

auth : an SbuildAuth
environment : the environment to use

sbuild_auth_get_pam_environment ()

char**      sbuild_auth_get_pam_environment (const SbuildAuth *restrict auth);

Get the PAM environment from auth.

auth : an SbuildAuth
Returns : a string vector. This string vector points to internally allocated storage and must not be freed, modified or stored.

sbuild_auth_get_ruid ()

uid_t       sbuild_auth_get_ruid            (const SbuildAuth *restrict auth);

Get the "remote uid" of the user. This is the uid which is requesting authentication.

auth : an SbuildAuth
Returns : a uid.

sbuild_auth_get_ruser ()

const char* sbuild_auth_get_ruser           (const SbuildAuth *restrict auth);

Get the "remote" name of the user. This is the user which is requesting authentication.

auth : an SbuildAuth
Returns : a string. This string points to internally allocated storage and must not be freed, modified or stored.

sbuild_auth_get_verbosity ()

SbuildAuthVerbosity sbuild_auth_get_verbosity
                                            (const SbuildAuth *restrict auth);

Get the message verbosity of auth.

auth : an SbuildAuth
Returns : the SbuildAuthVerbosity verbosity level.

sbuild_auth_set_verbosity ()

void        sbuild_auth_set_verbosity       (SbuildAuth *auth,
                                             SbuildAuthVerbosity verbosity);

Set the message verbosity of auth.

auth : an SbuildAuth
verbosity : the verbosity level to use

sbuild_auth_get_conv ()

SbuildAuthConv* sbuild_auth_get_conv        (const SbuildAuth *restrict auth);

Get the conversation handler for auth.

auth : an SbuildAuth
Returns : the handler object.

sbuild_auth_set_conv ()

void        sbuild_auth_set_conv            (SbuildAuth *auth,
                                             SbuildAuthConv *conv);

Set the conversation handler for auth.

auth : an SbuildAuth
conv : the conversation handler to use

sbuild_auth_start ()

gboolean    sbuild_auth_start               (SbuildAuth *auth,
                                             GError **error);

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

auth : an SbuildAuth
error : a GError
Returns : TRUE on success, FALSE on failure (error will be set to indicate the cause of the failure).

sbuild_auth_stop ()

gboolean    sbuild_auth_stop                (SbuildAuth *auth,
                                             GError **error);

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

auth : an SbuildAuth
error : a GError
Returns : TRUE on success, FALSE on failure (error will be set to indicate the cause of the failure).

sbuild_auth_authenticate ()

gboolean    sbuild_auth_authenticate        (SbuildAuth *auth,
                                             GError **error);

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

auth : an SbuildAuth
error : a GError
Returns : TRUE on success, FALSE on failure (error will be set to indicate the cause of the failure).

sbuild_auth_account ()

gboolean    sbuild_auth_account             (SbuildAuth *auth,
                                             GError **error);

Do PAM account management (authorisation).

auth : an SbuildAuth
error : a GError
Returns : TRUE on success, FALSE on failure (error will be set to indicate the cause of the failure).

sbuild_auth_cred_establish ()

gboolean    sbuild_auth_cred_establish      (SbuildAuth *auth,
                                             GError **error);

Use PAM to establish credentials.

auth : an SbuildAuth
error : a GError
Returns : TRUE on success, FALSE on failure (error will be set to indicate the cause of the failure).

sbuild_auth_cred_delete ()

gboolean    sbuild_auth_cred_delete         (SbuildAuth *auth,
                                             GError **error);

Use PAM to delete credentials.

auth : an SbuildAuth
error : a GError
Returns : TRUE on success, FALSE on failure (error will be set to indicate the cause of the failure).

sbuild_auth_open_session ()

gboolean    sbuild_auth_open_session        (SbuildAuth *auth,
                                             GError **error);

Open a PAM session. This should be called in the child process.

auth : an SbuildAuth
error : a GError
Returns : TRUE on success, FALSE on failure (error will be set to indicate the cause of the failure).

sbuild_auth_close_session ()

gboolean    sbuild_auth_close_session       (SbuildAuth *auth,
                                             GError **error);

Close a PAM session.

auth : an SbuildAuth
error : a GError
Returns : TRUE on success, FALSE on failure (error will be set to indicate the cause of the failure).

sbuild_auth_setupenv ()

gboolean    sbuild_auth_setupenv            (SbuildAuth *auth,
                                             GError **error);

Import the user environment into PAM. If no environment was specified with sbuild_auth_set_environment, a minimal environment will be created containing HOME, LOGNAME, PATH, TERM and LOGNAME.

auth : an SbuildAuth
error : a GError
Returns : TRUE on success, FALSE on failure (error will be set to indicate the cause of the failure).

sbuild_auth_run ()

gboolean    sbuild_auth_run                 (SbuildAuth *auth,
                                             GError **error);

Run the authentication process.

The user may be required to authenticate themselves, depending upon the result of the require_auth vfunc (the "require-auth" signal), called by sbuild_auth_require_auth().

If authentication and authorisation succeed, the "session-run" signal will be emitted. Derived classes should override the session_run vfunc, or connect signal handlers.

auth : an SbuildAuth
error : a GError, or NULL to ignore errors
Returns : TRUE on success, FALSE on failure (error will be set to indicate the cause of the failure).

Properties

The "command" property

  "command"              GStrv                 : Read / Write

The command to run in the session, or NULL for a login shell.


The "conv" property

  "conv"                 SbuildAuthConv        : Read / Write

Conversation handler.


The "environment" property

  "environment"          GStrv                 : Read / Write

The user environment to set in the session.


The "gid" property

  "gid"                  gint                  : Read

The GID to run as in the session.

Allowed values: >= 0

Default value: 0


The "home" property

  "home"                 gchararray            : Read

The home directory for the user in the session.

Default value: "/bin/false"


The "ruid" property

  "ruid"                 gint                  : Read

The UID of the current user.

Allowed values: >= 0

Default value: 0


The "ruser" property

  "ruser"                gchararray            : Read

The current user's login name.

Default value: ""


The "service" property

  "service"              gchararray            : Read / Write / Construct Only

The PAM service name.

Default value: ""


The "shell" property

  "shell"                gchararray            : Read

The login shell for the user to run as in the session.

Default value: "/bin/false"


The "uid" property

  "uid"                  gint                  : Read

The UID to run as in the session.

Allowed values: >= 0

Default value: 0


The "user" property

  "user"                 gchararray            : Read / Write

The user login name to run as in the session.

Default value: ""


The "verbosity" property

  "verbosity"            SbuildAuthVerbosity   : Read / Write

Message verbosity level.

Default value: SBUILD_AUTH_VERBOSITY_NORMAL

Signals

The "require-auth" signal

SbuildAuthStatususer_function                  (SbuildAuth *sbuildauth,
                                            gpointer user_data);

Check if authentication is required. Each registered handler is run in turn until all have run, or one returns SBUILD_AUTH_STATUS_FAIL.

sbuildauth : the object which received the signal.
user_data : user data set when the signal handler was connected.
Returns : An SbuildAuthStatus to indicate whether authentication is not required, required, or if it has already failed.

The "session-run" signal

gboolean    user_function                  (SbuildAuth *sbuildauth,
                                            SbuildErrorPointer *arg1,
                                            gpointer user_data);

Run a session. Each registered session handler is run in turn.

sbuildauth : the object which received the signal.
arg1 : A GError.
user_data : user data set when the signal handler was connected.
Returns : TRUE to continue running session handlers, FALSE to abort on error (error must be set appropriately).