Security/Tizen 2.X libprivilege-control Development Guide

From Tizen Wiki
Jump to: navigation, search

Contents

error codes

code value comment
PC_OPERATION_SUCCESS 0
PC_ERR_FILE_OPERATION -1
PC_ERR_MEM_OPERATION -2
PC_ERR_NOT_PERMITTED -3
PC_ERR_INVALID_PARAM -4
PC_ERR_INVALID_OPERATION -5
PC_ERR_DB_OPERATION -6
PC_ERR_DB_LABEL_TAKEN -7 Label is taken by another application
PC_ERR_DB_QUERY_PREP -8 Query fails during preparing a SQL statement
PC_ERR_DB_QUERY_BIND -9 Query fails during binding to a SQL statement
PC_ERR_DB_QUERY_STEP -10 Query fails during stepping a SQL statement
PC_ERR_DB_CONNECTION -11 Unable to establish a connection with the database
PC_ERR_DB_NO_SUCH_APP -12 There is no application with such app_id
PC_ERR_DB_PERM_FORBIDDEN -13 There already exists a permission with this name and type


app type

app_type_t :

PERM_APP_TYPE_FIRST
PERM_APP_TYPE_WRT = PERM_APP_TYPE_FIRST
PERM_APP_TYPE_OSP
PERM_APP_TYPE_OTHER
PERM_APP_TYPE_WRT_PARTNER
PERM_APP_TYPE_WRT_PLATFORM
PERM_APP_TYPE_OSP_PARTNER
PERM_APP_TYPE_OSP_PLATFORM
PERM_APP_TYPE_EFL
PERM_APP_TYPE_EFL_PARTNER
PERM_APP_TYPE_EFL_PLATFORM
PERM_APP_TYPE_LAST = PERM_APP_TYPE_EFL_PLATFORM


API

int get_smack_label_from_process(pid_t pid, char *smack_label);

Description : Gets smack label of a process, based on its pid.
Parameter :
pid pid of process
smack_label label of process
Return : PC_OPERATION_SUCCESS on success PC_ERR_* on error.


int perm_app_set_privilege(const char* name, const char* type, const char* path);

Description : Set DAC and SMACK privileges for application.
This function is meant to be called by the application launcher just before
it launches an application. It will setup DAC and SMACK privileges based
on app type and accesses.
It must be called with root privileges, which will be dropped in the function.
Parameter :
name package name
type application type (currently distinguished types:
"wgt", "wgt_partner", "wgt_platform",
"tpk", "osp", "osp_partner", "osp_platform",
"rpm", "efl")
path file system path to the binary
Return : PC_OPERATION_SUCCESS on success, PC_ERR_* on error


int perm_app_set_privilege_debug(const char* name, const char* type, const char* path);

Description : Set DAC and SMACK privileges for application.
This function is meant to be called by the debug application launcher just before
it launches an application. It will setup DAC and SMACK privileges based
on app type and accesses.
It must be called with root privileges, which will be dropped in the function.
Parameter :
name package name
type application type (currently distinguished types:
"wgt", "wgt_partner", "wgt_platform" and other)
path system path to the binary
Return : PC_OPERATION_SUCCESS on success, PC_ERR_* on error


char* perm_app_id_from_socket(int sockfd);

Description : For a UNIX socket endpoint determine the other side's pkg_id. Caller is
responsible for freeing the return widget id.
Parameter :
sockfd socket file descriptor
Return : id of the connecting widget on success, NULL on failure.


int perm_app_install(const char* pkg_id);

Description : Adds an application to the database if it doesn't already exist. It is needed
for tracking lifetime of an application. It must be called by privileged
user, before using any other perm_app_* function regarding that application.
It must be called within database transaction started with perm_begin() and
finished with perm_end(). It may be called more than once during installation.
Parameter :
pkg_id application identifier
Return : PC_OPERATION_SUCCESS on success, PC_ERR_* on error


int perm_app_uninstall(const char* pkg_id);

Description : Removes an application from the database with it's permissions, rules and
directories, enabling future installation of the application with the same
pkg_id. It is needed for tracking lifetime of an application. It must be
called by privileged user and within database transaction started with
perm_begin() and finished with perm_end().
Parameter :
pkg_id application identifier
Return : PC_OPERATION_SUCCESS on success, PC_ERR_* on error


int perm_app_setup_permissions(const char* pkg_id, app_type_t app_type, const char** perm_list);

