![]() |
![]() |
![]() |
Schroot Reference Manual | ![]() |
---|
SbuildAuthSbuildAuth — authentication handler |
enum SbuildAuthError; #define SBUILD_AUTH_ERROR SbuildAuth; SbuildAuthStatus (*SbuildAuthRequireAuthFunc) (SbuildAuth *auth); gboolean (*SbuildAuthSessionRunFunc) (SbuildAuth *auth, GError **error); SbuildAuthClass; enum SbuildAuthStatus; SbuildAuth* sbuild_auth_new (void); 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); gboolean sbuild_auth_get_quiet (const SbuildAuth *restrict auth); void sbuild_auth_set_quiet (SbuildAuth *auth, gboolean quiet); 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);
"command" GStrv : Read / Write "environment" GStrv : Read / Write "gid" gint : Read "home" gchararray : Read "quiet" gboolean : Read / Write "ruid" gint : Read "ruser" gchararray : Read "shell" gchararray : Read "uid" gint : Read "user" gchararray : Read / Write
"require-auth" SbuildAuthStatususer_function (SbuildAuth *sbuildauth, gpointer user_data); "session-run" gboolean user_function (SbuildAuth *sbuildauth, SbuildErrorPointer *arg1, gpointer user_data);
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.
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. |
#define SBUILD_AUTH_ERROR sbuild_auth_error_quark()
The error domain for sbuild authentication errors.
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. |
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).
|
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 |
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. |
SbuildAuth* sbuild_auth_new (void);
Creates a new SbuildAuth.
Returns : | the newly created SbuildAuth. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
void sbuild_auth_set_environment (SbuildAuth *auth, char **environment);
Set the environment to use in auth
.
auth : |
an SbuildAuth |
environment : |
the environment to use |
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. |
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. |
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. |
gboolean sbuild_auth_get_quiet (const SbuildAuth *restrict auth);
Get the message verbosity of auth
.
auth : |
an SbuildAuth |
Returns : | TRUE if quiet messages are enabled, otherwise FALSE. |
void sbuild_auth_set_quiet (SbuildAuth *auth, gboolean quiet);
Set the message verbosity of auth
.
auth : |
an SbuildAuth |
quiet : |
the quiet to use |
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).
|
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).
|
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).
|
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).
|
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).
|
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).
|
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).
|
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).
|
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).
|
gboolean sbuild_auth_run (SbuildAuth *auth, GError **error);
Run the authentication process.
If required, the user may be required to authenticate themselves. This usually occurs when running as a different user. The user must be a member of the appropriate groups in order to satisfy the groups and root-groups requirements in the chroot configuration.
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).
|
command
" property"command" GStrv : Read / Write
The command to run in the session, or NULL for a login shell.
environment
" property"environment" GStrv : Read / Write
The user environment to set in the session.
gid
" property"gid" gint : Read
The GID to run as in the session.
Allowed values: >= 0
Default value: 0
home
" property"home" gchararray : Read
The home directory for the user in the session.
Default value: "/bin/false"
quiet
" property"quiet" gboolean : Read / Write
Suppress non-essential messages.
Default value: FALSE
ruid
" property"ruid" gint : Read
The UID of the current user.
Allowed values: >= 0
Default value: 0
shell
" property"shell" gchararray : Read
The login shell for the user to run as in the session.
Default value: "/bin/false"
uid
" property"uid" gint : Read
The UID to run as in the session.
Allowed values: >= 0
Default value: 0
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. |
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).
|
<< SbuildConfig | SbuildSession >> |