src/libsystemd/sd-bus/kdbus.h

   1 /*
   2  * kdbus is free software; you can redistribute it and/or modify it under
   3  * the terms of the GNU Lesser General Public License as published by the
   4  * Free Software Foundation; either version 2.1 of the License, or (at
   5  * your option) any later version.
   6  */
   7
   8 #ifndef _KDBUS_UAPI_H_
   9 #define _KDBUS_UAPI_H_
  10
  11 #include <linux/ioctl.h>
  12 #include <linux/types.h>
  13
  14 #define KDBUS_IOCTL_MAGIC               0x95
  15 #define KDBUS_SRC_ID_KERNEL             (0)
  16 #define KDBUS_DST_ID_NAME               (0)
  17 #define KDBUS_MATCH_ID_ANY              (~0ULL)
  18 #define KDBUS_DST_ID_BROADCAST          (~0ULL)
  19 #define KDBUS_FLAG_KERNEL               (1ULL << 63)
  20
  21 /**
  22  * struct kdbus_notify_id_change - name registry change message
  23  * @id:                 New or former owner of the name
  24  * @flags:              flags field from KDBUS_HELLO_*
  25  *
  26  * Sent from kernel to userspace when the owner or activator of
  27  * a well-known name changes.
  28  *
  29  * Attached to:
  30  *   KDBUS_ITEM_ID_ADD
  31  *   KDBUS_ITEM_ID_REMOVE
  32  */
  33 struct kdbus_notify_id_change {
  34         __u64 id;
  35         __u64 flags;
  36 };
  37
  38 /**
  39  * struct kdbus_notify_name_change - name registry change message
  40  * @old_id:             ID and flags of former owner of a name
  41  * @new_id:             ID and flags of new owner of a name
  42  * @name:               Well-known name
  43  *
  44  * Sent from kernel to userspace when the owner or activator of
  45  * a well-known name changes.
  46  *
  47  * Attached to:
  48  *   KDBUS_ITEM_NAME_ADD
  49  *   KDBUS_ITEM_NAME_REMOVE
  50  *   KDBUS_ITEM_NAME_CHANGE
  51  */
  52 struct kdbus_notify_name_change {
  53         struct kdbus_notify_id_change old_id;
  54         struct kdbus_notify_id_change new_id;
  55         char name[0];
  56 };
  57
  58 /**
  59  * struct kdbus_creds - process credentials
  60  * @uid:                User ID
  61  * @euid:               Effective UID
  62  * @suid:               Saved UID
  63  * @fsuid:              Filesystem UID
  64  * @gid:                Group ID
  65  * @egid:               Effective GID
  66  * @sgid:               Saved GID
  67  * @fsgid:              Filesystem GID
  68  *
  69  * Attached to:
  70  *   KDBUS_ITEM_CREDS
  71  */
  72 struct kdbus_creds {
  73         __u32 uid;
  74         __u32 euid;
  75         __u32 suid;
  76         __u32 fsuid;
  77         __u32 gid;
  78         __u32 egid;
  79         __u32 sgid;
  80         __u32 fsgid;
  81 };
  82
  83 /**
  84  * struct kdbus_pids - process identifiers
  85  * @pid:                Process ID
  86  * @tid:                Thread ID
  87  * @starttime:          Starttime of the process
  88  *
  89  * The PID, TID and starttime of a process. The start tmie is useful to detect
  90  * PID overruns from the client side. i.e. if you use the PID to look something
  91  * up in /proc/$PID/ you can afterwards check the starttime field of it, to
  92  * ensure you didn't run into a PID overrun.
  93  *
  94  * Attached to:
  95  *   KDBUS_ITEM_PIDS
  96  */
  97 struct kdbus_pids {
  98         __u64 pid;
  99         __u64 tid;
 100         __u64 starttime;
 101 };
 102
 103 /**
 104  * struct kdbus_caps - process capabilities
 105  * @last_cap:   Highest currently known capability bit
 106  * @caps:       Variable number of 32-bit capabilities flags
 107  *
 108  * Contains a variable number of 32-bit capabilities flags.
 109  *
 110  * Attached to:
 111  *   KDBUS_ITEM_CAPS
 112  */
 113 struct kdbus_caps {
 114         __u32 last_cap;
 115         __u32 caps[0];
 116 };
 117
 118 /**
 119  * struct kdbus_audit - audit information
 120  * @sessionid:          The audit session ID
 121  * @loginuid:           The audit login uid
 122  *
 123  * Attached to:
 124  *   KDBUS_ITEM_AUDIT
 125  */
 126 struct kdbus_audit {
 127         __u64 sessionid;
 128         __u64 loginuid;
 129 };
 130
 131 /**
 132  * struct kdbus_timestamp
 133  * @seqnum:             Global per-domain message sequence number
 134  * @monotonic_ns:       Monotonic timestamp, in nanoseconds
 135  * @realtime_ns:        Realtime timestamp, in nanoseconds
 136  *
 137  * Attached to:
 138  *   KDBUS_ITEM_TIMESTAMP
 139  */
 140 struct kdbus_timestamp {
 141         __u64 seqnum;
 142         __u64 monotonic_ns;
 143         __u64 realtime_ns;
 144 };
 145
 146 /**
 147  * struct kdbus_vec - I/O vector for kdbus payload items
 148  * @size:               The size of the vector
 149  * @address:            Memory address of data buffer
 150  * @offset:             Offset in the in-message payload memory,
 151  *                      relative to the message head
 152  *
 153  * Attached to:
 154  *   KDBUS_ITEM_PAYLOAD_VEC, KDBUS_ITEM_PAYLOAD_OFF
 155  */
 156 struct kdbus_vec {
 157         __u64 size;
 158         union {
 159                 __u64 address;
 160                 __u64 offset;
 161         };
 162 };
 163
 164 /**
 165  * struct kdbus_bloom_parameter - bus-wide bloom parameters
 166  * @size:               Size of the bit field in bytes (m / 8)
 167  * @n_hash:             Number of hash functions used (k)
 168  */
 169 struct kdbus_bloom_parameter {
 170         __u64 size;
 171         __u64 n_hash;
 172 };
 173
 174 /**
 175  * struct kdbus_bloom_filter - bloom filter containing n elements
 176  * @generation:         Generation of the element set in the filter
 177  * @data:               Bit field, multiple of 8 bytes
 178  */
 179 struct kdbus_bloom_filter {
 180         __u64 generation;
 181         __u64 data[0];
 182 };
 183
 184 /**
 185  * struct kdbus_memfd - a kdbus memfd
 186  * @size:               The memfd's size
 187  * @fd:                 The file descriptor number
 188  * @__pad:              Padding to ensure proper alignment and size
 189  *
 190  * Attached to:
 191  *   KDBUS_ITEM_PAYLOAD_MEMFD
 192  */
 193 struct kdbus_memfd {
 194         __u64 size;
 195         int fd;
 196         __u32 __pad;
 197 };
 198
 199 /**
 200  * struct kdbus_name - a registered well-known name with its flags
 201  * @flags:              Flags from KDBUS_NAME_*
 202  * @name:               Well-known name
 203  *
 204  * Attached to:
 205  *   KDBUS_ITEM_OWNED_NAME
 206  */
 207 struct kdbus_name {
 208         __u64 flags;
 209         char name[0];
 210 };
 211
 212 /**
 213  * struct kdbus_policy_access - policy access item
 214  * @type:               One of KDBUS_POLICY_ACCESS_* types
 215  * @access:             Access to grant
 216  * @id:                 For KDBUS_POLICY_ACCESS_USER, the uid
 217  *                      For KDBUS_POLICY_ACCESS_GROUP, the gid
 218  */
 219 struct kdbus_policy_access {
 220         __u64 type;     /* USER, GROUP, WORLD */
 221         __u64 access;   /* OWN, TALK, SEE */
 222         __u64 id;       /* uid, gid, 0 */
 223 };
 224
 225 /**
 226  * enum kdbus_item_type - item types to chain data in a list
 227  * @_KDBUS_ITEM_NULL:                   Uninitialized/invalid
 228  * @_KDBUS_ITEM_USER_BASE:              Start of user items
 229  * @KDBUS_ITEM_PAYLOAD_VEC:             Vector to data
 230  * @KDBUS_ITEM_PAYLOAD_OFF:             Data at returned offset to message head
 231  * @KDBUS_ITEM_PAYLOAD_MEMFD:           Data as sealed memfd
 232  * @KDBUS_ITEM_FDS:                     Attached file descriptors
 233  * @KDBUS_ITEM_BLOOM_PARAMETER:         Bus-wide bloom parameters, used with
 234  *                                      KDBUS_CMD_BUS_MAKE, carries a
 235  *                                      struct kdbus_bloom_parameter
 236  * @KDBUS_ITEM_BLOOM_FILTER:            Bloom filter carried with a message,
 237  *                                      used to match against a bloom mask of a
 238  *                                      connection, carries a struct
 239  *                                      kdbus_bloom_filter
 240  * @KDBUS_ITEM_BLOOM_MASK:              Bloom mask used to match against a
 241  *                                      message'sbloom filter
 242  * @KDBUS_ITEM_DST_NAME:                Destination's well-known name
 243  * @KDBUS_ITEM_MAKE_NAME:               Name of domain, bus, endpoint
 244  * @KDBUS_ITEM_ATTACH_FLAGS_SEND:       Attach-flags, used for updating which
 245  *                                      metadata a connection opts in to send
 246  * @KDBUS_ITEM_ATTACH_FLAGS_RECV:       Attach-flags, used for updating which
 247  *                                      metadata a connection requests to
 248  *                                      receive for each reeceived message
 249  * @KDBUS_ITEM_ID:                      Connection ID
 250  * @KDBUS_ITEM_NAME:                    Well-know name with flags
 251  * @_KDBUS_ITEM_ATTACH_BASE:            Start of metadata attach items
 252  * @KDBUS_ITEM_TIMESTAMP:               Timestamp
 253  * @KDBUS_ITEM_CREDS:                   Process credentials
 254  * @KDBUS_ITEM_PIDS:                    Process identifiers
 255  * @KDBUS_ITEM_AUXGROUPS:               Auxiliary process groups
 256  * @KDBUS_ITEM_OWNED_NAME:              A name owned by the associated
 257  *                                      connection
 258  * @KDBUS_ITEM_TID_COMM:                Thread ID "comm" identifier
 259  *                                      (Don't trust this, see below.)
 260  * @KDBUS_ITEM_PID_COMM:                Process ID "comm" identifier
 261  *                                      (Don't trust this, see below.)
 262  * @KDBUS_ITEM_EXE:                     The path of the executable
 263  *                                      (Don't trust this, see below.)
 264  * @KDBUS_ITEM_CMDLINE:                 The process command line
 265  *                                      (Don't trust this, see below.)
 266  * @KDBUS_ITEM_CGROUP:                  The croup membership
 267  * @KDBUS_ITEM_CAPS:                    The process capabilities
 268  * @KDBUS_ITEM_SECLABEL:                The security label
 269  * @KDBUS_ITEM_AUDIT:                   The audit IDs
 270  * @KDBUS_ITEM_CONN_DESCRIPTION:        The connection's human-readable name
 271  *                                      (debugging)
 272  * @_KDBUS_ITEM_POLICY_BASE:            Start of policy items
 273  * @KDBUS_ITEM_POLICY_ACCESS:           Policy access block
 274  * @_KDBUS_ITEM_KERNEL_BASE:            Start of kernel-generated message items
 275  * @KDBUS_ITEM_NAME_ADD:                Notification in kdbus_notify_name_change
 276  * @KDBUS_ITEM_NAME_REMOVE:             Notification in kdbus_notify_name_change
 277  * @KDBUS_ITEM_NAME_CHANGE:             Notification in kdbus_notify_name_change
 278  * @KDBUS_ITEM_ID_ADD:                  Notification in kdbus_notify_id_change
 279  * @KDBUS_ITEM_ID_REMOVE:               Notification in kdbus_notify_id_change
 280  * @KDBUS_ITEM_REPLY_TIMEOUT:           Timeout has been reached
 281  * @KDBUS_ITEM_REPLY_DEAD:              Destination died
 282  *
 283  * N.B: The process and thread COMM fields, as well as the CMDLINE and
 284  * EXE fields may be altered by unprivileged processes und should
 285  * hence *not* used for security decisions. Peers should make use of
 286  * these items only for informational purposes, such as generating log
 287  * records.
 288  */
 289 enum kdbus_item_type {
 290         _KDBUS_ITEM_NULL,
 291         _KDBUS_ITEM_USER_BASE,
 292         KDBUS_ITEM_PAYLOAD_VEC  = _KDBUS_ITEM_USER_BASE,
 293         KDBUS_ITEM_PAYLOAD_OFF,
 294         KDBUS_ITEM_PAYLOAD_MEMFD,
 295         KDBUS_ITEM_FDS,
 296         KDBUS_ITEM_BLOOM_PARAMETER,
 297         KDBUS_ITEM_BLOOM_FILTER,
 298         KDBUS_ITEM_BLOOM_MASK,
 299         KDBUS_ITEM_DST_NAME,
 300         KDBUS_ITEM_MAKE_NAME,
 301         KDBUS_ITEM_ATTACH_FLAGS_SEND,
 302         KDBUS_ITEM_ATTACH_FLAGS_RECV,
 303         KDBUS_ITEM_ID,
 304         KDBUS_ITEM_NAME,
 305
 306         /* keep these item types in sync with KDBUS_ATTACH_* flags */
 307         _KDBUS_ITEM_ATTACH_BASE = 0x1000,
 308         KDBUS_ITEM_TIMESTAMP    = _KDBUS_ITEM_ATTACH_BASE,
 309         KDBUS_ITEM_CREDS,
 310         KDBUS_ITEM_PIDS,
 311         KDBUS_ITEM_AUXGROUPS,
 312         KDBUS_ITEM_OWNED_NAME,
 313         KDBUS_ITEM_TID_COMM,
 314         KDBUS_ITEM_PID_COMM,
 315         KDBUS_ITEM_EXE,
 316         KDBUS_ITEM_CMDLINE,
 317         KDBUS_ITEM_CGROUP,
 318         KDBUS_ITEM_CAPS,
 319         KDBUS_ITEM_SECLABEL,
 320         KDBUS_ITEM_AUDIT,
 321         KDBUS_ITEM_CONN_DESCRIPTION,
 322
 323         _KDBUS_ITEM_POLICY_BASE = 0x2000,
 324         KDBUS_ITEM_POLICY_ACCESS = _KDBUS_ITEM_POLICY_BASE,
 325
 326         _KDBUS_ITEM_KERNEL_BASE = 0x8000,
 327         KDBUS_ITEM_NAME_ADD     = _KDBUS_ITEM_KERNEL_BASE,
 328         KDBUS_ITEM_NAME_REMOVE,
 329         KDBUS_ITEM_NAME_CHANGE,
 330         KDBUS_ITEM_ID_ADD,
 331         KDBUS_ITEM_ID_REMOVE,
 332         KDBUS_ITEM_REPLY_TIMEOUT,
 333         KDBUS_ITEM_REPLY_DEAD,
 334 };
 335
 336 /**
 337  * struct kdbus_item - chain of data blocks
 338  * @size:               Overall data record size
 339  * @type:               Kdbus_item type of data
 340  * @data:               Generic bytes
 341  * @data32:             Generic 32 bit array
 342  * @data64:             Generic 64 bit array
 343  * @str:                Generic string
 344  * @id:                 Connection ID
 345  * @vec:                KDBUS_ITEM_PAYLOAD_VEC
 346  * @creds:              KDBUS_ITEM_CREDS
 347  * @audit:              KDBUS_ITEM_AUDIT
 348  * @timestamp:          KDBUS_ITEM_TIMESTAMP
 349  * @name:               KDBUS_ITEM_NAME
 350  * @bloom_parameter:    KDBUS_ITEM_BLOOM_PARAMETER
 351  * @bloom_filter:       KDBUS_ITEM_BLOOM_FILTER
 352  * @memfd:              KDBUS_ITEM_PAYLOAD_MEMFD
 353  * @name_change:        KDBUS_ITEM_NAME_ADD
 354  *                      KDBUS_ITEM_NAME_REMOVE
 355  *                      KDBUS_ITEM_NAME_CHANGE
 356  * @id_change:          KDBUS_ITEM_ID_ADD
 357  *                      KDBUS_ITEM_ID_REMOVE
 358  * @policy:             KDBUS_ITEM_POLICY_ACCESS
 359  */
 360 struct kdbus_item {
 361         __u64 size;
 362         __u64 type;
 363         union {
 364                 __u8 data[0];
 365                 __u32 data32[0];
 366                 __u64 data64[0];
 367                 char str[0];
 368
 369                 __u64 id;
 370                 struct kdbus_vec vec;
 371                 struct kdbus_creds creds;
 372                 struct kdbus_pids pids;
 373                 struct kdbus_audit audit;
 374                 struct kdbus_caps caps;
 375                 struct kdbus_timestamp timestamp;
 376                 struct kdbus_name name;
 377                 struct kdbus_bloom_parameter bloom_parameter;
 378                 struct kdbus_bloom_filter bloom_filter;
 379                 struct kdbus_memfd memfd;
 380                 int fds[0];
 381                 struct kdbus_notify_name_change name_change;
 382                 struct kdbus_notify_id_change id_change;
 383                 struct kdbus_policy_access policy_access;
 384         };
 385 };
 386
 387 /**
 388  * enum kdbus_msg_flags - type of message
 389  * @KDBUS_MSG_FLAGS_EXPECT_REPLY:       Expect a reply message, used for
 390  *                                      method calls. The userspace-supplied
 391  *                                      cookie identifies the message and the
 392  *                                      respective reply carries the cookie
 393  *                                      in cookie_reply
 394  * @KDBUS_MSG_FLAGS_SYNC_REPLY:         Wait for destination connection to
 395  *                                      reply to this message. The
 396  *                                      KDBUS_CMD_MSG_SEND ioctl() will block
 397  *                                      until the reply is received, and
 398  *                                      offset_reply in struct kdbus_msg will
 399  *                                      yield the offset in the sender's pool
 400  *                                      where the reply can be found.
 401  *                                      This flag is only valid if
 402  *                                      @KDBUS_MSG_FLAGS_EXPECT_REPLY is set as
 403  *                                      well.
 404  * @KDBUS_MSG_FLAGS_NO_AUTO_START:      Do not start a service, if the addressed
 405  *                                      name is not currently active
 406  */
 407 enum kdbus_msg_flags {
 408         KDBUS_MSG_FLAGS_EXPECT_REPLY    = 1ULL << 0,
 409         KDBUS_MSG_FLAGS_SYNC_REPLY      = 1ULL << 1,
 410         KDBUS_MSG_FLAGS_NO_AUTO_START   = 1ULL << 2,
 411 };
 412
 413 /**
 414  * enum kdbus_payload_type - type of payload carried by message
 415  * @KDBUS_PAYLOAD_KERNEL:       Kernel-generated simple message
 416  * @KDBUS_PAYLOAD_DBUS:         D-Bus marshalling "DBusDBus"
 417  */
 418 enum kdbus_payload_type {
 419         KDBUS_PAYLOAD_KERNEL,
 420         KDBUS_PAYLOAD_DBUS      = 0x4442757344427573ULL,
 421 };
 422
 423 /**
 424  * struct kdbus_msg - the representation of a kdbus message
 425  * @size:               Total size of the message
 426  * @flags:              Message flags (KDBUS_MSG_FLAGS_*), userspace → kernel
 427  * @kernel_flags:       Supported message flags, kernel → userspace
 428  * @priority:           Message queue priority value
 429  * @dst_id:             64-bit ID of the destination connection
 430  * @src_id:             64-bit ID of the source connection
 431  * @payload_type:       Payload type (KDBUS_PAYLOAD_*)
 432  * @cookie:             Userspace-supplied cookie, for the connection
 433  *                      to identify its messages
 434  * @timeout_ns:         The time to wait for a message reply from the peer.
 435  *                      If there is no reply, a kernel-generated message
 436  *                      with an attached KDBUS_ITEM_REPLY_TIMEOUT item
 437  *                      is sent to @src_id. The timeout is expected in
 438  *                      nanoseconds and as absolute CLOCK_MONOTONIC value.
 439  * @cookie_reply:       A reply to the requesting message with the same
 440  *                      cookie. The requesting connection can match its
 441  *                      request and the reply with this value
 442  * @offset_reply:       If KDBUS_MSG_FLAGS_EXPECT_REPLY, this field will
 443  *                      contain the offset in the sender's pool where the
 444  *                      reply is stored.
 445  * @items:              A list of kdbus_items containing the message payload
 446  */
 447 struct kdbus_msg {
 448         __u64 size;
 449         __u64 flags;
 450         __u64 kernel_flags;
 451         __s64 priority;
 452         __u64 dst_id;
 453         __u64 src_id;
 454         __u64 payload_type;
 455         __u64 cookie;
 456         union {
 457                 __u64 timeout_ns;
 458                 __u64 cookie_reply;
 459                 __u64 offset_reply;
 460         };
 461         struct kdbus_item items[0];
 462 } __attribute__((aligned(8)));
 463
 464 /**
 465  * enum kdbus_recv_flags - flags for de-queuing messages
 466  * @KDBUS_RECV_PEEK:            Return the next queued message without
 467  *                              actually de-queuing it, and without installing
 468  *                              any file descriptors or other resources. It is
 469  *                              usually used to determine the activating
 470  *                              connection of a bus name.
 471  * @KDBUS_RECV_DROP:            Drop and free the next queued message and all
 472  *                              its resources without actually receiving it.
 473  * @KDBUS_RECV_USE_PRIORITY:    Only de-queue messages with the specified or
 474  *                              higher priority (lowest values); if not set,
 475  *                              the priority value is ignored.
 476  */
 477 enum kdbus_recv_flags {
 478         KDBUS_RECV_PEEK         = 1ULL <<  0,
 479         KDBUS_RECV_DROP         = 1ULL <<  1,
 480         KDBUS_RECV_USE_PRIORITY = 1ULL <<  2,
 481 };
 482
 483 /**
 484  * struct kdbus_cmd_recv - struct to de-queue a buffered message
 485  * @flags:              KDBUS_RECV_* flags, userspace → kernel
 486  * @kernel_flags:       Supported KDBUS_RECV_* flags, kernel → userspace
 487  * @priority:           Minimum priority of the messages to de-queue. Lowest
 488  *                      values have the highest priority.
 489  * @offset:             Returned offset in the pool where the message is
 490  *                      stored. The user must use KDBUS_CMD_FREE to free
 491  *                      the allocated memory.
 492  * @dropped_msgs:       In case the KDBUS_CMD_MSG_RECV ioctl returns
 493  *                      -EOVERFLOW, this field will contain the number of
 494  *                      broadcast messages that have been lost since the
 495  *                      last call.
 496  * @msg_size:           Filled by the kernel with the actual message size. This
 497  *                      is the full size of the slice placed at @offset. It
 498  *                      includes the memory used for the kdbus_msg object, but
 499  *                      also for all appended VECs. By using @msg_size and
 500  *                      @offset, you can map a single message, instead of
 501  *                      mapping the whole pool.
 502  *
 503  * This struct is used with the KDBUS_CMD_MSG_RECV ioctl.
 504  */
 505 struct kdbus_cmd_recv {
 506         __u64 flags;
 507         __u64 kernel_flags;
 508         __s64 priority;
 509         union {
 510                 __u64 offset;
 511                 __u64 dropped_msgs;
 512         };
 513         __u64 msg_size;
 514 } __attribute__((aligned(8)));
 515
 516 /**
 517  * struct kdbus_cmd_cancel - struct to cancel a synchronously pending message
 518  * @cookie:             The cookie of the pending message
 519  * @flags:              Flags for the free command. Currently unused.
 520  *
 521  * This struct is used with the KDBUS_CMD_CANCEL ioctl.
 522  */
 523 struct kdbus_cmd_cancel {
 524         __u64 cookie;
 525         __u64 flags;
 526 } __attribute__((aligned(8)));
 527
 528 /**
 529  * struct kdbus_cmd_free - struct to free a slice of memory in the pool
 530  * @offset:             The offset of the memory slice, as returned by other
 531  *                      ioctls
 532  * @flags:              Flags for the free command, userspace → kernel
 533  * @kernel_flags:       Supported flags of the free command, userspace → kernel
 534  *
 535  * This struct is used with the KDBUS_CMD_FREE ioctl.
 536  */
 537 struct kdbus_cmd_free {
 538         __u64 offset;
 539         __u64 flags;
 540         __u64 kernel_flags;
 541 } __attribute__((aligned(8)));
 542
 543 /**
 544  * enum kdbus_policy_access_type - permissions of a policy record
 545  * @_KDBUS_POLICY_ACCESS_NULL:  Uninitialized/invalid
 546  * @KDBUS_POLICY_ACCESS_USER:   Grant access to a uid
 547  * @KDBUS_POLICY_ACCESS_GROUP:  Grant access to gid
 548  * @KDBUS_POLICY_ACCESS_WORLD:  World-accessible
 549  */
 550 enum kdbus_policy_access_type {
 551         _KDBUS_POLICY_ACCESS_NULL,
 552         KDBUS_POLICY_ACCESS_USER,
 553         KDBUS_POLICY_ACCESS_GROUP,
 554         KDBUS_POLICY_ACCESS_WORLD,
 555 };
 556
 557 /**
 558  * enum kdbus_policy_access_flags - mode flags
 559  * @KDBUS_POLICY_OWN:           Allow to own a well-known name
 560  *                              Implies KDBUS_POLICY_TALK and KDBUS_POLICY_SEE
 561  * @KDBUS_POLICY_TALK:          Allow communication to a well-known name
 562  *                              Implies KDBUS_POLICY_SEE
 563  * @KDBUS_POLICY_SEE:           Allow to see a well-known name
 564  */
 565 enum kdbus_policy_type {
 566         KDBUS_POLICY_SEE        = 0,
 567         KDBUS_POLICY_TALK,
 568         KDBUS_POLICY_OWN,
 569 };
 570
 571 /**
 572  * enum kdbus_hello_flags - flags for struct kdbus_cmd_hello
 573  * @KDBUS_HELLO_ACCEPT_FD:      The connection allows the reception of
 574  *                              any passed file descriptors
 575  * @KDBUS_HELLO_ACTIVATOR:      Special-purpose connection which registers
 576  *                              a well-know name for a process to be started
 577  *                              when traffic arrives
 578  * @KDBUS_HELLO_POLICY_HOLDER:  Special-purpose connection which registers
 579  *                              policy entries for a name. The provided name
 580  *                              is not activated and not registered with the
 581  *                              name database, it only allows unprivileged
 582  *                              connections to aquire a name, talk or discover
 583  *                              a service
 584  * @KDBUS_HELLO_MONITOR:        Special-purpose connection to monitor
 585  *                              bus traffic
 586  */
 587 enum kdbus_hello_flags {
 588         KDBUS_HELLO_ACCEPT_FD           =  1ULL <<  0,
 589         KDBUS_HELLO_ACTIVATOR           =  1ULL <<  1,
 590         KDBUS_HELLO_POLICY_HOLDER       =  1ULL <<  2,
 591         KDBUS_HELLO_MONITOR             =  1ULL <<  3,
 592 };
 593
 594 /**
 595  * enum kdbus_attach_flags - flags for metadata attachments
 596  * @KDBUS_ATTACH_TIMESTAMP:             Timestamp
 597  * @KDBUS_ATTACH_CREDS:                 Credentials
 598  * @KDBUS_ATTACH_PIDS:                  PIDs
 599  * @KDBUS_ATTACH_AUXGROUPS:             Auxiliary groups
 600  * @KDBUS_ATTACH_NAMES:                 Well-known names
 601  * @KDBUS_ATTACH_TID_COMM:              The "comm" process identifier of the TID
 602  * @KDBUS_ATTACH_PID_COMM:              The "comm" process identifier of the PID
 603  * @KDBUS_ATTACH_EXE:                   The path of the executable
 604  * @KDBUS_ATTACH_CMDLINE:               The process command line
 605  * @KDBUS_ATTACH_CGROUP:                The croup membership
 606  * @KDBUS_ATTACH_CAPS:                  The process capabilities
 607  * @KDBUS_ATTACH_SECLABEL:              The security label
 608  * @KDBUS_ATTACH_AUDIT:                 The audit IDs
 609  * @KDBUS_ATTACH_CONN_DESCRIPTION:      The human-readable connection name
 610  * @_KDBUS_ATTACH_ALL:                  All of the above
 611  * @_KDBUS_ATTACH_ANY:                  Wildcard match to enable any kind of
 612  *                                      metatdata.
 613  */
 614 enum kdbus_attach_flags {
 615         KDBUS_ATTACH_TIMESTAMP          =  1ULL <<  0,
 616         KDBUS_ATTACH_CREDS              =  1ULL <<  1,
 617         KDBUS_ATTACH_PIDS               =  1ULL <<  2,
 618         KDBUS_ATTACH_AUXGROUPS          =  1ULL <<  3,
 619         KDBUS_ATTACH_NAMES              =  1ULL <<  4,
 620         KDBUS_ATTACH_TID_COMM           =  1ULL <<  5,
 621         KDBUS_ATTACH_PID_COMM           =  1ULL <<  6,
 622         KDBUS_ATTACH_EXE                =  1ULL <<  7,
 623         KDBUS_ATTACH_CMDLINE            =  1ULL <<  8,
 624         KDBUS_ATTACH_CGROUP             =  1ULL <<  9,
 625         KDBUS_ATTACH_CAPS               =  1ULL << 10,
 626         KDBUS_ATTACH_SECLABEL           =  1ULL << 11,
 627         KDBUS_ATTACH_AUDIT              =  1ULL << 12,
 628         KDBUS_ATTACH_CONN_DESCRIPTION   =  1ULL << 13,
 629         _KDBUS_ATTACH_ALL               =  (1ULL << 14) - 1,
 630         _KDBUS_ATTACH_ANY               =  ~0ULL
 631 };
 632
 633 /**
 634  * struct kdbus_cmd_hello - struct to say hello to kdbus
 635  * @size:               The total size of the structure
 636  * @flags:              Connection flags (KDBUS_HELLO_*), userspace → kernel
 637  * @kernel_flags:       Supported connection flags, kernel → userspace
 638  * @attach_flags_send:  Mask of metadata to attach to each message sent
 639  *                      off by this connection (KDBUS_ATTACH_*)
 640  * @attach_flags_recv:  Mask of metadata to attach to each message receieved
 641  *                      by the new connection (KDBUS_ATTACH_*)
 642  * @bus_flags:          The flags field copied verbatim from the original
 643  *                      KDBUS_CMD_BUS_MAKE ioctl. It's intended to be useful
 644  *                      to do negotiation of features of the payload that is
 645  *                      transferred (kernel → userspace)
 646  * @id:                 The ID of this connection (kernel → userspace)
 647  * @pool_size:          Size of the connection's buffer where the received
 648  *                      messages are placed
 649  * @bloom:              The bloom properties of the bus, specified
 650  *                      by the bus creator (kernel → userspace)
 651  * @id128:              Unique 128-bit ID of the bus (kernel → userspace)
 652  * @items:              A list of items
 653  *
 654  * This struct is used with the KDBUS_CMD_HELLO ioctl.
 655  */
 656 struct kdbus_cmd_hello {
 657         __u64 size;
 658         __u64 flags;
 659         __u64 kernel_flags;
 660         __u64 attach_flags_send;
 661         __u64 attach_flags_recv;
 662         __u64 bus_flags;
 663         __u64 id;
 664         __u64 pool_size;
 665         struct kdbus_bloom_parameter bloom;
 666         __u8 id128[16];
 667         struct kdbus_item items[0];
 668 } __attribute__((aligned(8)));
 669
 670 /**
 671  * enum kdbus_make_flags - Flags for KDBUS_CMD_{BUS,EP,NS}_MAKE
 672  * @KDBUS_MAKE_ACCESS_GROUP:    Make the bus or endpoint node group-accessible
 673  * @KDBUS_MAKE_ACCESS_WORLD:    Make the bus or endpoint node world-accessible
 674  */
 675 enum kdbus_make_flags {
 676         KDBUS_MAKE_ACCESS_GROUP         = 1ULL <<  0,
 677         KDBUS_MAKE_ACCESS_WORLD         = 1ULL <<  1,
 678 };
 679
 680 /**
 681  * struct kdbus_cmd_make - struct to make a bus, an endpoint or a domain
 682  * @size:               The total size of the struct
 683  * @flags:              Properties for the bus/ep/domain to create,
 684  *                      userspace → kernel
 685  * @kernel_flags:       Supported flags for the used command, kernel → userspace
 686  * @items:              Items describing details
 687  *
 688  * This structure is used with the KDBUS_CMD_BUS_MAKE and
 689  * KDBUS_CMD_ENDPOINT_MAKE ioctls.
 690  */
 691 struct kdbus_cmd_make {
 692         __u64 size;
 693         __u64 flags;
 694         __u64 kernel_flags;
 695         struct kdbus_item items[0];
 696 } __attribute__((aligned(8)));
 697
 698 /**
 699  * enum kdbus_name_flags - properties of a well-known name
 700  * @KDBUS_NAME_REPLACE_EXISTING:        Try to replace name of other connections
 701  * @KDBUS_NAME_ALLOW_REPLACEMENT:       Allow the replacement of the name
 702  * @KDBUS_NAME_QUEUE:                   Name should be queued if busy
 703  * @KDBUS_NAME_IN_QUEUE:                Name is queued
 704  * @KDBUS_NAME_ACTIVATOR:               Name is owned by a activator connection
 705  */
 706 enum kdbus_name_flags {
 707         KDBUS_NAME_REPLACE_EXISTING     = 1ULL <<  0,
 708         KDBUS_NAME_ALLOW_REPLACEMENT    = 1ULL <<  1,
 709         KDBUS_NAME_QUEUE                = 1ULL <<  2,
 710         KDBUS_NAME_IN_QUEUE             = 1ULL <<  3,
 711         KDBUS_NAME_ACTIVATOR            = 1ULL <<  4,
 712 };
 713
 714 /**
 715  * struct kdbus_cmd_name - struct to describe a well-known name
 716  * @size:               The total size of the struct
 717  * @flags:              Flags for a name entry (KDBUS_NAME_*),
 718  *                      userspace → kernel, kernel → userspace
 719  * @kernel_flags:       Supported flags for a name entry, kernel → userspace
 720  * @items:              Item list, containing the well-known name as
 721  *                      KDBUS_ITEM_NAME
 722  *
 723  * This structure is used with the KDBUS_CMD_NAME_ACQUIRE ioctl.
 724  */
 725 struct kdbus_cmd_name {
 726         __u64 size;
 727         __u64 flags;
 728         __u64 kernel_flags;
 729         struct kdbus_item items[0];
 730 } __attribute__((aligned(8)));
 731
 732 /**
 733  * struct kdbus_name_info - struct to describe a well-known name
 734  * @size:               The total size of the struct
 735  * @conn_flags:         The flags of the owning connection (KDBUS_HELLO_*)
 736  * @owner_id:           The current owner of the name
 737  * @items:              Item list, containing the well-known name as
 738  *                      KDBUS_ITEM_OWNED_NAME
 739  *
 740  * This structure is used as return struct for the KDBUS_CMD_NAME_LIST ioctl.
 741  */
 742 struct kdbus_name_info {
 743         __u64 size;
 744         __u64 conn_flags;
 745         __u64 owner_id;
 746         struct kdbus_item items[0];
 747 } __attribute__((aligned(8)));
 748
 749 /**
 750  * enum kdbus_name_list_flags - what to include into the returned list
 751  * @KDBUS_NAME_LIST_UNIQUE:     All active connections
 752  * @KDBUS_NAME_LIST_NAMES:      All known well-known names
 753  * @KDBUS_NAME_LIST_ACTIVATORS: All activator connections
 754  * @KDBUS_NAME_LIST_QUEUED:     All queued-up names
 755  */
 756 enum kdbus_name_list_flags {
 757         KDBUS_NAME_LIST_UNIQUE          = 1ULL <<  0,
 758         KDBUS_NAME_LIST_NAMES           = 1ULL <<  1,
 759         KDBUS_NAME_LIST_ACTIVATORS      = 1ULL <<  2,
 760         KDBUS_NAME_LIST_QUEUED          = 1ULL <<  3,
 761 };
 762
 763 /**
 764  * struct kdbus_cmd_name_list - request a list of name entries
 765  * @flags:              Flags for the query (KDBUS_NAME_LIST_*),
 766  *                      userspace → kernel
 767  * @kernel_flags:       Supported flags for queries, kernel → userspace
 768  * @offset:             The returned offset in the caller's pool buffer.
 769  *                      The user must use KDBUS_CMD_FREE to free the
 770  *                      allocated memory.
 771  *
 772  * This structure is used with the KDBUS_CMD_NAME_LIST ioctl.
 773  */
 774 struct kdbus_cmd_name_list {
 775         __u64 flags;
 776         __u64 kernel_flags;
 777         __u64 offset;
 778 } __attribute__((aligned(8)));
 779
 780 /**
 781  * struct kdbus_name_list - information returned by KDBUS_CMD_NAME_LIST
 782  * @size:               The total size of the structure
 783  * @names:              A list of names
 784  *
 785  * Note that the user is responsible for freeing the allocated memory with
 786  * the KDBUS_CMD_FREE ioctl.
 787  */
 788 struct kdbus_name_list {
 789         __u64 size;
 790         struct kdbus_name_info names[0];
 791 };
 792
 793 /**
 794  * struct kdbus_cmd_info - struct used for KDBUS_CMD_CONN_INFO ioctl
 795  * @size:               The total size of the struct
 796  * @flags:              KDBUS_ATTACH_* flags, userspace → kernel
 797  * @kernel_flags:       Supported KDBUS_ATTACH_* flags, kernel → userspace
 798  * @id:                 The 64-bit ID of the connection. If set to zero, passing
 799  *                      @name is required. kdbus will look up the name to
 800  *                      determine the ID in this case.
 801  * @offset:             Returned offset in the caller's pool buffer where the
 802  *                      kdbus_info struct result is stored. The user must
 803  *                      use KDBUS_CMD_FREE to free the allocated memory.
 804  * @items:              The optional item list, containing the
 805  *                      well-known name to look up as a KDBUS_ITEM_NAME.
 806  *                      Only needed in case @id is zero.
 807  *
 808  * On success, the KDBUS_CMD_CONN_INFO ioctl will return 0 and @offset will
 809  * tell the user the offset in the connection pool buffer at which to find the
 810  * result in a struct kdbus_info.
 811  */
 812 struct kdbus_cmd_info {
 813         __u64 size;
 814         __u64 flags;
 815         __u64 kernel_flags;
 816         __u64 id;
 817         __u64 offset;
 818         struct kdbus_item items[0];
 819 } __attribute__((aligned(8)));
 820
 821 /**
 822  * struct kdbus_info - information returned by KDBUS_CMD_*_INFO
 823  * @size:               The total size of the struct
 824  * @id:                 The connection's or bus' 64-bit ID
 825  * @flags:              The connection's or bus' flags
 826  * @items:              A list of struct kdbus_item
 827  *
 828  * Note that the user is responsible for freeing the allocated memory with
 829  * the KDBUS_CMD_FREE ioctl.
 830  */
 831 struct kdbus_info {
 832         __u64 size;
 833         __u64 id;
 834         __u64 flags;
 835         struct kdbus_item items[0];
 836 };
 837
 838 /**
 839  * struct kdbus_cmd_update - update flags of a connection
 840  * @size:               The total size of the struct
 841  * @flags:              Flags for the update command, userspace → kernel
 842  * @kernel_flags:       Supported flags for this command, kernel → userspace
 843  * @items:              A list of struct kdbus_item
 844  *
 845  * This struct is used with the KDBUS_CMD_CONN_UPDATE ioctl.
 846  */
 847 struct kdbus_cmd_update {
 848         __u64 size;
 849         __u64 flags;
 850         __u64 kernel_flags;
 851         struct kdbus_item items[0];
 852 } __attribute__((aligned(8)));
 853
 854 /**
 855  * enum kdbus_cmd_match_flags - flags to control the KDBUS_CMD_MATCH_ADD ioctl
 856  * @KDBUS_MATCH_REPLACE:        If entries with the supplied cookie already
 857  *                              exists, remove them before installing the new
 858  *                              matches.
 859  */
 860 enum kdbus_cmd_match_flags {
 861         KDBUS_MATCH_REPLACE     = 1ULL <<  0,
 862 };
 863
 864 /**
 865  * struct kdbus_cmd_match - struct to add or remove matches
 866  * @size:               The total size of the struct
 867  * @cookie:             Userspace supplied cookie. When removing, the cookie
 868  *                      identifies the match to remove
 869  * @flags:              Flags for match command (KDBUS_MATCH_*),
 870  *                      userspace → kernel
 871  * @kernel_flags:       Supported flags of the used command, kernel → userspace
 872  * @items:              A list of items for additional information
 873  *
 874  * This structure is used with the KDBUS_CMD_MATCH_ADD and
 875  * KDBUS_CMD_MATCH_REMOVE ioctl.
 876  */
 877 struct kdbus_cmd_match {
 878         __u64 size;
 879         __u64 cookie;
 880         __u64 flags;
 881         __u64 kernel_flags;
 882         struct kdbus_item items[0];
 883 } __attribute__((aligned(8)));
 884
 885 /**
 886  * Ioctl API
 887  * KDBUS_CMD_BUS_MAKE:          After opening the "control" node, this command
 888  *                              creates a new bus with the specified
 889  *                              name. The bus is immediately shut down and
 890  *                              cleaned up when the opened file descriptor is
 891  *                              closed.
 892  * KDBUS_CMD_ENDPOINT_MAKE:     Creates a new named special endpoint to talk to
 893  *                              the bus. Such endpoints usually carry a more
 894  *                              restrictive policy and grant restricted access
 895  *                              to specific applications.
 896  * KDBUS_CMD_HELLO:             By opening the bus node, a connection is
 897  *                              created. After a HELLO the opened connection
 898  *                              becomes an active peer on the bus.
 899  * KDBUS_CMD_BYEBYE:            Disconnect a connection. If there are no
 900  *                              messages queued up in the connection's pool,
 901  *                              the call succeeds, and the handle is rendered
 902  *                              unusable. Otherwise, -EBUSY is returned without
 903  *                              any further side-effects.
 904  * KDBUS_CMD_MSG_SEND:          Send a message and pass data from userspace to
 905  *                              the kernel.
 906  * KDBUS_CMD_MSG_RECV:          Receive a message from the kernel which is
 907  *                              placed in the receiver's pool.
 908  * KDBUS_CMD_MSG_CANCEL:        Cancel a pending request of a message that
 909  *                              blocks while waiting for a reply. The parameter
 910  *                              denotes the cookie of the message in flight.
 911  * KDBUS_CMD_FREE:              Release the allocated memory in the receiver's
 912  *                              pool.
 913  * KDBUS_CMD_NAME_ACQUIRE:      Request a well-known bus name to associate with
 914  *                              the connection. Well-known names are used to
 915  *                              address a peer on the bus.
 916  * KDBUS_CMD_NAME_RELEASE:      Release a well-known name the connection
 917  *                              currently owns.
 918  * KDBUS_CMD_NAME_LIST:         Retrieve the list of all currently registered
 919  *                              well-known and unique names.
 920  * KDBUS_CMD_CONN_INFO:         Retrieve credentials and properties of the
 921  *                              initial creator of the connection. The data was
 922  *                              stored at registration time and does not
 923  *                              necessarily represent the connected process or
 924  *                              the actual state of the process.
 925  * KDBUS_CMD_CONN_UPDATE:       Update the properties of a connection. Used to
 926  *                              update the metadata subscription mask and
 927  *                              policy.
 928  * KDBUS_CMD_BUS_CREATOR_INFO:  Retrieve information of the creator of the bus
 929  *                              a connection is attached to.
 930  * KDBUS_CMD_ENDPOINT_UPDATE:   Update the properties of a custom enpoint. Used
 931  *                              to update the policy.
 932  * KDBUS_CMD_MATCH_ADD: Install a match which broadcast messages should
 933  *                              be delivered to the connection.
 934  * KDBUS_CMD_MATCH_REMOVE:      Remove a current match for broadcast messages.
 935  */
 936 #define KDBUS_CMD_BUS_MAKE              _IOW(KDBUS_IOCTL_MAGIC, 0x00,   \
 937                                              struct kdbus_cmd_make)
 938 #define KDBUS_CMD_ENDPOINT_MAKE         _IOW(KDBUS_IOCTL_MAGIC, 0x10,   \
 939                                              struct kdbus_cmd_make)
 940
 941 #define KDBUS_CMD_HELLO                 _IOWR(KDBUS_IOCTL_MAGIC, 0x20,  \
 942                                               struct kdbus_cmd_hello)
 943 #define KDBUS_CMD_BYEBYE                _IO(KDBUS_IOCTL_MAGIC, 0x21)    \
 944
 945 #define KDBUS_CMD_MSG_SEND              _IOWR(KDBUS_IOCTL_MAGIC, 0x30,  \
 946                                               struct kdbus_msg)
 947 #define KDBUS_CMD_MSG_RECV              _IOWR(KDBUS_IOCTL_MAGIC, 0x31,  \
 948                                               struct kdbus_cmd_recv)
 949 #define KDBUS_CMD_MSG_CANCEL            _IOW(KDBUS_IOCTL_MAGIC, 0x32,   \
 950                                              struct kdbus_cmd_cancel)
 951 #define KDBUS_CMD_FREE                  _IOW(KDBUS_IOCTL_MAGIC, 0x33,   \
 952                                              struct kdbus_cmd_free)
 953
 954 #define KDBUS_CMD_NAME_ACQUIRE          _IOWR(KDBUS_IOCTL_MAGIC, 0x40,  \
 955                                               struct kdbus_cmd_name)
 956 #define KDBUS_CMD_NAME_RELEASE          _IOW(KDBUS_IOCTL_MAGIC, 0x41,   \
 957                                              struct kdbus_cmd_name)
 958 #define KDBUS_CMD_NAME_LIST             _IOWR(KDBUS_IOCTL_MAGIC, 0x42,  \
 959                                               struct kdbus_cmd_name_list)
 960
 961 #define KDBUS_CMD_CONN_INFO             _IOWR(KDBUS_IOCTL_MAGIC, 0x50,  \
 962                                               struct kdbus_cmd_info)
 963 #define KDBUS_CMD_CONN_UPDATE           _IOW(KDBUS_IOCTL_MAGIC, 0x51,   \
 964                                              struct kdbus_cmd_update)
 965 #define KDBUS_CMD_BUS_CREATOR_INFO      _IOWR(KDBUS_IOCTL_MAGIC, 0x52,  \
 966                                               struct kdbus_cmd_info)
 967
 968 #define KDBUS_CMD_ENDPOINT_UPDATE       _IOW(KDBUS_IOCTL_MAGIC, 0x61,   \
 969                                              struct kdbus_cmd_update)
 970
 971 #define KDBUS_CMD_MATCH_ADD             _IOW(KDBUS_IOCTL_MAGIC, 0x70,   \
 972                                              struct kdbus_cmd_match)
 973 #define KDBUS_CMD_MATCH_REMOVE          _IOW(KDBUS_IOCTL_MAGIC, 0x71,   \
 974                                              struct kdbus_cmd_match)
 975
 976 #endif /* _KDBUS_UAPI_H_ */