mirror of
https://gitlab.freedesktop.org/dbus/dbus.git
synced 2026-01-09 14:30:20 +01:00
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.
This commit is contained in:
Havoc Pennington
parent
2d760baace
commit
dbc061b812
6 changed files with 94 additions and 38 deletions
14
ChangeLog
14
ChangeLog
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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*
|
||||
|
|
|
|||
|
|
@ -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);
|
||||
}
|
||||
|
||||
/**
|
||||
|
|
|
|||
|
|
@ -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 */
|
||||
};
|
||||
|
||||
|
|
|
|||
|
|
@ -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>
|
||||
|
||||
|
|
|
|||
|
|
@ -13,6 +13,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.
|
||||
up out of thin air.
|
||||
|
||||
.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.
|
||||
|
||||
.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
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue