aboutsummaryrefslogtreecommitdiffstats
path: root/compat/include/cynara/cynara-creds-commons.h
blob: 81b97840c5768268b881faf47b46be151c9ad0ae (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
/*
 *  Copyright (c) 2014-2015 Samsung Electronics Co., Ltd All Rights Reserved
 *
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.
 *  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License
 */
/**
 * @file        src/include/cynara-creds-commons.h
 * @author      Lukasz Wojciechowski <l.wojciechow@partner.samsung.com>
 * @author      Radoslaw Bartosiak <r.bartosiak@samsung.com>
 * @author      Aleksander Zdyb <a.zdyb@samsung.com>
 * @author      Oskar Switalski <o.switalski@samsung.com>
 * @version     1.0
 * @brief       This file contains common APIs for Cynara credentials helper.
 */

#ifndef CYNARA_CREDS_COMMONS_H
#define CYNARA_CREDS_COMMONS_H

#include <cynara/cynara-error.h>

enum cynara_client_creds {
    CLIENT_METHOD_SMACK,
    CLIENT_METHOD_PID,

    CLIENT_METHOD_DEFAULT = 0xFFFF,
};

enum cynara_user_creds {
    USER_METHOD_UID,
    USER_METHOD_GID,

    USER_METHOD_DEFAULT = 0xFFFF,
};

#ifdef __cplusplus
extern "C" {
#endif

/**
 * \par Description:
 * Gets the system default method value for client feature used in cynara-creds.
 *
 * \par Purpose:
 * Functions cynara_creds_dbus_get_client() and cynara_creds_socket_get_client() take a method
 * parameter, which determines a kind of process feature (i.e PID, SMACK label) returned by them.
 * The described function provides implementation for obtaining a system default value
 * for this parameter.
 *
 * \par Typical use case:
 * The function might be called before cynara_creds_dbus_get_client()
 * and cynara_creds_socket_get_client(), when functions shall be invoked with system default
 * value of method parameter.
 *
 * \par Method of function operation:
 * When this function is called for the first time it reads and returns the value of client_default
 * parameter from /etc/cynara/creds.conf file.
 * Returned value is cached so subsequent calls will not consult file again but use cached value.
 * This also means that after the initial call any changes in the file will be ignored for the
 * remaining lifetime of the process.
 *
 * \par Sync (or) Async:
 * This is a synchronous API.
 *
 * \par Thread safety:
 * This function is thread-safe.
 *
 * \param[out] method Placeholder for system default client feature
 *                     (like CLIENT_METHOD_SMACK, CLIENT_METHOD_PID)
 *
 * \return CYNARA_API_SUCCESS on success
 * \return CYNARA_API_CONFIGURATION_ERROR if the configuration file can not be opened or
 *                                        there are errors in configuration file
 * \return CYNARA_API_OUT_OF_MEMORY if there is error in memory allocation
 * \return CYNARA_API_UNKNOWN_ERROR if there is other error
 *
 */
int cynara_creds_get_default_client_method(enum cynara_client_creds *method);

/**
 * \par Description:
 * Gets the system default method value for user feature used in cynara-creds.
 *
 * \par Purpose:
 * Functions cynara_creds_dbus_get_user() and cynara_creds_socket_get_user() take a method
 * parameter, which determines a kind of process feature (i.e UID, GID) returned by them.
 * The described function provides implementation for obtaining a system default value
 * for this parameter.
 *
 * \par Typical use case:
 * The function might be called before cynara_creds_dbus_get_user()
 * and cynara_creds_socket_get_user() when functions shall be invoked with system default
 * value of method parameter.
 *
 * \par Method of function operation:
 * When this function is called for the first time it reads and returns the value of user_default
 * parameter from /etc/cynara/creds.conf file.
 * Returned value is cached so subsequent calls will not consult file again but use cached value.
 * This also means that after the initial call any changes in the file will be ignored for the
 * remaining lifetime of the process.
 *
 * \par Sync (or) Async:
 * This is a synchronous API.
 *
 * \par Thread safety:
 * This function is thread-safe.
 *
 * \param[out] method Placeholder for system default user feature
 * (like USER_METHOD_UID, USER_METHOD_GID)
 *
 * \return CYNARA_API_SUCCESS on success
 * \return CYNARA_API_CONFIGURATION_ERROR if the configuration file can not be opened or
 *                                        there are errors in configuration file
 * \return CYNARA_API_OUT_OF_MEMORY if there is error in memory allocation
 * \return CYNARA_API_UNKNOWN_ERROR if there is other error
 */
int cynara_creds_get_default_user_method(enum cynara_user_creds *method);

#ifdef __cplusplus
}
#endif

#endif /* CYNARA_CREDS_COMMONS_H */