![[first]](../icons/first.png){kind=icon}
![[previous]](../icons/n_left.png){kind=icon}
![[next]](../icons/n_right.png){kind=icon}
![[last]](../icons/n_last.png){kind=icon}
![[top]](../icons/n_top.png){kind=icon}
![[bottom]](../icons/bottom.png){kind=icon}
![[index]](../icons/index.png){kind=icon}
![[help]](../icons/help.png){kind=icon}
*/
1 /*
2 * Copyright 2018-2021 the Pacemaker project contributors
3 *
4 * The version control history for this file may have further details.
5 *
6 * This source code is licensed under the GNU Lesser General Public License
7 * version 2.1 or later (LGPLv2.1+) WITHOUT ANY WARRANTY.
8 */
9
10 #ifndef CRMCOMMON_PRIVATE__H
11 # define CRMCOMMON_PRIVATE__H
12
13 /* This header is for the sole use of libcrmcommon, so that functions can be
14 * declared with G_GNUC_INTERNAL for efficiency.
15 */
16
17 #include <stdint.h> // uint8_t, uint32_t
18 #include <stdbool.h> // bool
19 #include <sys/types.h> // size_t
20 #include <glib.h> // GList
21 #include <libxml/tree.h> // xmlNode, xmlAttr
22 #include <qb/qbipcc.h> // struct qb_ipc_response_header
23
24 // Decent chunk size for processing large amounts of data
25 #define PCMK__BUFFER_SIZE 4096
26
27 /*
28 * XML and ACLs
29 */
30
31 enum xml_private_flags {
32 pcmk__xf_none = 0x0000,
33 pcmk__xf_dirty = 0x0001,
34 pcmk__xf_deleted = 0x0002,
35 pcmk__xf_created = 0x0004,
36 pcmk__xf_modified = 0x0008,
37
38 pcmk__xf_tracking = 0x0010,
39 pcmk__xf_processed = 0x0020,
40 pcmk__xf_skip = 0x0040,
41 pcmk__xf_moved = 0x0080,
42
43 pcmk__xf_acl_enabled = 0x0100,
44 pcmk__xf_acl_read = 0x0200,
45 pcmk__xf_acl_write = 0x0400,
46 pcmk__xf_acl_deny = 0x0800,
47
48 pcmk__xf_acl_create = 0x1000,
49 pcmk__xf_acl_denied = 0x2000,
50 pcmk__xf_lazy = 0x4000,
51 };
52
53 /* When deleting portions of an XML tree, we keep a record so we can know later
54 * (e.g. when checking differences) that something was deleted.
55 */
56 typedef struct pcmk__deleted_xml_s {
57 char *path;
58 int position;
59 } pcmk__deleted_xml_t;
60
61 typedef struct xml_private_s {
62 long check;
63 uint32_t flags;
64 char *user;
65 GList *acls;
66 GList *deleted_objs; // List of pcmk__deleted_xml_t
67 } xml_private_t;
68
69 #define pcmk__set_xml_flags(xml_priv, flags_to_set) do { \
70 (xml_priv)->flags = pcmk__set_flags_as(__func__, __LINE__, \
71 LOG_NEVER, "XML", "XML node", (xml_priv)->flags, \
72 (flags_to_set), #flags_to_set); \
73 } while (0)
74
75 #define pcmk__clear_xml_flags(xml_priv, flags_to_clear) do { \
76 (xml_priv)->flags = pcmk__clear_flags_as(__func__, __LINE__, \
77 LOG_NEVER, "XML", "XML node", (xml_priv)->flags, \
78 (flags_to_clear), #flags_to_clear); \
79 } while (0)
80
81 G_GNUC_INTERNAL
82 void pcmk__xml2text(xmlNode *data, int options, char **buffer, int *offset,
83 int *max, int depth);
84
85 G_GNUC_INTERNAL
86 void pcmk__buffer_add_char(char **buffer, int *offset, int *max, char c);
87
88 G_GNUC_INTERNAL
89 void pcmk__set_xml_doc_flag(xmlNode *xml, enum xml_private_flags flag);
90
91 G_GNUC_INTERNAL
92 bool pcmk__tracking_xml_changes(xmlNode *xml, bool lazy);
93
94 G_GNUC_INTERNAL
95 int pcmk__element_xpath(const char *prefix, xmlNode *xml, char *buffer,
96 int offset, size_t buffer_size);
97
98 G_GNUC_INTERNAL
99 void pcmk__mark_xml_created(xmlNode *xml);
100
101 G_GNUC_INTERNAL
102 int pcmk__xml_position(xmlNode *xml, enum xml_private_flags ignore_if_set);
103
104 G_GNUC_INTERNAL
105 xmlNode *pcmk__xml_match(xmlNode *haystack, xmlNode *needle, bool exact);
106
107 G_GNUC_INTERNAL
108 void pcmk__xe_log(int log_level, const char *file, const char *function,
109 int line, const char *prefix, xmlNode *data, int depth,
110 int options);
111
112 G_GNUC_INTERNAL
113 void pcmk__xml_update(xmlNode *parent, xmlNode *target, xmlNode *update,
114 bool as_diff);
115
116 G_GNUC_INTERNAL
117 xmlNode *pcmk__xc_match(xmlNode *root, xmlNode *search_comment, bool exact);
118
119 G_GNUC_INTERNAL
120 void pcmk__xc_update(xmlNode *parent, xmlNode *target, xmlNode *update);
121
122 G_GNUC_INTERNAL
123 void pcmk__free_acls(GList *acls);
124
125 G_GNUC_INTERNAL
126 void pcmk__unpack_acl(xmlNode *source, xmlNode *target, const char *user);
127
128 G_GNUC_INTERNAL
129 bool pcmk__check_acl(xmlNode *xml, const char *name,
130 enum xml_private_flags mode);
131
132 G_GNUC_INTERNAL
133 void pcmk__apply_acl(xmlNode *xml);
134
135 G_GNUC_INTERNAL
136 void pcmk__apply_creation_acl(xmlNode *xml, bool check_top);
137
138 G_GNUC_INTERNAL
139 void pcmk__mark_xml_attr_dirty(xmlAttr *a);
140
141 G_GNUC_INTERNAL
142 bool pcmk__xa_filterable(const char *name);
143
144 static inline const char *
145 pcmk__xml_attr_value(const xmlAttr *attr)
/* ![[first]](../icons/n_first.png)
![[top]](../icons/top.png)
*/
146 {
147 return ((attr == NULL) || (attr->children == NULL))? NULL
148 : (const char *) attr->children->content;
149 }
150
151 /*
152 * IPC
153 */
154
155 #define PCMK__IPC_VERSION 1
156
157 #define PCMK__CONTROLD_API_MAJOR "1"
158 #define PCMK__CONTROLD_API_MINOR "0"
159
160 // IPC behavior that varies by daemon
161 typedef struct pcmk__ipc_methods_s {
162 /*!
163 * \internal
164 * \brief Allocate any private data needed by daemon IPC
165 *
166 * \param[in] api IPC API connection
167 *
168 * \return Standard Pacemaker return code
169 */
170 int (*new_data)(pcmk_ipc_api_t *api);
171
172 /*!
173 * \internal
174 * \brief Free any private data used by daemon IPC
175 *
176 * \param[in] api_data Data allocated by new_data() method
177 */
178 void (*free_data)(void *api_data);
179
180 /*!
181 * \internal
182 * \brief Perform daemon-specific handling after successful connection
183 *
184 * Some daemons require clients to register before sending any other
185 * commands. The controller requires a CRM_OP_HELLO (with no reply), and
186 * the CIB manager, executor, and fencer require a CRM_OP_REGISTER (with a
187 * reply). Ideally this would be consistent across all daemons, but for now
188 * this allows each to do its own authorization.
189 *
190 * \param[in] api IPC API connection
191 *
192 * \return Standard Pacemaker return code
193 */
194 int (*post_connect)(pcmk_ipc_api_t *api);
195
196 /*!
197 * \internal
198 * \brief Check whether an IPC request results in a reply
199 *
200 * \param[in] api IPC API connection
201 * \param[in] request IPC request XML
202 *
203 * \return true if request would result in an IPC reply, false otherwise
204 */
205 bool (*reply_expected)(pcmk_ipc_api_t *api, xmlNode *request);
206
207 /*!
208 * \internal
209 * \brief Perform daemon-specific handling of an IPC message
210 *
211 * \param[in] api IPC API connection
212 * \param[in] msg Message read from IPC connection
213 */
214 void (*dispatch)(pcmk_ipc_api_t *api, xmlNode *msg);
215
216 /*!
217 * \internal
218 * \brief Perform daemon-specific handling of an IPC disconnect
219 *
220 * \param[in] api IPC API connection
221 */
222 void (*post_disconnect)(pcmk_ipc_api_t *api);
223 } pcmk__ipc_methods_t;
224
225 // Implementation of pcmk_ipc_api_t
226 struct pcmk_ipc_api_s {
227 enum pcmk_ipc_server server; // Daemon this IPC API instance is for
228 enum pcmk_ipc_dispatch dispatch_type; // How replies should be dispatched
229 size_t ipc_size_max; // maximum IPC buffer size
230 crm_ipc_t *ipc; // IPC connection
231 mainloop_io_t *mainloop_io; // If using mainloop, I/O source for IPC
232 bool free_on_disconnect; // Whether disconnect should free object
233 pcmk_ipc_callback_t cb; // Caller-registered callback (if any)
234 void *user_data; // Caller-registered data (if any)
235 void *api_data; // For daemon-specific use
236 pcmk__ipc_methods_t *cmds; // Behavior that varies by daemon
237 };
238
239 typedef struct pcmk__ipc_header_s {
240 struct qb_ipc_response_header qb;
241 uint32_t size_uncompressed;
242 uint32_t size_compressed;
243 uint32_t flags;
244 uint8_t version;
245 } pcmk__ipc_header_t;
246
247 G_GNUC_INTERNAL
248 int pcmk__send_ipc_request(pcmk_ipc_api_t *api, xmlNode *request);
249
250 G_GNUC_INTERNAL
251 void pcmk__call_ipc_callback(pcmk_ipc_api_t *api,
252 enum pcmk_ipc_event event_type,
253 crm_exit_t status, void *event_data);
254
255 G_GNUC_INTERNAL
256 unsigned int pcmk__ipc_buffer_size(unsigned int max);
257
258 G_GNUC_INTERNAL
259 bool pcmk__valid_ipc_header(const pcmk__ipc_header_t *header);
260
261 G_GNUC_INTERNAL
262 pcmk__ipc_methods_t *pcmk__controld_api_methods(void);
263
264 G_GNUC_INTERNAL
265 pcmk__ipc_methods_t *pcmk__pacemakerd_api_methods(void);
266
267
268 /*
269 * Logging
270 */
271
272 /*!
273 * \brief Check the authenticity of the IPC socket peer process
274 *
275 * If everything goes well, peer's authenticity is verified by the means
276 * of comparing against provided referential UID and GID (either satisfies),
277 * and the result of this check can be deduced from the return value.
278 * As an exception, detected UID of 0 ("root") satisfies arbitrary
279 * provided referential daemon's credentials.
280 *
281 * \param[in] qb_ipc libqb client connection if available
282 * \param[in] sock IPC related, connected Unix socket to check peer of
283 * \param[in] refuid referential UID to check against
284 * \param[in] refgid referential GID to check against
285 * \param[out] gotpid to optionally store obtained PID of the peer
286 * (not available on FreeBSD, special value of 1
287 * used instead, and the caller is required to
288 * special case this value respectively)
289 * \param[out] gotuid to optionally store obtained UID of the peer
290 * \param[out] gotgid to optionally store obtained GID of the peer
291 *
292 * \return Standard Pacemaker return code
293 * ie: 0 if it the connection is authentic
294 * pcmk_rc_ipc_unauthorized if the connection is not authentic,
295 * standard errors.
296 *
297 * \note While this function is tolerant on what constitutes authorized
298 * IPC daemon process (its effective user matches UID=0 or \p refuid,
299 * or at least its group matches \p refgid), either or both (in case
300 * of UID=0) mismatches on the expected credentials of such peer
301 * process \e shall be investigated at the caller when value of 1
302 * gets returned there, since higher-than-expected privileges in
303 * respect to the expected/intended credentials possibly violate
304 * the least privilege principle and may pose an additional risk
305 * (i.e. such accidental inconsistency shall be eventually fixed).
306 */
307 int pcmk__crm_ipc_is_authentic_process(qb_ipcc_connection_t *qb_ipc, int sock, uid_t refuid, gid_t refgid,
308 pid_t *gotpid, uid_t *gotuid, gid_t *gotgid);
309
310
311 #endif // CRMCOMMON_PRIVATE__H
![[last]](../icons/last.png){kind=icon}
![[bottom]](../icons/n_bottom.png){kind=icon}
*/