ace_client/include/ace_api_client.h

   1 /*
   2  * Copyright (c) 2011 Samsung Electronics Co., Ltd All Rights Reserved
   3  *
   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
   7  *
   8  *        http://www.apache.org/licenses/LICENSE-2.0
   9  *
  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.
  15  */
  16 /*
  17  * @file        ace_api_client.h
  18  * @author      Tomasz Swierczek (t.swierczek@samsung.com)
  19  * @version     1.0
  20  * @brief       This is C api for Access Control Engine (ACE), client mode
  21  *              (RO part).
  22  */
  23
  24 #ifndef ACE_API_CLIENT_H
  25 #define ACE_API_CLIENT_H
  26
  27 #include <ace_api_common.h>
  28
  29 #ifdef __cplusplus
  30 extern "C" {
  31 #endif
  32
  33 /*
  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.
  37  */
  38
  39 // --------------- Initialization and deinitialization -------------------------
  40
  41 /*
  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
  46  * popup.
  47  *
  48  * Function must be synchronous and must behave accordingly:
  49  *
  50  * Function may return value other than ACE_OK, but it will be treated as
  51  * denial of access.
  52  *
  53  * If returned value is ACE_OK, then 'validation_result' must hold information
  54  * on whether the access was granted or not.
  55  *
  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.
  59  *
  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.
  66  *
  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.
  72  *
  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.
  76  */
  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);
  84
  85 /*
  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).
  89  *
  90  * 'handler' must not be NULL, see definition of ace_popup_handler_func_t for
  91  * more information.
  92  *
  93  * Returns error or ACE_OK.
  94  */
  95 ace_return_t ace_client_initialize(ace_popup_handler_func_t handler);
  96
  97 /*
  98  * Deinitializes ACE client for check access API. Can be called only once.
  99  */
 100 ace_return_t ace_client_shutdown(void);
 101
 102 // --------------- Check Access API --------------------------------------------
 103
 104 /*
 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.
 107  *
 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)
 111  */
 112 ace_return_t ace_check_access_ex(const ace_request_t* request, ace_check_result_t* result);
 113
 114 #ifdef __cplusplus
 115 }
 116 #endif
 117
 118 #endif // ACE_API_CLIENT_H