Description : Grants SMACK permissions to an application, based on permissions list. It is
intended to be called during that application installation. The permissions
will be persistent. It must be called by privileged user and within database
transaction started with perm_begin() and finished with perm_end().
Parameter :
pkg_id application identifier
app_type application type
perm_list array of permission names, last element must be NULL
Return : PC_OPERATION_SUCCESS on success, PC_ERR_* on error


int perm_app_enable_permissions(const char* pkg_id, app_type_t app_type, const char** perm_list, bool persistent);

Description : Grants SMACK permissions to an application, based on permissions list. It was
intended to be called during that application installation. Permissions
granted as volatile will not be present after system boot. It must be called
by privileged user and within database transaction started with perm_begin()
and finished with perm_end().
In new code please call perm_app_setup_permissions during your application
installation instead of this function.
Parameter :
pkg_id application identifier
app_type application type
perm_list array of permission names, last element must be NULL
persistent boolean for choosing between persistent and temporary rules
Return : PC_OPERATION_SUCCESS on success, PC_ERR_* on error


int perm_app_disable_permissions(const char* pkg_id, app_type_t app_type, const char** perm_list);

Description : Removes previously granted SMACK permissions based on permissions list.
It will remove given permissions from an application, leaving other granted
permissions untouched. Results will be persistent. It must be called by
privileged user and within database transaction started with perm_begin()
and finished with perm_end().
Parameter :
pkg_id application identifier
app_type application type
perm_list array of permission names, last element must be NULL
Return : PC_OPERATION_SUCCESS on success, PC_ERR_* on error


int perm_app_revoke_permissions(const char* pkg_id);

Description : Removes all application's permissions, rules and directories registered in
the database. It must be called by privileged user and within database
transaction started with perm_begin() and finished with perm_end().
Parameter :
pkg_id application identifier
Return : PC_OPERATION_SUCCESS on success, PC_ERR_* on error


int perm_app_reset_permissions(const char* pkg_id);

Description : Removes all application's permissions which are not persistent. It must be
called by privileged user and within database transaction started with
perm_begin() and finished with perm_end().
Parameter :
pkg_id application identifier
Return : PC_OPERATION_SUCCESS on success, PC_ERR_* on error


int perm_app_has_permission(const char *pkg_id, app_type_t app_type, const char *permission_name, bool *is_enabled);

Description : Checks if an application has the privilege that is specified by the name.
It must be called by privileged user.
Parameter :
pkg_id application identifier
app_type application type
permission_name permission name
is_enabled buffer for return value
Return : PC_OPERATION_SUCCESS on success, PC_ERR_* on error


int perm_get_permissions(char ***ppp_permissions, app_type_t app_type);

Description : Get the list of the permissions for given application type
Caller is responsible for freeing allocated memory.
*ppp_permissions is a pointer to an array consisting of char pointers,
terminated with NULL pointer. Memory allocated with each
of these pointer except for the last one (NULL) should be freed,
followed by freeing *ppp_permissions itself.
Parameter :
ppp_permissions list of all permissions
app_type application type
Return : PC_OPERATION_SUCCESS on success, PC_ERR_* on error


int perm_get_apps_with_permission(perm_app_status_t **pp_apps, size_t *pi_apps_number, app_type_t app_type, const char *s_permission_name);

Description : Get the list of the applications of given type with particular permission.
Caller is responsible for freeing allocated memory
using perm_free_apps_list()
Parameter :
pp_apps list of application's statuses
pi_apps_number number of found application
app_type application type
s_permission_name permission name
Return : PC_OPERATION_SUCCESS on success, PC_ERR_* on error


void perm_free_apps_list(perm_app_status_t *pp_apps, size_t i_apps_number);

Description : Free the list of the applications allocated with
perm_get_apps_with_permission().
Parameter :
pp_apps list of application's statuses
i_apps_number number of applications on the list
Return :


int perm_app_get_permissions(const char *pkg_id, app_type_t app_type, char ***ppp_perm_list);

Description : Get permissions for the specified app.
In case of success caller is responsible for freeing memory allocated by it.
Each cell in *ppp_perm_list except for the last (NULL) should be freed, followed by freeing
*ppp_perm_list itself.
In case of error an error code is returned and, provided that ppp_perm_list is not NULL,
*ppp_perm_list is set to NULL.
Parameter :
pkg_id application identifier
app_type application type
ppp_perm_list buffer for return value
Return : PC_OPERATION_SUCCESS on success, PC_ERR_* on error


