Cynara's API is split into two parts:
- client API for privilege checking API - easily accessed with libcynara-client(-async) by anyone
- admin API for policy managing API - accessed only by trusted processes with libcynara-admin.
Cynara service uses separate Unix Domain Sockets for handling each type of API.
Both synchronous and asynchronous client API for Cynara are available. It is provided by libcynara-client and libcynara-client-async libraries.
To enhance client performance a simple LRU Cache was implemented for both synchronous and asynchronous client API. Cache is available in Cynara since version 0.2.0.
On Tizen 3.0 application context - information that identify application and user that runs it are defined by Smack label and UID. There are helpers libraries for different IPC. They will make obtaining these information easier. They are described below in credentials section.
There might be a problem, if IPC between application and service do not provide UID and Smack label of application. The only way to obtain application context is probably reading it from /proc/PID (service needs RX to application Smack label for that).
Direct ways of getting these information is described here, but users are strongly recommended to use credential helpers libraries.
Admin API is the only way to change policy kept in Cynara. Its usage needs root privileges on Tizen. This restriction guarantees that no unprivileged process can alter Cynara's policy. In Tizen 3.0, there is a dedicated service Security Manager to make changes to Cynara and probably should be the only user of Cynara's admin interface. Processes that would like to change Cynara policy (e.g. installers) should use libsecurity-manager-client library instead of directly invoking Cynara's admin API.
Plugin API enables creating independent plugin for Cynara extensions. Plugin is a shared library dynamically loaded into Cynara, providing defined by API entry points to create external plugin entity. Plugin API is based on class interfaces, which define methods needed for both client side and service side plugins.
The helper APIs can be used to create:
- client identification strings
- user identification strings
Identification strings are necessary to specify Cynara policies. However, it is important to notice that usage of strings generated by these helper APIs is not obligatory – a different consistent way of client and user process identification strings might be introduced.
The client identification string might be generated based on the client process PID or Smack label. The user identification string might be generated based on the client process UID (user id) or Smack label. The default methods for a system might be obtained by calling cynara_creds_get_default_client_method or cynara_creds_get_default_user_method respectively.
Currently, there are two sets of functions which generate the identification strings. The one is based on DBUS connection, the other is based on Unix socket file descriptors. The connections and socket descriptors are used to obtain the PID, Smack or UID associated with the client or user process.
In addition to the functions generating the identification strings, there are functions returning the PID of the process on the other side of socket/dbus connection. The PID might be used to generate different identification strings.
This helper API can be used to create a client session string identifiers based on PID and time of creation a client process. Session string identifiers are used in in cynara_check() and cynara_async_create_request() functions defined in client libraries. It is important to notice that usage of strings generated by session library APIs is not obligatory – a different consistent way of identifiers generation might be introduced.
Cynara plugins may use external applications (agents) in order to perform some action on privilege check request. Agent API allows communication between plugins and agents.
Monitor API allows real-time auditing of client checks.