2 * Copyright (c) 2011 Samsung Electronics Co., Ltd All Rights Reserved
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
8 * http://www.apache.org/licenses/LICENSE-2.0
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
17 * @file ace_api_client.h
18 * @author Tomasz Swierczek (t.swierczek@samsung.com)
20 * @brief This is C api for Access Control Engine (ACE), client mode
24 #ifndef ACE_API_CLIENT_H
25 #define ACE_API_CLIENT_H
27 #include <ace_api_common.h>
34 * API defined in this header should be used only from one thread. If used
35 * otherwise, unexpected behaviour may occur, including segmentation faults and
36 * escalation of global warming. Be warned.
39 // --------------- Initialization and deinitialization -------------------------
42 * Function type that must be implemented externally and passed to ACE
43 * on initialization. This function must show to the user a popup with
44 * information on access request to single device capability. Will be used by
45 * implementation of ace_check_access API, when policy requires to display
48 * Function must be synchronous and must behave accordingly:
50 * Function may return value other than ACE_OK, but it will be treated as
53 * If returned value is ACE_OK, then 'validation_result' must hold information
54 * on whether the access was granted or not.
56 * Executed function must display a popup with readable information presented to
57 * user, covering 'resource_name' that is to be accessed for 'handle' widget
58 * which is requesting the access.
60 * In its implementation, after the user answered to displayed question,
61 * UI handler must call popup answer validation API (ace_validate_answer)
62 * from separate, ace-popup-validation library, with passed 'param_list',
63 * 'session_id', 'handle' and given answer as arguments. Validation result
64 * returned by ace_validate_answer needs to be returned in 'validation_result'
65 * parameter of UI handler.
67 * 'popup_type' describes what kind of options should be given to user - i.e.
68 * ONESHOT prompt only gives possibility to answer Permit/Deny and returned
69 * validity for this prompt must be ONCE. PER_SESSION prompt allows to return
70 * validity ONCE or PER_SESSION. BLANKET prompt allows to return any validity,
71 * as defined in ace_validity_t.
73 * This call must be made from properly SMACK labelled, safe process - otherwise
74 * the validation will not occur in security daemon and caller will not be
75 * granted access to requested device capability.
77 typedef ace_return_t (*ace_popup_handler_func_t)(
78 ace_popup_t popup_type,
79 const ace_resource_t resource_name,
80 const ace_session_id_t session_id,
81 const ace_param_list_t* param_list,
82 ace_widget_handle_t handle,
83 ace_bool_t* validation_result);
86 * Initializes ACE for check access API (client mode). Must be called only once.
87 * Keep in mind that initializing ACE in client mode disallows usage of API
88 * defined in ace_api.h and ace_api_settings.h (RW part).
90 * 'handler' must not be NULL, see definition of ace_popup_handler_func_t for
93 * Returns error or ACE_OK.
95 ace_return_t ace_client_initialize(ace_popup_handler_func_t handler);
98 * Deinitializes ACE client for check access API. Can be called only once.
100 ace_return_t ace_client_shutdown(void);
102 // --------------- Check Access API --------------------------------------------
105 * Does ACE check with set of device capabilities and function parameters.
106 * Checks cache first, if it is non-existent, does full ACE check.
108 * Returns error or ACE_OK and information if access was allowed or not
109 * (value ACE_TRUE or ACE_FALSE is in 'access' argument, only if returned value
110 * is ACE_OK - otherwise, 'access' value is undefined)
112 ace_return_t ace_check_access_ex(const ace_request_t* request, ace_check_result_t* result);
118 #endif // ACE_API_CLIENT_H