X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=src%2Flibsystemd%2Fsd-bus%2FPORTING-DBUS1;h=0253a42137850b113aee41ad5c2a4e1d373c726d;hb=03e334a1c7dc8c20c38902aa039440763acc9b17;hp=57339ee268ca6726f77684de4d6b326a9c35a191;hpb=1fa132931a3eed8556da801d9fe91aa4c166445e;p=elogind.git diff --git a/src/libsystemd/sd-bus/PORTING-DBUS1 b/src/libsystemd/sd-bus/PORTING-DBUS1 index 57339ee26..0253a4213 100644 --- a/src/libsystemd/sd-bus/PORTING-DBUS1 +++ b/src/libsystemd/sd-bus/PORTING-DBUS1 @@ -51,7 +51,9 @@ client does not know what they mean, it must disconnect. The upper system, the lower 32bit indicate "compatible" feature additions. A client that does not support a "compatible" feature addition can go on communicating with the bus, however a client that does not support an -"incompatible" feature must not proceed with the connection. +"incompatible" feature must not proceed with the connection. When a +client encountes such an "incompatible" feature it should immediately +try the next bus address configured in the bus address string. The hello structure also contains another flags field "attach_flags" which indicates metadata that is optionally attached to all incoming @@ -66,8 +68,9 @@ The kernel will return in the "id" field your unique id. This is a simple numeric value. For compatibility with classic dbus1 simply format this as string and prefix ":0.". -The kernel will also return the bloom filter size used for the signal -broadcast bloom filter (see below). +The kernel will also return the bloom filter size and bloom filter +hash function number used for the signal broadcast bloom filter (see +below). The kernel will also return the bus ID of the bus in a 128bit field. @@ -231,18 +234,35 @@ probabilistically check whether a certain word is contained in a vocabulary. It knows no false negatives, but it does know false positives. -The bloom filter that needs to be included has the parameters m=512 -(bits in the filter), k=8 (nr of hash functions). The underlying hash -function is SipHash-2-4. We calculate two hash values for an input -strings, one with the hash key b9660bf0467047c18875c49c54b9bd15 (this -is supposed to be read as a series of 16 hexadecimal formatted -bytes), and one with the hash key -aaa154a2e0714b39bfe1dd2e9fc54a3b. This results in two 64bit hash -values, A and B. The 8 hash functions for the bloom filter require a 9 -bit output each (since m=512=2^9), to generate these we XOR combine -the first 8 bit of A shifted to the left by 1, with the first 8 bit of -B. Then, for the next hash function we use the second 8 bit pair, and -so on. +The parameters for the bloom filters that need to be included in +broadcast message is communicated to userspace as part of the hello +response structure (see above). By default it has the parameters m=512 +(bits in the filter), k=8 (nr of hash functions). Note however, that +this is subject to change in later versions, and userspace +implementations must be capable of handling m values between at least +m=8 and m=2^32, and k values between at least k=1 and k=32. The +underlying hash function is SipHash-2-4. It is used with a number of +constant (yet originally randomly generated) 128bit hash keys, more +specifically: + + b9,66,0b,f0,46,70,47,c1,88,75,c4,9c,54,b9,bd,15, + aa,a1,54,a2,e0,71,4b,39,bf,e1,dd,2e,9f,c5,4a,3b, + 63,fd,ae,be,cd,82,48,12,a1,6e,41,26,cb,fa,a0,c8, + 23,be,45,29,32,d2,46,2d,82,03,52,28,fe,37,17,f5, + 56,3b,bf,ee,5a,4f,43,39,af,aa,94,08,df,f0,fc,10, + 31,80,c8,73,c7,ea,46,d3,aa,25,75,0f,9e,4c,09,29, + 7d,f7,18,4b,7b,a4,44,d5,85,3c,06,e0,65,53,96,6d, + f2,77,e9,6f,93,b5,4e,71,9a,0c,34,88,39,25,bf,35 + +When calculating the first bit index into the bloom filter, the +SipHash-2-4 hash value is calculated for the input data and the first +16 bytes of the array above as hash key. Of the resulting 8 bytes of +output, as many full bytes are taken for the bit index as necessary, +starting from the output's first byte. For the second bit index the +same hash value is used, continuing with the next unused output byte, +and so on. Each time the bytes returned by the hash function are +depleted it is recalculated with the next 16 byte hash key from the +array above and the same input data. For each message to send across the bus we populate the bloom filter with all possible matchable strings. If a client then wants to @@ -298,6 +318,11 @@ messages (which it needs to anyway, given that transfers are relatively unrestricted on kdbus and people can send you all kinds of non-sense). +If a client connects to a bus whose bloom filter metrics (i.e. filter +size and number of hash functions) are outside of the range the client +supports it must immediately disconnect and continue connection with +the next bus address of the bus connection string. + INSTALLING MATCHES To install matches for broadcast messages, use the KDBUS_CMD_ADD_MATCH @@ -483,7 +508,7 @@ have attached. Note that when issuing the ioctl, you can select a different set of credentials to gather, than what was originally requested for being attached to incoming messages. -Credentials are always specific to the sender namespace that was +Credentials are always specific to the sender's domain that was current at the time of sending, and of the process that opened the bus connection at the time of opening it. Note that this latter data is cached! @@ -511,7 +536,7 @@ parameter. Client libraries should use the following connection string when connecting to the system bus: - kernel:path=/dev/kdbus/0-system/bus;unix:path=/run/dbus/system_bus_socket + kernel:path=/dev/kdbus/0-system/bus;unix:path=/var/run/dbus/system_bus_socket This will ensure that kdbus is preferred over the legacy AF_UNIX socket, but compatibility is kept. For the user bus use: