Offers interface for accessing current system user and authentication of users.
On Linux the implementation uses PAM so the authentication is not restricted to a local password file instead it can also be configured to use LDAP.
| SystemUser | Offers interface for accessing current system user and authentication of users. |
| Copyright | This program is free software. |
| Files | |
| C-kern/ | Header file SystemUser. |
| C-kern/ | Implementation file SystemUser Linuximpl. |
| Types | |
| struct sysuser_t | Export sysuser_t into global namespace. |
| struct sysuser_id_t | Make sysuser_id_t an alias of sys_userid_t. |
| struct sysuser_info_t | Export sysuser_info_t into global namespace. |
| Functions | |
| test | |
| unittest_platform_sysuser | Test sysuser_t functionality. |
| sysuser_id_t | This type is an alias of sys_userid_t. |
| lifetime | |
| sysuser_id_FREE | Static initializer. |
| query | |
| isadmin_sysuserid | Returns true if this user is administrator (== root). |
| isequal_sysuserid | Compares two sysuser_id_t for equality. |
| sysuser_t | Offers functionality to manage system user. |
| current | Contains the current user the process uses. |
| realuser | Contains user which started the process. |
| privilegeduser | Contains privileged user which is set at process creation from the system. |
| lifetime | |
| sysuser_FREE | Static initializer. |
| init_sysuser | Initializes system user of process at process start. |
| free_sysuser | Clears sysusr and resets system user ids. |
| query | |
| isequal_sysuser | Returns true if lsysusr equals rsysusr. |
| current_sysuser | Returns the current active system user. |
| real_sysuser | Returns sysuser_id_t of the user which started the process. |
| privileged_sysuser | Returns sysuser_id_t of the user which has other privileges. |
| switch | |
| switchtoprivilege_sysuser | Switches current user to privileged_sysuser. |
| switchtoreal_sysuser | Switches current user to real_sysuser. |
| set | |
| setusers_sysuser | Changes realuser and privileged user. |
| authentication | |
| authenticate_sysuser | Checks that a certain user / password combination is valid. |
| sysuser_info_t | Stores information about a sysuser_t. |
| size | Size in bytes of allocated memory this structure uses. |
| lifetime | |
| new_sysuserinfo | Returns information about sysuser_id_t given as parameter. |
| delete_sysuserinfo | Frees memory holding system user information. |
| query | |
| name_sysuserinfo | Returns user name stored in usrinfo. |
| inline implementation | |
| sysuser_t | |
| current_sysuser | Implement sysuser_t.current_sysuser. |
| real_sysuser | Implement sysuser_t.real_sysuser. |
| privileged_sysuser | Implement sysuser_t.privileged_sysuser. |
| init_sysuser | Implement sysuser_t.init_sysuser as noop if !defined(KONFIG_SUBSYS_SYSUSER) |
| free_sysuser | Implement sysuser_t.free_sysuser as noop if !defined(KONFIG_SUBSYS_SYSUSER) |
| sysuser_info_t | |
| name_sysuserinfo | Implements sysuser_info_t.name_sysuserinfo. |
This program is free software. You can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
© 2012 Jörg Seebohn
Header file SystemUser.
Implementation file SystemUser Linuximpl.
typedef struct sysuser_t sysuser_t
Export sysuser_t into global namespace.
Make sysuser_id_t an alias of sys_userid_t.
typedef struct sysuser_info_t sysuser_info_t
Export sysuser_info_t into global namespace.
| test | |
| unittest_platform_sysuser | Test sysuser_t functionality. |
int unittest_platform_sysuser( void )
Test sysuser_t functionality.
The unit test uses username=”guest” and password=”GUEST” to test <authenticate_sysuser> for success. Configure your system either with this test account or adapt the unit test with a valid username/password combination. Also this test works only if unittest_platform_sysuser is started as user “root” or as “guest”.
typedef sys_userid_t sysuser_id_t
This type is an alias of sys_userid_t.
| lifetime | |
| sysuser_id_FREE | Static initializer. |
| query | |
| isadmin_sysuserid | Returns true if this user is administrator (== root). |
| isequal_sysuserid | Compares two sysuser_id_t for equality. |
bool isequal_sysuserid( sysuser_id_t luid, sysuser_id_t ruid )
Compares two sysuser_id_t for equality.
struct sysuser_t
Offers functionality to manage system user.
The current implementation supports the idea (see <initonce_sysuser>) of two users.
The user returned from privileged_sysuser has higher or special privileges so the process can accomplish system administration tasks for which the real user has not enough rights.
| current | Contains the current user the process uses. |
| realuser | Contains user which started the process. |
| privilegeduser | Contains privileged user which is set at process creation from the system. |
| lifetime | |
| sysuser_FREE | Static initializer. |
| init_sysuser | Initializes system user of process at process start. |
| free_sysuser | Clears sysusr and resets system user ids. |
| query | |
| isequal_sysuser | Returns true if lsysusr equals rsysusr. |
| current_sysuser | Returns the current active system user. |
| real_sysuser | Returns sysuser_id_t of the user which started the process. |
| privileged_sysuser | Returns sysuser_id_t of the user which has other privileges. |
| switch | |
| switchtoprivilege_sysuser | Switches current user to privileged_sysuser. |
| switchtoreal_sysuser | Switches current user to real_sysuser. |
| set | |
| setusers_sysuser | Changes realuser and privileged user. |
| authentication | |
| authenticate_sysuser | Checks that a certain user / password combination is valid. |
sysuser_id_t current
Contains the current user the process uses. It is either set to the value of realuser or privilegeduser.
int init_sysuser( /*out*/sysuser_t * sysusr )
Initializes system user of process at process start.
On Posix like system a process can have an effective user id which is different from the real user id which started the process. The effectice user id is set from the system to the owner of the program file if the setuid bit is set.
This function sets the effective user id to the real user id but remembers it. To get privileged rights call switchtoprivilege_sysuser.
int free_sysuser( sysuser_t * sysusr )
Clears sysusr and resets system user ids. The system user ids are set to the values before init_sysuser was called.
sysuser_id_t real_sysuser( sysuser_t * sysusr )
Returns sysuser_id_t of the user which started the process.
sysuser_id_t privileged_sysuser( sysuser_t * sysusr )
Returns sysuser_id_t of the user which has other privileges. If this user is equal to real_sysuser the process has no special privileges. A privileged user is not necessarily an administrator but it can.
int switchtoprivilege_sysuser( sysuser_t * sysusr )
Switches current user to privileged_sysuser. See current_sysuser.
int switchtoreal_sysuser( sysuser_t * sysusr )
Switches current user to real_sysuser. See current_sysuser.
int setusers_sysuser( sysuser_t * sysusr, sysuser_id_t realuser, sysuser_id_t privilegeduser )
Changes realuser and privileged user. See real_sysuser and privileged_sysuser and current_sysuser. If you set privilegeduser to the same value as realuser you will give up your privileges. The current user is switch to the real user. If you want to change the user ids to arbitrary values other than realuser or privilegeduser this call will only work if current_sysuser is admin.
int authenticate_sysuser( const char * username, const char * password )
Checks that a certain user / password combination is valid.
| 0 | Success |
| EACCES | User unknown or password wrong. |
| ENOMEM | Buffer allocation failed. |
| ERANGE | Number of tries of wrong authentication reqeusts reached. |
| EPERM | Not enough rights to authenticate user. |
| ENOTRECOVERABLE | Caller should exit process after this value has been returned. |
| ELIBACC | Shared system library not found. |
Some underlying implementations are returns EACCES in case of EPERM or other error codes.
Uses authentication service of the operating system to authenticate system users. This means loading shated libraries into the running process. It is best to shield the caller by spawing a child process which does the authentication (see process_t). Only username / password combinations can be authenticated which are known to the underlying operating system. The user of the running process is not changed. To authenticate other users than the calling user the running process needs to have spedial rights. On Linux it should be running as root.
The configuration file for PAM is stored in /etc/pam.d/service_name alternatively in /etc/pam.conf. The fallback to /etc/pam.d/other is made if no service with this name exists. Currently the service name “passwd” (see sysuser_SYS_SERVICE_NAME) is used therefore the configuration file /etc/pam.d/passwd is used which is the configuration of the passwd command to change the own password. This configuration should always exist.
struct sysuser_info_t
Stores information about a sysuser_t.
| size | Size in bytes of allocated memory this structure uses. |
| lifetime | |
| new_sysuserinfo | Returns information about sysuser_id_t given as parameter. |
| delete_sysuserinfo | Frees memory holding system user information. |
| query | |
| name_sysuserinfo | Returns user name stored in usrinfo. |
int new_sysuserinfo( /*out*/sysuser_info_t ** usrinfo, sysuser_id_t uid )
Returns information about sysuser_id_t given as parameter. The system database is searched for an entry.
If no one exists ENOENT is returned and no error log is written in this case.
| sysuser_t | |
| current_sysuser | Implement sysuser_t.current_sysuser. |
| real_sysuser | Implement sysuser_t.real_sysuser. |
| privileged_sysuser | Implement sysuser_t.privileged_sysuser. |
| init_sysuser | Implement sysuser_t.init_sysuser as noop if !defined(KONFIG_SUBSYS_SYSUSER) |
| free_sysuser | Implement sysuser_t.free_sysuser as noop if !defined(KONFIG_SUBSYS_SYSUSER) |
| sysuser_info_t | |
| name_sysuserinfo | Implements sysuser_info_t.name_sysuserinfo. |
#define current_sysuser( sysusr ) ((sysusr)->current)
Implement sysuser_t.current_sysuser.
#define real_sysuser( sysusr ) ((sysusr)->realuser)
Implement sysuser_t.real_sysuser.
#define privileged_sysuser( sysusr ) ((sysusr)->privilegeduser)
Implement sysuser_t.privileged_sysuser.
#define init_sysuser( sysuser ) ((*(sysuser)) = (sysuser_t) sysuser_FREE, 0)
Implement sysuser_t.init_sysuser as noop if !defined(KONFIG_SUBSYS_SYSUSER)
#define free_sysuser( sysuser ) ((*(sysuser)) = (sysuser_t) sysuser_FREE, 0)
Implement sysuser_t.free_sysuser as noop if !defined(KONFIG_SUBSYS_SYSUSER)
#define name_sysuserinfo( usrinfo ) ((usrinfo)->name)
Implements sysuser_info_t.name_sysuserinfo.
Export sysuser_t into global namespace.
typedef struct sysuser_t sysuser_t
Offers functionality to manage system user.
struct sysuser_t
This type is an alias of sys_userid_t.
typedef sys_userid_t sysuser_id_t
Chooses Posix system user id.
#define sys_userid_t uid_t
Export sysuser_info_t into global namespace.
typedef struct sysuser_info_t sysuser_info_t
Stores information about a sysuser_t.
struct sysuser_info_t
Test sysuser_t functionality.
int unittest_platform_sysuser( void )
Static initializer.
#define sysuser_id_FREE sys_userid_FREE
Returns true if this user is administrator (== root).
bool isadmin_sysuserid( sysuser_id_t uid )
Compares two sysuser_id_t for equality.
bool isequal_sysuserid( sysuser_id_t luid, sysuser_id_t ruid )
Contains the current user the process uses.
sysuser_id_t current
Contains user which started the process.
sysuser_id_t realuser
Contains privileged user which is set at process creation from the system.
sysuser_id_t privilegeduser
Static initializer.
#define sysuser_FREE { sysuser_id_FREE, sysuser_id_FREE, sysuser_id_FREE }
Initializes system user of process at process start.
int init_sysuser( /*out*/sysuser_t * sysusr )
Clears sysusr and resets system user ids.
int free_sysuser( sysuser_t * sysusr )
Returns true if lsysusr equals rsysusr.
bool isequal_sysuser( const sysuser_t * lsysusr, const sysuser_t * rsysusr )
Returns the current active system user.
sysuser_id_t current_sysuser( sysuser_t * sysusr )
Returns sysuser_id_t of the user which started the process.
sysuser_id_t real_sysuser( sysuser_t * sysusr )
Returns sysuser_id_t of the user which has other privileges.
sysuser_id_t privileged_sysuser( sysuser_t * sysusr )
Switches current user to privileged_sysuser.
int switchtoprivilege_sysuser( sysuser_t * sysusr )
Switches current user to real_sysuser.
int switchtoreal_sysuser( sysuser_t * sysusr )
Changes realuser and privileged user.
int setusers_sysuser( sysuser_t * sysusr, sysuser_id_t realuser, sysuser_id_t privilegeduser )
Checks that a certain user / password combination is valid.
int authenticate_sysuser( const char * username, const char * password )
Size in bytes of allocated memory this structure uses.
size_t size
Returns information about sysuser_id_t given as parameter.
int new_sysuserinfo( /*out*/sysuser_info_t ** usrinfo, sysuser_id_t uid )
Frees memory holding system user information.
int delete_sysuserinfo( sysuser_info_t ** usrinfo )
Returns user name stored in usrinfo.
const char * name_sysuserinfo( sysuser_info_t * usrinfo )
Implement sysuser_t.current_sysuser.
#define current_sysuser( sysusr ) ((sysusr)->current)
Implement sysuser_t.real_sysuser.
#define real_sysuser( sysusr ) ((sysusr)->realuser)
Implement sysuser_t.privileged_sysuser.
#define privileged_sysuser( sysusr ) ((sysusr)->privilegeduser)
Implement sysuser_t.init_sysuser as noop if !defined(KONFIG_SUBSYS_SYSUSER)
#define init_sysuser( sysuser ) ((*(sysuser)) = (sysuser_t) sysuser_FREE, 0)
Implement sysuser_t.free_sysuser as noop if !defined(KONFIG_SUBSYS_SYSUSER)
#define free_sysuser( sysuser ) ((*(sysuser)) = (sysuser_t) sysuser_FREE, 0)
Implements sysuser_info_t.name_sysuserinfo.
#define name_sysuserinfo( usrinfo ) ((usrinfo)->name)
The name of service used during authentication.
#define sysuser_SYS_SERVICE_NAME "passwd"