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