From dbc061b8123799e9352ab069b4dc1b5ea394587d Mon Sep 17 00:00:00 2001 From: Havoc Pennington Date: Wed, 15 Nov 2006 01:52:01 +0000 Subject: 2006-11-14 Havoc Pennington * dbus/dbus-internals.c (_dbus_generate_uuid): The spec said the UUID had the timestamp last, but the implementation had it first; move it to last since I think it's a tiny bit nicer (easier to compare at a glance, faster to sort, less code), and will not cause any practical compatibility problems. Also, always convert the timestamp to big endian. * doc/dbus-specification.xml: Clean up the docs on the UUID. * tools/dbus-uuidgen.1: more prominently say it is not suitable as a replacement for regular uuidgen/RFC4122. --- doc/dbus-specification.xml | 78 ++++++++++++++++++++++++++++++++++------------ 1 file changed, 58 insertions(+), 20 deletions(-) (limited to 'doc') diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml index 986bada4..77b7e699 100644 --- a/doc/dbus-specification.xml +++ b/doc/dbus-specification.xml @@ -2237,23 +2237,29 @@ A server may specify a key-value pair with the key guid - and the value a hex-encoded 16-byte sequence. This globally unique ID must - be created by filling the first 4 bytes with a 32-bit UNIX time since the - epoch, and the remaining 12 bytes with random bytes. If present, the GUID - may be used to distinguish one server from another. A server should use a - different GUID for each address it listens on. For example, if a message - bus daemon offers both UNIX domain socket and TCP connections, but treats - clients the same regardless of how they connect, those two connections are - equivalent post-connection but should have distinct GUIDs to distinguish - the kinds of connection. + and the value a hex-encoded 16-byte sequence. + describes the format of the guid field. If present, + this UUID may be used to distinguish one server address from another. A + server should use a different UUID for each address it listens on. For + example, if a message bus daemon offers both UNIX domain socket and TCP + connections, but treats clients the same regardless of how they connect, + those two connections are equivalent post-connection but should have + distinct UUIDs to distinguish the kinds of connection. - The intent of the GUID feature is to allow a client to avoid opening - multiple identical connections to the same server, by allowing the client - to check whether an address corresponds to an already-existing connection. - Comparing two addresses is insufficient, because addresses can be recycled - by distinct servers. + The intent of the address UUID feature is to allow a client to avoid + opening multiple identical connections to the same server, by allowing the + client to check whether an address corresponds to an already-existing + connection. Comparing two addresses is insufficient, because addresses + can be recycled by distinct servers, and equivalent addresses may look + different if simply compared as strings (for example, the host in a TCP + address can be given as an IP address or as a hostname). + + + + Note that the address key is guid even though the + rest of the API and documentation says "UUID," for historical reasons. @@ -2314,6 +2320,43 @@ hyphens. + + + UUIDs + + A working D-Bus implementation uses universally-unique IDs in two places. + First, each server address has a UUID identifying the address, + as described in . Second, each operating + system kernel instance running a D-Bus client or server has a UUID + identifying that kernel, retrieved by invoking the method + org.freedesktop.DBus.Peer.GetMachineId() (see ). + + + The term "UUID" in this document is intended literally, i.e. an + identifier that is universally unique. It is not intended to refer to + RFC4122, and in fact the D-Bus UUID is not compatible with that RFC. + + + The UUID must contain 128 bits of data and be hex-encoded. The + hex-encoded string may not contain hyphens or other non-hex-digit + characters, and it must be exactly 32 characters long. To generate a + UUID, the current reference implementation concatenates 96 bits of random + data followed by the 32-bit time in seconds since the UNIX epoch (in big + endian byte order). + + + It would also be acceptable and probably better to simply generate 128 + bits of random data, as long as the random number generator is of high + quality. The timestamp could conceivably help if the random bits are not + very random. With a quality random number generator, collisions are + extremely unlikely even with only 96 bits, so it's somewhat academic. + + + Implementations should, however, stick to random data for the first 96 bits + of the UUID. + + Standard Interfaces @@ -2364,12 +2407,7 @@ is more robust. - The UUID must contain 128 bits of data and be hex-encoded (meaning, the hex - string contains 32 ASCII characters). The hex-encoded string may not contain - hyphens or other non-hex-digit characters, and it must be exactly 32 characters long. - To generate a UUID, the recommended algorithm is to put the current time in seconds - since the UNIX epoch in the last 32 bits of the UUID, and to put randomly-generated bits - in the first 96 bits of the UUID. + explains the format of the UUID. -- cgit