int perm_app_setup_path(const char* pkg_id, const char* path, app_path_type_t app_path_type, ...);

Description : Sets SMACK labels for an application directory (recursively) or for an executable/symlink
file. The exact behavior depends on app_path_type argument:
- APP_PATH_PRIVATE: label with app's label, set access label on everything
and execute label on executable files and symlinks to executable files
- APP_PATH_GROUP: label with given shared_label, set access label on
everything and enable transmute on directories. Also give pkg_id full access
to the shared label.
- APP_PATH_PUBLIC: label with autogenerated label, set access label on
everything and enable transmute on directories. Give full access to the label to
pkg_id and RX access to all other applications.
- APP_PATH_SETTINGS: label with autogenerated label, set access label on
everything and enable transmute on directories. Give full access to the label to
pkg_id and RWX access to all appsetting applications.
- PERM_APP_PATH_NPRUNTIME: label executable file or symlink to an exec given in path param
with label "<pkg_id>.npruntime". Set execute label on it.
Give pkg_id RW access to new created label and give new label RXAT access to pkg_id.
- APP_PATH_ANY_LABEL: label with given shared_label. Set access label on
everything and execute label on executable files and symlinks to
executable files.
This function should be called during application installation. Results will
be persistent on the file system. It must be called by privileged user and
within database transaction started with perm_begin() and finished with
perm_end().
Parameter :
pkg_id application identifier
path file or directory path
app_path_type application path type
shared_label optional argument for APP_PATH_GROUP_RW and
APP_PATH_ANY_LABEL path type; type is const char*
Return : PC_OPERATION_SUCCESS on success, PC_ERR_* on error


int perm_app_get_paths(const char* pkg_id, app_path_type_t app_path_type, char*** ppp_paths);

Description : Get paths of the specified type for the given application.
Provided type must be one of PERM_APP_PATH_GROUP, PERM_APP_PATH_PUBLIC, PERM_APP_PATH_SETTINGS,
PERM_APP_PATH_NPRUNTIME, as other types are not stored in the database.
In case of success caller is responsible for freeing memory allocated by it.
Each cell in *ppp_paths except for the last (NULL) should be freed, followed by freeing
*ppp_paths itself.
In case of error an error code is returned and, provided that ppp_paths is not NULL,
*ppp_paths is set to NULL.
Parameter :
pkg_id application identifier
app_path_type type of path
ppp_paths buffer for return value
Return : PC_OPERATION_SUCCESS on success, PC_ERR_* on error


int perm_app_remove_path(const char* pkg_id, const char *path);

Description : Remove path and all rules associated with it from the database.
This does not remove data from the filesystem.
Parameter :
pkg_id application identifier
path path to remove
Return : PC_OPERATION_SUCCESS on success, PC_ERR_* on error


int perm_app_add_friend(const char* pkg_id1, const char* pkg_id2);

Description : Make two applications "friends", by giving them both full permissions on
each other.
Results will be persistent on the file system. Must be called after
perm_app_enable_permissions() has been called for each application.
It must be called by privileged user.
Parameter :
pkg_id1 first application identifier
pkg_id2 second application identifier
Return : PC_OPERATION_SUCCESS on success, PC_ERR_* on error


int perm_add_api_feature(app_type_t app_type, const char* api_feature_name, const char** smack_rule_set, const gid_t* list_of_db_gids, size_t list_size);

Description : Adds new feature to the database.
It must be called by privileged user and within database transaction
started with perm_begin() and finished with perm_end().
Both *add_api_feature functions contain redundant and deprecated arguments
associated with gids list. This is the reason why perm_define_permission
should be used instead. It gives the same functionality, but comes without
the last two arguments.
Parameter :
app_type application type
api_feature_name name of newly added feature
smack_rule_set set of rules required by the feature - NULL terminated
list of NULL terminated rules.
list_of_db_gids deprecated attribute, use NULL or an error occurs
list_size deprecated attribute, use 0 or an error occurs
Return : PC_OPERATION_SUCCESS on success, PC_ERR_* on error


int perm_define_permission(app_type_t app_type, const char* permission_name, const char** smack_rule_set);

Description : Adds new permission (api feature) to the database.
It must be called by privileged user and within database transaction
started with perm_begin() and finished with perm_end().
Parameter :
app_type application type
permission_name name of newly added permission (api feature)
smack_rule_set set of rules granted by the permission - NULL terminated
list of NULL terminated rules.
Return : PC_OPERATION_SUCCESS on success, PC_ERR_* on error


