From 5a54ebc9e0dc889bb37abeb869668002e9ecb4e0 Mon Sep 17 00:00:00 2001 From: Daniel Mack Date: Tue, 27 Jan 2015 12:49:08 +0100 Subject: [PATCH] doc: some more information on items Signed-off-by: Daniel Mack --- doc/kdbus.item.xml | 757 ++++++++++++++++++++++++++++-------------- doc/kdbus.message.xml | 20 +- 2 files changed, 516 insertions(+), 261 deletions(-) diff --git a/doc/kdbus.item.xml b/doc/kdbus.item.xml index 46722fbe..ff218c3 100644 --- a/doc/kdbus.item.xml +++ b/doc/kdbus.item.xml @@ -31,7 +31,7 @@ kdbus.item - Kernel item structure + kdbus item structure @@ -40,9 +40,9 @@ 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 sent to will cause the ioctl to fail + 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 sent to will cause the ioctl to fail -EINVAL. Items are also used for information stored in a connection's pool, such as received messages, name lists or @@ -52,17 +52,19 @@ items or items that are unsupported by the ioctl are rejected. - 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. + + 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. Iterating items - A simple iterator in userspace would iterate over the items until the items - have reached the embedding structure's overall size. An example implementation - is shown below. + + A simple iterator in userspace would iterate over the items until + the items have reached the embedding structure's overall size. + An example implementation is shown below. + - - Item layout - 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. - A shortened version is shown below. - + + Item layout + + 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 { - /* item type specific payload - see below */ + __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. - - + + 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. + + - - Item types - - Items exchanged between userspace and kernel - - - KDBUS_ITEM_PAYLOAD_VEC - - - - - - KDBUS_ITEM_PAYLOAD_OFF - TODO - - - - - KDBUS_ITEM_PAYLOAD_MEMFD - TODO - - - - - KDBUS_ITEM_FDS - TODO - - - - - KDBUS_ITEM_CANCEL_FD - TODO - - - - - KDBUS_ITEM_BLOOM_PARAMETER - TODO - - - - - KDBUS_ITEM_BLOOM_FILTER - TODO - - - - - KDBUS_ITEM_BLOOM_MASK - TODO - - - - - KDBUS_ITEM_DST_NAME - TODO - - - - - KDBUS_ITEM_MAKE_NAME - TODO - - - - - KDBUS_ITEM_ATTACH_FLAGS_SEND - TODO - - - - - KDBUS_ITEM_ATTACH_FLAGS_RECV - TODO - - - - - KDBUS_ITEM_ID - TODO - - - - - KDBUS_ITEM_NAME - TODO - - - - - Items attached by the kernel as metadata - - - - KDBUS_ITEM_TIMESTAMP - TODO - - - - - KDBUS_ITEM_CREDS - TODO - - - - - KDBUS_ITEM_PIDS - TODO - - - - - KDBUS_ITEM_AUXGROUPS - TODO - - - - - KDBUS_ITEM_OWNED_NAME - TODO - - - - - KDBUS_ITEM_TID_COMM - TODO - - - - - KDBUS_ITEM_PID_COMM - TODO - - - - - KDBUS_ITEM_EXE - TODO - - - - - KDBUS_ITEM_CMDLINE - TODO - - - - - KDBUS_ITEM_CGROUP - TODO - - - - - KDBUS_ITEM_CAPS - TODO - - - - - KDBUS_ITEM_SECLABEL - TODO - - - - - KDBUS_ITEM_AUDIT - TODO - - - - - KDBUS_ITEM_CONN_DESCRIPTION - TODO - - - - - Items used for policy entries, matches and notifications - - - - KDBUS_ITEM_NAME_ADD - TODO - - - - - KDBUS_ITEM_NAME_REMOVE - TODO - - - - - KDBUS_ITEM_NAME_CHANGE - TODO - - - - - KDBUS_ITEM_ID_ADD - TODO - - - - - KDBUS_ITEM_ID_REMOVE - TODO - - - - - KDBUS_ITEM_REPLY_TIMEOUT - TODO - - - - - KDBUS_ITEM_REPLY_DEAD - TODO - - - - + + Item types + + Items exchanged between userspace and kernel + + + KDBUS_ITEM_PAYLOAD_VEC + KDBUS_ITEM_PAYLOAD_OFF + + Messages are directly copied by the sending process into the + receiver's + kdbus.pool2. + 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.pool2 + where the message payload can be found. + See + kdbus.message2 + 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.message2 + 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, userspace sets + the values of this array 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 occured. + filedescriptor. + In either case, the number of entries in the array is derived from + the item's total size. See + kdbus.message2 + 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 + filedescriptor. See + kdbus.message2 + for more information on this item and how to use it. + + + + + KDBUS_ITEM_BLOOM_PARAMETER + TODO + +struct kdbus_bloom_parameter { + __u64 size; + __u64 n_hash; +}; + + + + + + KDBUS_ITEM_BLOOM_FILTER + TODO + +struct kdbus_bloom_filter { + __u64 generation; + __u64 data[0]; +}; + + + + + + KDBUS_ITEM_BLOOM_MASK + TODO + + + + + 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.message2 + for more information on how to send a message. + + + + + KDBUS_ITEM_MAKE_NAME + TODO + + + + + KDBUS_ITEM_ATTACH_FLAGS_SEND + KDBUS_ITEM_ATTACH_FLAGS_RECV + + Contains a set of attach flags at + send or receive time. See + kdbus2, + kdbus.bus2 and + kdbus.connection2 + for more information on attach flags. + + + + + KDBUS_ITEM_ID + + Transports a connection's numerical ID of + a connection as u64 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.name2 + for more information on how to access the name registry of a bus. + +struct kdbus_name { + __u64 flags; + char name[0]; +}; + + + + + + Items attached by the kernel as metadata + + + + 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 credentials such as the user and + group in the usual four flavors: + real, effective, saved and file-system 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 + u32 values in item.data32. + The array length can be determined by looking at the item's total + size, substracting the size of the header and and dividing the + remainder by sizeof(u32). + + + + + 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 of a task's + TID, stored as null-terminated string in + item.str. Its length can also be derived from + the item's total size. + + + + + KDBUS_ITEM_PID_COMM [*] + + Contains the comm of a task's + PID, stored as null-terminated string in + item.str. Its length can also be derived from + the item's total size. + + + + + 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. + + + + + 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. + + + + + 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 increas in the + future, userspace 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. + + + + + + Note that the content stored in these items 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. + + Items used for policy entries, matches and notifications + + + + KDBUS_ITEM_NAME_ADD + TODO + +struct kdbus_notify_name_change { + struct kdbus_notify_id_change old_id; + struct kdbus_notify_id_change new_id; + char name[0]; +}; + + + + + + KDBUS_ITEM_POLICY_ACCESS + TODO + +struct kdbus_policy_access { + __u64 type; /* USER, GROUP, WORLD */ + __u64 access; /* OWN, TALK, SEE */ + __u64 id; /* uid, gid, 0 */ +}; + + + + + + KDBUS_ITEM_NAME_REMOVE + TODO + + + + + KDBUS_ITEM_NAME_CHANGE + TODO + + + + + KDBUS_ITEM_ID_ADD + TODO + +struct kdbus_notify_id_change { + __u64 id; + __u64 flags; +}; + + + + + + KDBUS_ITEM_ID_REMOVE + TODO + + + + + KDBUS_ITEM_REPLY_TIMEOUT + TODO + + + + + KDBUS_ITEM_REPLY_DEAD + TODO + + + - See Also diff --git a/doc/kdbus.message.xml b/doc/kdbus.message.xml index 039599f..ec58fd7 100644 --- a/doc/kdbus.message.xml +++ b/doc/kdbus.message.xml @@ -130,13 +130,19 @@ struct kdbus_cmd_send { KDBUS_ITEM_CANCEL_FD - When this optional item is passed in, and the call is executed as SYNC - call, the passed in file descriptor can be used as alternative - cancellation point. The kernel will call poll() on this file descriptor, - and if it reports any incoming bytes, the blocking send operation will - be canceled, and the call will return -ECANCELED. Any type of file - descriptor that implements poll() can be used as payload to this item. - For asynchronous message sending, this item is accepted but ignored. + When this optional item is passed in, and the call is + executed as SYNC call, the passed in file descriptor can be + used as alternative cancellation point. The kernel will call + poll() + poll2 + on this file descriptor, and if it reports any incoming + bytes, the blocking send operation will be canceled, and the + call will return -ECANCELED. Any type of + file descriptor on which + poll2 + can be called on can be used as payload to this item. + For asynchronous message sending, this item is allowed but + ignored. -- 2.34.1