#include <sys/types.h>
#include <stdint.h>
Go to the source code of this file.
Defines | |
#define | CREDS_BAD -1 |
Typedefs | |
typedef int | creds_type_t |
typedef long | creds_value_t |
typedef struct _creds_struct * | creds_t |
Functions | |
creds_t | creds_getpeer (int socket) |
creds_t | creds_gettask (pid_t pid) |
creds_t | creds_init () |
void | creds_clear (creds_t creds) |
void | creds_free (creds_t creds) |
int | creds_set (const creds_t creds) |
int | creds_set2 (const creds_t creds, int flags) |
int | creds_add (creds_t *creds, creds_type_t type, creds_value_t value) |
void | creds_sub (creds_t creds, creds_type_t type, creds_value_t value) |
creds_type_t | creds_list (const creds_t creds, int index, creds_value_t *value) |
int | creds_find (const creds_t creds, const char *pattern, char *buf, size_t size) |
int | creds_have_p (const creds_t creds, creds_type_t type, creds_value_t value) |
int | creds_have_access (const creds_t creds, creds_type_t type, creds_value_t value, const char *access_type) |
long | creds_str2creds (const char *credential, creds_value_t *value) |
int | creds_creds2str (creds_type_t type, creds_value_t value, char *buf, size_t size) |
const uint32_t * | creds_export (creds_t creds, size_t *length) |
creds_t | creds_import (const uint32_t *list, size_t length) |
long | creds_load (int flags, const char *path, const creds_t creds) |
long | creds_confine (const char *path) |
long | creds_confine2 (const char *path, int flags, const creds_t creds) |
int | credp_str2flags (const char *str, int *mask) |
size_t | credp_flags2str (int flags, int mask, char *buf, size_t size) |
Credentials handling library.
The current credentials information supported by the kernel, includes following:
When available, the kernel defines the supported credential types (CREDS_* constants) in <linux/aegis/creds.h>.
Most users of this API need to be aware of only one symbol: CREDS_BAD.
#define CREDS_BAD -1 |
typedef struct _creds_struct* creds_t |
Opaque credentials handle.
The internal structure is defined by the implementation. A NULL value is also valid, and represents an empty credentials set. All functions defined here, that take creds_t as a parameter, can be called with NULL handle.
typedef int creds_type_t |
Types of credentials information
typedef long creds_value_t |
Value of the credential
size_t credp_flags2str | ( | int | flags, | |
int | mask, | |||
char * | buf, | |||
size_t | size | |||
) |
Convert flags and mask into modifier keywords list.
flags | The flags value | |
mask | The bits used in flags value | |
buf | The buffer for the converted value | |
size | The size of the buffer |
The return value has the semantics of 'snprintf' (but guaranteed to be always >= 0). If the return value is larger or equal to size, the provided buffer was too short (and conversion was truncated).
int credp_str2flags | ( | const char * | str, | |
int * | mask | |||
) |
Convert policy modifier keywors into flags (for creds_load)
str | The modifier keywords | |
mask | Returns the mask of affected bits in flags |
If str==NULL, returns the default flags and the mask (if non-NULL) indicates the bits in use as default values (which may be ON or OFF in flags).
If str!=NULL, it must be a white space separated list of the modifier keywords. Returns the default flags modified by the modifier keywords and the mask (if non-NULL) indicates the bits modified by the modifiers (passing an empty string, returns default flags with mask==0).
The flags value '-1' is invalid, and is returned when the modifiers cannot be converted to flags. Additional error information is retured in mask as:
int creds_add | ( | creds_t * | creds, | |
creds_type_t | type, | |||
creds_value_t | value | |||
) |
Add a credential to the credential data
creds | A pointer to the credentials handle. | |
type | The type of the credential value | |
value | The value of the credential |
This operation can change the content of the credentials handle and invalidate previous value -- thus, if application has copied the handle to multiple locations, it must update all copies with the value in handle that was passed to this function.
void creds_clear | ( | creds_t | creds | ) |
Clear all credentials.
creds | The credentials handle. |
Clear out all credentials from creds, without releasing the memory space allocated to the handle.
long creds_confine | ( | const char * | path | ) |
Activate credentials based on defined policy
path | Path to executable |
When this function is supported by the implementation, it will locate an installed policy based on the path and set the credentials based on it.
If the current task has some capabilities active, it can activate all of the policy (possibly increasing the credentials)
CAP::setgid CAP::setuid tcb
Otherwise, the function does intersection between the stored policy and current credentials, and credentials can only stay same or decrease.
If the path does not have a matching policy, all current credentials will be removed, and all UID and GID are set to 'nobody' and 'nogroup'.
'nobody' and 'nogroup' are also used, if the policy specifies UID or GID, but current task does not have 'setuid' and/or 'setgid' capabilities.
long creds_confine2 | ( | const char * | path, | |
int | flags, | |||
const creds_t | creds | |||
) |
Activate credentials based on defined policy, if policy is not defined use fallback from arguments.
path | Path to executable | |
flags | Processing flags | |
creds | The credentials to apply |
When this function is supported by the implementation, it will locate an installed policy based on the path and set the credentials based on it. If policy is not found fallback policy is used from arguments flags and creds.
If the current task has some capabilities active, it can activate all of the policy (possibly increasing the credentials)
CAP::setgid CAP::setuid tcb
Otherwise, the function does intersection between the stored policy and current credentials, and credentials can only stay same or decrease.
If the path does not have a matching policy, all current credentials configured according arguments 'flags' and 'creds'.
If the policy specifies UID or GID, but current task does not have 'setuid' and/or 'setgid' capabilities; user is set as 'nobody' and group is set as 'nogroup'.
int creds_creds2str | ( | creds_type_t | type, | |
creds_value_t | value, | |||
char * | buf, | |||
size_t | size | |||
) |
Universal credential to string conversion
type | Credential type | |
value | Credential value | |
buf | The buffer for the converted value | |
size | The size of the buffer |
The return value has the semantics of 'snprintf'. If the return value is larger or equal to size, the provided buffer was too short (and conversion was truncated).
const uint32_t* creds_export | ( | creds_t | creds, | |
size_t * | length | |||
) |
Export opaque credentials information as integer array
creds | Credentials handle | |
length | Returns the length of the array (# of uint32_t ints) |
The returned value is only valid as long as the creds handle is not modified or freed.
int creds_find | ( | const creds_t | creds, | |
const char * | pattern, | |||
char * | buf, | |||
size_t | size | |||
) |
Find first credential matching a pattern
creds | The credentials handle | |
pattern | The pattern to match ('*' match zero or more, '?' match single) | |
buf | The buffer for the matched credential | |
size | The size of the buffer |
The return value has the semantics of 'snprintf'. If the return value is larger or equal to size, the provided buffer was too short and find has failed.
The return value has following interpretaions
Example, to find user id from credentials creds_find(creds, "UID::*", buf, sizeof(buf));
void creds_free | ( | creds_t | creds | ) |
Free credentials handle.
creds | The credentials handle. |
After the call, the content of the handle is invalid and must not be passed to any of the functions in this header. To be resused, reinitialize the handle with one of the following functions:
creds_t creds_getpeer | ( | int | socket | ) |
Read peer credentials from a socket.
socket | The socket |
The returned handle must be freed with creds_free.
Because every peer has at least UID and GID, empty credentials set (a NULL return) indicates some error.
creds_t creds_gettask | ( | pid_t | pid | ) |
Read credentials from a task
pid | The process id (0 gives current process) |
The returned handle must be freed with creds_free.
Because every task has at least UID and GID, empty credentials set (a NULL return) indicates some error.
Note that this function should be used only in order to obtain a credential set either for process itself or for its children. Otherwise its usage maybe not secure.
int creds_have_access | ( | const creds_t | creds, | |
creds_type_t | type, | |||
creds_value_t | value, | |||
const char * | access_type | |||
) |
Test if the process with a given credential set can perform an access of specified type on a object protected by the credential identified by type and value.
creds | The credentials handle | |
type | The type of credentials to test | |
value | The specific value to test | |
access_type | The access type |
Please note that current implementation is using the creds_have_p function underneath and access_type parameter is ignored. This function is added for future releases compatibility. Please supply an empty string as the access_type parameter.
int creds_have_p | ( | const creds_t | creds, | |
creds_type_t | type, | |||
creds_value_t | value | |||
) |
Test presence of a credential.
creds | The credentials handle | |
type | The type of credentials to test | |
value | The specific value to test |
creds_t creds_import | ( | const uint32_t * | list, | |
size_t | length | |||
) |
Recreate credentails from exported integer array
list | The integer array | |
length | The length (# of uint32_t) of array |
The returned creds handle must be released with creds_free.
creds_t creds_init | ( | ) |
Initialize a new empty credentials handle
This operation succeeds always. The returned value must be released with creds_free.
Note: because a NULL handle is a valid representation of an empty credentials set, implementation may just return NULL here (and NULL return is not an indication of any error!).
creds_type_t creds_list | ( | const creds_t | creds, | |
int | index, | |||
creds_value_t * | value | |||
) |
Iterate over all credentials values.
creds | The credentials handle. | |
index | The index of the credential [0..N] | |
value | The returned credentials value |
long creds_load | ( | int | flags, | |
const char * | path, | |||
const creds_t | creds | |||
) |
Bind a set of credentials to an executable
flags | Processing flags | |
path | Path to executable | |
creds | The credentials to apply |
When this function is supported by the implementation, it will arrange that every time the executable defined by the "path" is executed, it will have the defined set of credentials in its task context.
This function requires special capabilities.
tcb
int creds_set | ( | const creds_t | creds | ) |
Modify credentials of current process.
creds | The handle for credentials to be applied. |
A requested credential is activated only if the current task has proper credentials to allow the operation.
CAP::setgid CAP::setuid
If there is a special support in kernel for this operation, also unprivileged task can use this function, but the resulting credentials set will be an intersection of the current and proposed set. This allows unprivileged task to decrease credentials.
int creds_set2 | ( | const creds_t | creds, | |
int | flags | |||
) |
Modify credentials of current process.
creds | The handle for credentials to be applied. | |
flags | The policy modifier flags |
A requested credential is activated only if the current task has proper credentials to allow the operation.
CAP::setgid CAP::setuid
If there is a special support in kernel for this operation, also unprivileged task can use this function, but the resulting credentials set will be an intersection of the current and proposed set. This allows unprivileged task to decrease credentials.
long creds_str2creds | ( | const char * | credential, | |
creds_value_t * | value | |||
) |
Universal string to credential conversion
credential | The name |
value | The credential value (NULL possible) |
The credential string starts with a name space designation separated from the actual credential name by "::". Some possible name spaces on a Unix platform are
Converting a known name space only (for example "GID::") returns the type of the name space and CREDS_BAD as the value.
An implementation may support other name spaces depending on platform. It also decides how to deal with omitted namespace.
Beware, that although in above, the example name spaces each map directly to unique credential type, other name spaces may map to the same types, e.g. it's not 1-to-1 mapping!
void creds_sub | ( | creds_t | creds, | |
creds_type_t | type, | |||
creds_value_t | value | |||
) |
Subtract credential fromt the credential data
creds | The credentials handle | |
type | The type of the credential value | |
value | The value of the credentail |
Removes the specified credential, if present in the creds, otherwise does nothing. There are no error conditions.