diff options
| -rw-r--r-- | ChangeLog | 14 | ||||
| -rw-r--r-- | dbus/dbus-connection.c | 5 | ||||
| -rw-r--r-- | dbus/dbus-internals.c | 11 | ||||
| -rw-r--r-- | dbus/dbus-internals.h | 5 | ||||
| -rw-r--r-- | doc/dbus-specification.xml | 78 | ||||
| -rw-r--r-- | tools/dbus-uuidgen.1 | 19 |
6 files changed, 94 insertions, 38 deletions
@@ -1,3 +1,17 @@ +2006-11-14 Havoc Pennington <hp@redhat.com> + + * 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. + 2006-11-14 John (J5) Palmieri <johnp@redhat.com> * dbus/dbus-threads.h: fix DBUS_THREAD_FUNCTIONS_ALL_MASK to have diff --git a/dbus/dbus-connection.c b/dbus/dbus-connection.c index 552ecfd8..268a97d6 100644 --- a/dbus/dbus-connection.c +++ b/dbus/dbus-connection.c @@ -5511,7 +5511,10 @@ dbus_connection_get_outgoing_size (DBusConnection *connection) * If the remote application has the same machine ID as the one * returned by this function, then the remote application is on the * same machine as your application. - * + * + * The UUID is not a UUID in the sense of RFC4122; the details + * are explained in the D-Bus specification. + * * @returns a 32-byte-long hex-encoded UUID string, or #NULL if insufficient memory */ char* diff --git a/dbus/dbus-internals.c b/dbus/dbus-internals.c index 961e7269..788b3529 100644 --- a/dbus/dbus-internals.c +++ b/dbus/dbus-internals.c @@ -22,6 +22,7 @@ */ #include "dbus-internals.h" #include "dbus-protocol.h" +#include "dbus-marshal-basic.h" #include "dbus-test.h" #include <stdio.h> #include <stdarg.h> @@ -505,18 +506,12 @@ void _dbus_generate_uuid (DBusGUID *uuid) { long now; - char *p; - int ts_size; _dbus_get_current_time (&now, NULL); - uuid->as_uint32s[0] = now; - - ts_size = sizeof (uuid->as_uint32s[0]); - p = ((char*)uuid->as_bytes) + ts_size; + uuid->as_uint32s[DBUS_UUID_LENGTH_WORDS - 1] = DBUS_UINT32_TO_BE (now); - _dbus_generate_random_bytes_buffer (p, - sizeof (uuid->as_bytes) - ts_size); + _dbus_generate_random_bytes_buffer (uuid->as_bytes, DBUS_UUID_LENGTH_BYTES - 4); } /** diff --git a/dbus/dbus-internals.h b/dbus/dbus-internals.h index 4d839241..750882b9 100644 --- a/dbus/dbus-internals.h +++ b/dbus/dbus-internals.h @@ -318,7 +318,8 @@ void _dbus_set_bad_address (DBusError *error, const char *address_problem_other); #define DBUS_UUID_LENGTH_BYTES 16 -#define DBUS_UUID_LENGTH_HEX (DBUS_UUID_LENGTH_BYTES * 2) +#define DBUS_UUID_LENGTH_WORDS (DBUS_UUID_LENGTH_BYTES / 4) +#define DBUS_UUID_LENGTH_HEX (DBUS_UUID_LENGTH_BYTES * 2) /** * A globally unique ID ; we have one for each DBusServer, and also one for each @@ -326,7 +327,7 @@ void _dbus_set_bad_address (DBusError *error, */ union DBusGUID { - dbus_uint32_t as_uint32s[DBUS_UUID_LENGTH_BYTES / 4]; /**< guid as four uint32 values */ + dbus_uint32_t as_uint32s[DBUS_UUID_LENGTH_WORDS]; /**< guid as four uint32 values */ char as_bytes[DBUS_UUID_LENGTH_BYTES]; /**< guid as 16 single-byte values */ }; 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 @@ <para> A server may specify a key-value pair with the key <literal>guid</literal> - 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. <xref linkend="uuids"/> + describes the format of the <literal>guid</literal> 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. </para> <para> - 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). + </para> + + <para> + Note that the address key is <literal>guid</literal> even though the + rest of the API and documentation says "UUID," for historical reasons. </para> <para> @@ -2314,6 +2320,43 @@ hyphens. </para> </sect1> + + <sect1 id="uuids"> + <title>UUIDs</title> + <para> + 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 <xref linkend="addresses"/>. 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 <xref + linkend="standard-interfaces-peer"/>). + </para> + <para> + 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. + </para> + <para> + 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). + </para> + <para> + 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. + </para> + <para> + Implementations should, however, stick to random data for the first 96 bits + of the UUID. + </para> + </sect1> <sect1 id="standard-interfaces"> <title>Standard Interfaces</title> @@ -2364,12 +2407,7 @@ is more robust. </para> <para> - 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. + <xref linkend="uuids"/> explains the format of the UUID. </para> </sect2> diff --git a/tools/dbus-uuidgen.1 b/tools/dbus-uuidgen.1 index 882acfec..480fd18f 100644 --- a/tools/dbus-uuidgen.1 +++ b/tools/dbus-uuidgen.1 @@ -14,6 +14,11 @@ dbus-uuidgen \- Utility to generate UUIDs The \fIdbus-uuidgen\fP command generates or reads a universally unique ID. .PP +Note that the D-Bus UUID has no relationship to RFC 4122 and does not generate +UUIDs compatible with that spec. Many systems have a separate command +for that (often called "uuidgen"). + +.PP See http://www.freedesktop.org/software/dbus/ for more information about D-Bus. @@ -39,15 +44,11 @@ IDs, and so forth. .PP If you run \fIdbus-uuidgen\fP with no options it just prints a new uuid made -up out of thin air. This is similar to the regular "uuidgen" command. - -.PP -If you run it with --get, it prints the machine uuid by default, or -the uuid in the specified file if you specify a file. +up out of thin air. .PP -The D-Bus UUID has no relationship to RFC 4122 and does not generate -UUIDs compatible with that spec. +If you run it with --get, it prints the machine UUID by default, or +the UUID in the specified file if you specify a file. .PP If you try to change an existing machine-id on a running system, it will @@ -55,6 +56,10 @@ probably result in bad things happening. Don't try to change this file. Also, don't make it the same on two different systems; it needs to be different anytime there are two different kernels running. +.PP +The UUID should be different on two different virtual machines, +because there are two different kernels. + .SH OPTIONS The following options are supported: .TP |