root/lib/common/crmcommon_private.h

/* [previous][next][first][last][top][bottom][index][help] */

INCLUDED FROM


DEFINITIONS

This source file includes following definitions.
  1. pcmk__xml_attr_value

   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)
     /* [previous][next][first][last][top][bottom][index][help] */
 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

/* [previous][next][first][last][top][bottom][index][help] */