kdbus item kdbus.item 7 kdbus.item kdbus item structure, layout and usage To flexibly augment transport structures, data blobs of type struct kdbus_item can be attached to the structs passed into the ioctls. Some ioctls make items of certain types mandatory, others are optional. Items that are unsupported by ioctls they are attached to will cause the ioctl to fail with errno set to EINVAL. Items are also used for information stored in a connection's pool, such as received messages, name lists or requested connection or bus owner information. Depending on the type of an item, its total size is either fixed or variable. Whenever items are used as part of the kdbus kernel API, they are embedded in structs that are embedded inside structs that themselves include a size field containing the overall size of the structure. This allows multiple items to be chained up, and an item iterator (see below) is capable of detecting the end of an item chain. The kernel expects all items to be aligned to 8-byte boundaries. Unaligned items will cause the ioctl they are used with to fail with errno set to EINVAL. An item that has an unaligned size itself hence needs to be padded if it is followed by another item. A simple iterator would iterate over the items until the items have reached the embedding structure's overall size. An example implementation is shown below. size)) #define KDBUS_ITEM_FOREACH(item, head, first) \ for ((item) = (head)->first; \ ((uint8_t *)(item) < (uint8_t *)(head) + (head)->size) && \ ((uint8_t *)(item) >= (uint8_t *)(head)); \ (item) = KDBUS_ITEM_NEXT(item)) ]]> A struct kdbus_item consists of a size field, describing its overall size, and a type field, both 64 bit wide. They are followed by a union to store information that is specific to the item's type. The struct layout is shown below. struct kdbus_item { __u64 size; __u64 type; /* item payload - see below */ union { __u8 data[0]; __u32 data32[0]; __u64 data64[0]; char str[0]; __u64 id; struct kdbus_vec vec; struct kdbus_creds creds; struct kdbus_pids pids; struct kdbus_audit audit; struct kdbus_caps caps; struct kdbus_timestamp timestamp; struct kdbus_name name; struct kdbus_bloom_parameter bloom_parameter; struct kdbus_bloom_filter bloom_filter; struct kdbus_memfd memfd; int fds[0]; struct kdbus_notify_name_change name_change; struct kdbus_notify_id_change id_change; struct kdbus_policy_access policy_access; }; }; struct kdbus_item should never be used to allocate an item instance, as its size may grow in future releases of the API. Instead, it should be manually assembled by storing the size, type and payload to a struct of its own. KDBUS_ITEM_NEGOTIATE With this item is attached to any ioctl, programs can probe the kernel for known item types. The item carries an array of uint64_t values in item.data64, each set to an item type to probe. The kernel will reset each member of this array that is not recognized as valid item type to 0. This way, users can negotiate kernel features at start-up to keep newer userspace compatible with older kernels. This item is never attached by the kernel in response to any command. KDBUS_ITEM_PAYLOAD_VEC KDBUS_ITEM_PAYLOAD_OFF Messages are directly copied by the sending process into the receiver's kdbus.pool 7 . This way, two peers can exchange data by effectively doing a single-copy from one process to another; the kernel will not buffer the data anywhere else. KDBUS_ITEM_PAYLOAD_VEC is used when sending message. The item references a memory address when the payload data can be found. KDBUS_ITEM_PAYLOAD_OFF is used when messages are received, and the offset value describes the offset inside the receiving connection's kdbus.pool 7 where the message payload can be found. See kdbus.message 7 for more information on passing of payload data along with a message. struct kdbus_vec { __u64 size; union { __u64 address; __u64 offset; }; }; KDBUS_ITEM_PAYLOAD_MEMFD Transports a file descriptor of a memfd in struct kdbus_memfd in item.memfd. The size field has to match the actual size of the memfd that was specified when it was created. The start parameter denotes the offset inside the memfd at which the referenced payload starts. See kdbus.message 7 for more information on passing of payload data along with a message. struct kdbus_memfd { __u64 start; __u64 size; int fd; __u32 __pad; }; KDBUS_ITEM_FDS Contains an array of file descriptors. When used with KDBUS_CMD_SEND, the values of this array must be filled with valid file descriptor numbers. When received as item attached to a message, the array will contain the numbers of the installed file descriptors, or -1 in case an error occurred. In either case, the number of entries in the array is derived from the item's total size. See kdbus.message 7 for more information. KDBUS_ITEM_CANCEL_FD Transports a file descriptor that can be used to cancel a synchronous KDBUS_CMD_SEND operation by writing to it. The file descriptor is stored in item.fd[0]. The item may only contain one file descriptor. See kdbus.message 7 for more information on this item and how to use it. KDBUS_ITEM_BLOOM_PARAMETER Contains a set of bloom parameters as struct kdbus_bloom_parameter in item.bloom_parameter. The item is passed from userspace to kernel during the KDBUS_CMD_BUS_MAKE ioctl, and returned verbatim when KDBUS_CMD_HELLO is called. The kernel does not use the bloom parameters, but they need to be known by each connection on the bus in order to define the bloom filter hash details. See kdbus.match 7 for more information on matching and bloom filters. struct kdbus_bloom_parameter { __u64 size; __u64 n_hash; }; KDBUS_ITEM_BLOOM_FILTER Carries a bloom filter as struct kdbus_bloom_filter in item.bloom_filter. It is mandatory to send this item attached to a struct kdbus_msg, in case the message is a signal. This item is never transported from kernel to userspace. See kdbus.match 7 for more information on matching and bloom filters. struct kdbus_bloom_filter { __u64 generation; __u64 data[0]; }; KDBUS_ITEM_BLOOM_MASK Transports a bloom mask as binary data blob stored in item.data. This item is used to describe a match into a connection's match database. See kdbus.match 7 for more information on matching and bloom filters. KDBUS_ITEM_DST_NAME Contains a well-known name to send a message to, as null-terminated string in item.str. This item is used with KDBUS_CMD_SEND. See kdbus.message 7 for more information on how to send a message. KDBUS_ITEM_MAKE_NAME Contains a bus name or endpoint name, stored as null-terminated string in item.str. This item is sent from userspace to kernel when buses or endpoints are created, and returned back to userspace when the bus creator information is queried. See kdbus.bus 7 and kdbus.endpoint 7 . KDBUS_ITEM_ATTACH_FLAGS_SEND KDBUS_ITEM_ATTACH_FLAGS_RECV Contains a set of attach flags at send or receive time. See kdbus 7 , kdbus.bus 7 and kdbus.connection 7 for more information on attach flags. KDBUS_ITEM_ID Transports a connection's numerical ID of a connection as uint64_t value in item.id. KDBUS_ITEM_NAME Transports a name associated with the name registry as null-terminated string as struct kdbus_name in item.name. The flags contains the flags of the name. See kdbus.name 7 for more information on how to access the name registry of a bus. struct kdbus_name { __u64 flags; char name[0]; }; KDBUS_ITEM_TIMESTAMP Contains both the monotonic and the realtime timestamp, taken when the message was processed on the kernel side. Stored as struct kdbus_timestamp in item.timestamp. struct kdbus_timestamp { __u64 seqnum; __u64 monotonic_ns; __u64 realtime_ns; }; KDBUS_ITEM_CREDS Contains a set of user and group information as 32-bit values, in the usual four flavors: real, effective, saved and filesystem related. Stored as struct kdbus_creds in item.creds. struct kdbus_creds { __u32 uid; __u32 euid; __u32 suid; __u32 fsuid; __u32 gid; __u32 egid; __u32 sgid; __u32 fsgid; }; KDBUS_ITEM_PIDS Contains the PID, TID and parent PID (PPID) of a remote peer. Stored as struct kdbus_pids in item.pids. struct kdbus_pids { __u64 pid; __u64 tid; __u64 ppid; }; KDBUS_ITEM_AUXGROUPS Contains the auxiliary (supplementary) groups a remote peer is a member of, stored as array of uint32_t values in item.data32. The array length can be determined by looking at the item's total size, subtracting the size of the header and dividing the remainder by sizeof(uint32_t). KDBUS_ITEM_OWNED_NAME Contains a well-known name currently owned by a connection. The name is stored as null-terminated string in item.str. Its length can also be derived from the item's total size. KDBUS_ITEM_TID_COMM [*] Contains the comm string of a task's TID (thread ID), stored as null-terminated string in item.str. Its length can also be derived from the item's total size. Receivers of this item should not use its contents for any kind of security measures. See below. KDBUS_ITEM_PID_COMM [*] Contains the comm string of a task's PID (process ID), stored as null-terminated string in item.str. Its length can also be derived from the item's total size. Receivers of this item should not use its contents for any kind of security measures. See below. KDBUS_ITEM_EXE [*] Contains the path to the executable of a task, stored as null-terminated string in item.str. Its length can also be derived from the item's total size. Receivers of this item should not use its contents for any kind of security measures. See below. KDBUS_ITEM_CMDLINE [*] Contains the command line arguments of a task, stored as an array of null-terminated strings in item.str. The total length of all strings in the array can be derived from the item's total size. Receivers of this item should not use its contents for any kind of security measures. See below. KDBUS_ITEM_CGROUP Contains the cgroup path of a task, stored as null-terminated string in item.str. Its length can also be derived from the item's total size. KDBUS_ITEM_CAPS Contains sets of capabilities, stored as struct kdbus_caps in item.caps. As the item size may increase in the future, programs should be written in a way that it takes item.caps.last_cap into account, and derive the number of sets and rows from the item size and the reported number of valid capability bits. struct kdbus_caps { __u32 last_cap; __u32 caps[0]; }; KDBUS_ITEM_SECLABEL Contains the LSM label of a task, stored as null-terminated string in item.str. Its length can also be derived from the item's total size. KDBUS_ITEM_AUDIT Contains the audit sessionid and loginuid of a task, stored as struct kdbus_audit in item.audit. struct kdbus_audit { __u32 sessionid; __u32 loginuid; }; KDBUS_ITEM_CONN_DESCRIPTION Contains the connection description, as set by KDBUS_CMD_HELLO or KDBUS_CMD_CONN_UPDATE, stored as null-terminated string in item.str. Its length can also be derived from the item's total size. All metadata is automatically translated into the namespaces of the task that receives them. See kdbus.message 7 for more information. [*] Note that the content stored in metadata items of type KDBUS_ITEM_TID_COMM, KDBUS_ITEM_PID_COMM, KDBUS_ITEM_EXE and KDBUS_ITEM_CMDLINE can easily be tampered by the sending tasks. Therefore, they should not be used for any sort of security relevant assumptions. The only reason they are transmitted is to let receivers know about details that were set when metadata was collected, even though the task they were collected from is not active any longer when the items are received. KDBUS_ITEM_POLICY_ACCESS This item describes a policy access entry to access the policy database of a kdbus.bus 7 or kdbus.endpoint 7 . Please refer to kdbus.policy 7 for more information on the policy database and how to access it. struct kdbus_policy_access { __u64 type; __u64 access; __u64 id; }; KDBUS_ITEM_ID_ADD KDBUS_ITEM_ID_REMOVE This item is sent as attachment to a kernel notification and indicates that a new connection was created on the bus, or that a connection was disconnected, respectively. It stores a struct kdbus_notify_id_change in item.id_change. The id field contains the numeric ID of the connection that was added or removed, and flags is set to the connection flags, as passed by KDBUS_CMD_HELLO. See kdbus.match 7 and kdbus.message 7 for more information on matches and notification messages. struct kdbus_notify_id_change { __u64 id; __u64 flags; }; KDBUS_ITEM_NAME_ADD KDBUS_ITEM_NAME_REMOVE KDBUS_ITEM_NAME_CHANGE This item is sent as attachment to a kernel notification and indicates that a well-known name appeared, disappeared or transferred to another owner on the bus. It stores a struct kdbus_notify_name_change in item.name_change. old_id describes the former owner of the name and is set to 0 values in case of KDBUS_ITEM_NAME_ADD. new_id describes the new owner of the name and is set to 0 values in case of KDBUS_ITEM_NAME_REMOVE. The name field contains the well-known name the notification is about, as null-terminated string. See kdbus.match 7 and kdbus.message 7 for more information on matches and notification messages. struct kdbus_notify_name_change { struct kdbus_notify_id_change old_id; struct kdbus_notify_id_change new_id; char name[0]; }; KDBUS_ITEM_REPLY_TIMEOUT This item is sent as attachment to a kernel notification. It informs the receiver that an expected reply to a message was not received in time. The remote peer ID and the message cookie are stored in the message header. See kdbus.message 7 for more information about messages, timeouts and notifications. KDBUS_ITEM_REPLY_DEAD This item is sent as attachment to a kernel notification. It informs the receiver that a remote connection a reply is expected from was disconnected before that reply was sent. The remote peer ID and the message cookie are stored in the message header. See kdbus.message 7 for more information about messages, timeouts and notifications. kdbus 7 kdbus.bus 7 kdbus.connection 7 kdbus.endpoint 7 kdbus.fs 7 kdbus.message 7 kdbus.name 7 kdbus.pool 7 memfd_create 2