int perm_begin(void);

Description : Starts exclusive database transaction. Run before functions modifying
database.
Parameter :
Return : PC_OPERATION_SUCCESS on success, PC_ERR_* on error


int perm_end(void);

Description : Ends exclusive database transaction. Run after functions modifying database.
If an error occurred during the transaction then all modifications will be
rolled back.
Parameter :
Return : PC_OPERATION_SUCCESS on success, PC_ERR_* on error


int perm_rollback(void);

Description : Run to rollback any privilege modification.
Parameter :
Return : PC_OPERATION_SUCCESS on success, PC_ERR_* on error


int perm_add_additional_rules(const char** set_smack_rule_set);

Description : Adds additional rules to the database. The rules can use wild-cards and labels.
It must be called within database transaction started with perm_begin() and
finished with perm_end().
Parameter :
set_smack_rule_set an array of rules, NULL terminated
Return : PC_OPERATION_SUCCESS on success, PC_ERR_* on error


const char* perm_strerror(int errnum);

Description : Get message connected to error code.
Parameter :
errnum error code
Return : string describing the error code


int perm_app_set_privilege_version(const char* const s_app_label_name, const char * const s_version);

Description : Set privilege version for specific app. This function has to be
called before assigning any privileges, otherwise incorrect versions
of privileges will be assigned. If this function is not called,
default privilege version is the current tizen version. The provided
version has to be available in smack-privilege-config package, that
is installed on the target device, otherwise that version is not
supported.
Parameter :
s_app_label_name application's label name
s_version version to set
Return : PC_OPERATION_SUCCESS on success, PC_ERR_* on error
PC_ERR_INVALID_PARAM on unsupported version


int perm_app_get_privilege_version(const char* const s_app_label_name, char **p_version);

Description : Get privilege version for specific app.
Parameter :
s_app_label_name application's label name
p_version return version - this should be freed
Return : PC_OPERATION_SUCCESS on success, PC_ERR_* on error


int perm_db_configuration_refresh(const char *const dir, int clear_not_found_permissions);

Description : Perform a configuration refresh on a rule database.
Parameter :
dir directory's path, from which information will be read.
clear_not_found_permissions input flag for indicating need of additional resetting all privileges
Return : PC_OPERATION_SUCCESS on success, PC_ERR_* on error


int perm_app_enable_blacklist_permissions(const char* const s_app_label_name, app_type_t perm_type, const char** pp_perm_list);

Description : Allows selected blacklisted permissions to be used by given application.
Applications won't be able to use blacklisted permission when they are
disabled and they are disabled by default. Passing permission name that
is not on a black list will result in an error.
It must be called by privileged
user and within database transaction started with perm_begin() and finished
with perm_end().
Parameter :
s_app_label_name application identifier
perm_type permission type
pp_perm_list array of blacklist permission names, last element
must be NULL
Return : PC_OPERATION_SUCCESS on success, PC_ERR_* on error


int perm_app_disable_blacklist_permissions(const char* const s_app_label_name, app_type_t perm_type, const char** pp_perm_list);

Description : Disables selected blacklisted permissions for given application. This
setting overrides permissions requested by app during installation as well
as permissions enabled with perm_app_enable_permissions(). Passing
permission name that is not on a black list or is not enabled will result in
an error.
It must be called by privileged user and within database transaction started
with perm_begin() and finished with perm_end().
Parameter :
s_app_label_name application identifier
perm_type permission type
pp_perm_list array of blacklist permission names, last element
must be NULL
Return : PC_OPERATION_SUCCESS on success, PC_ERR_* on error


int perm_app_get_blacklist_statuses(const char* const s_app_label_name, perm_blacklist_status_t** pp_perm_list, size_t* p_perm_number);

Description : Returns a list of black list permissions and their status (enabled/disabled)
for given app.
Parameter :
s_app_label_name application identifier
pp_perm_list array of blacklist permission structures containing
permission name and its status. Free it with>br/>perm_free_blacklist_statuses(...)
p_perm_number size of the blacklist permission array
Return : PC_OPERATION_SUCCESS on success, PC_ERR_* on error


void perm_free_blacklist_statuses(perm_blacklist_status_t* p_perm_list, size_t i_perm_number);

Description : Free the list of blacklist statuses allocated with
perm_app_get_blacklist_statuses(...).
Parameter :
p_perm_list array of blacklist permission structures containing
permission name and its status.
i_perm_number size of the blacklist permission array
Return :