shaba/systemd
1
0
Fork 0
mirror of https://github.com/systemd/systemd.git synced 2024-12-22 17:35:35 +03:00
Code

sd-id128: document everywhere that we treat all UUIDs as Variant 1

Browse Source 
So in theory UUID Variant 2 (i.e. microsoft GUIDs) are supposed to be
displayed in native endian. That is of course a bad idea, and Linux
userspace generally didn't implement that, i.e. uuidd and similar.
Hence, let's not bother either, but let's document that we treat
everything the same as Variant 1, even if it declares something else.
This commit is contained in:
Lennart Poettering 2021-06-15 17:55:17 +02:00 committed by Zbigniew Jędrzejewski-Szmek
parent 9b682672e4
commit 39d02a175f
6 changed files with 34 additions and 28 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
man/machine-id.xml
View File

@ -147,15 +147,13 @@
<refsect1>
<title>Relation to OSF UUIDs</title>
<para>Note that the machine ID historically is not an OSF UUID as
defined by <ulink url="https://tools.ietf.org/html/rfc4122">RFC
4122</ulink>, nor a Microsoft GUID; however, starting with systemd
v30, newly generated machine IDs do qualify as v4 UUIDs.</para>
<para>Note that the machine ID historically is not an OSF UUID as defined by <ulink
url="https://tools.ietf.org/html/rfc4122">RFC 4122</ulink>, nor a Microsoft GUID; however, starting with
systemd v30, newly generated machine IDs do qualify as Variant 1 Version 4 UUIDs, as per RFC 4122.</para>
<para>In order to maintain compatibility with existing
installations, an application requiring a UUID should decode the
machine ID, and then apply the following operations to turn it
into a valid OSF v4 UUID. With <literal>id</literal> being an
<para>In order to maintain compatibility with existing installations, an application requiring a strictly
RFC 4122 compliant UUID should decode the machine ID, and then (non-reversibly) apply the following
operations to turn it into a valid RFC 4122 Variant 1 Version 4 UUID. With <literal>id</literal> being an
unsigned character array:</para>
<programlisting>/* Set UUID version to 4 --- truly random generation */

25
man/sd-id128.xml
View File

@ -50,13 +50,11 @@
<refsect1>
<title>Description</title>
<para><filename>sd-id128.h</filename> provides APIs to process and
generate 128-bit ID values. The 128-bit ID values processed and
generated by these APIs are a generalization of OSF UUIDs as
defined by <ulink url="https://tools.ietf.org/html/rfc4122">RFC
4122</ulink> but use a simpler string format. These functions
impose no structure on the used IDs, much unlike OSF UUIDs or
Microsoft GUIDs, but are fully compatible with those types of IDs.
<para><filename>sd-id128.h</filename> provides APIs to process and generate 128-bit ID values. The
128-bit ID values processed and generated by these APIs are a generalization of OSF UUIDs as defined by
<ulink url="https://tools.ietf.org/html/rfc4122">RFC 4122</ulink> but use a simpler string format. These
functions impose no structure on the used IDs, much unlike OSF UUIDs or Microsoft GUIDs, but are mostly
compatible with those types of IDs.
</para>
<para>See
@ -101,8 +99,7 @@
int main(int argc, char **argv) {
puts("Match for coredumps: MESSAGE_ID=" SD_MESSAGE_COREDUMP_STR);
}
</programlisting>
}</programlisting>
<para><function>SD_ID128_CONST_STR()</function> may be used to
convert constant 128-bit IDs into constant strings for output. The
@ -125,9 +122,13 @@ int main(int argc, char **argv) {
}</programlisting>
<para><constant>SD_ID128_UUID_FORMAT_STR</constant> is similar to
<constant>SD_ID128_FORMAT_STR</constant> but includes separating hyphens to conform to the
"<ulink url="https://en.wikipedia.org/wiki/Universally_unique_identifier#Format">canonical representation</ulink>".
</para>
<constant>SD_ID128_FORMAT_STR</constant> but includes separating hyphens to conform to the "<ulink
url="https://en.wikipedia.org/wiki/Universally_unique_identifier#Format">canonical
representation</ulink>". This formats the string based on <ulink
url="https://tools.ietf.org/html/rfc4122">RFC4122</ulink> Variant 1 rules, i.e. converting from Big
Endian byte order. This matches behaviour of most other Linux userspace infrastructure. It's probably
best to avoid UUIDs of other variants, in order to avoid unnecessary ambiguities. All 128-bit IDs
generated by the sd-id128 APIs strictly conform to Variant 1 Version 4 UUIDs, as per RFC 4122.</para>
<para>Use <function>sd_id128_equal()</function> to compare two 128-bit IDs:</para>

8
man/sd_id128_get_machine.xml
View File

@ -101,10 +101,10 @@
<para>Note that <function>sd_id128_get_machine_app_specific()</function>,
<function>sd_id128_get_boot()</function>, <function>sd_id128_get_boot_app_specific()</function>, and
<function>sd_id128_get_invocation()</function> always return UUID v4 compatible IDs.
<function>sd_id128_get_machine()</function> will also return a UUID v4-compatible ID on new installations
but might not on older. It is possible to convert the machine ID into a UUID v4-compatible one. For more
information, see
<function>sd_id128_get_invocation()</function> always return UUID Variant 1 Version 4 compatible IDs.
<function>sd_id128_get_machine()</function> will also return a UUID Variant 1 Version 4 compatible ID on
new installations but might not on older. It is possible to convert the machine ID non-reversibly into a
UUID Variant 1 Version 4 compatible one. For more information, see
<citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>. It is
hence guaranteed that these functions will never return the ID consisting of all zero or all one bits
(<constant>SD_ID128_NULL</constant>, <constant>SD_ID128_ALLF</constant>) — with the possible exception of

6
man/sd_id128_randomize.xml
View File

@ -42,9 +42,9 @@
<filename>/dev/urandom</filename> kernel random number
generator.</para>
<para>Note that <function>sd_id128_randomize()</function> always returns a UUID v4-compatible ID. It is
hence guaranteed that this function will never return the ID consisting of all zero or all one bits
(<constant>SD_ID128_NULL</constant>, <constant>SD_ID128_ALLF</constant>).</para>
<para>Note that <function>sd_id128_randomize()</function> always returns a UUID Variant 1 Version 4
compatible ID. It is hence guaranteed that this function will never return the ID consisting of all zero
or all one bits (<constant>SD_ID128_NULL</constant>, <constant>SD_ID128_ALLF</constant>).</para>
<para>For more information about the <literal>sd_id128_t</literal>
type, see

5
man/sd_id128_to_string.xml
View File

@ -54,6 +54,11 @@
<constant>NULL</constant> the function will validate the passed ID string, but not actually return it in parsed
form.</para>
<para>Note that when parsing 37 character UUIDs this is done strictly in Big Endian byte order,
i.e. according to <ulink url="https://tools.ietf.org/html/rfc4122">RFC4122</ulink> Variant 1
rules, even if the UUID encodes a different variant. This matches behaviour in various other Linux
userspace tools. It's probably wise to avoid UUIDs of other variant types.</para>
<para>For more information about the <literal>sd_id128_t</literal>
type see
<citerefentry><refentrytitle>sd-id128</refentrytitle><manvolnum>3</manvolnum></citerefentry>.

4
src/systemd/sd-id128.h
View File

@ -63,7 +63,9 @@ int sd_id128_get_boot_app_specific(sd_id128_t app_id, sd_id128_t *ret);
#define SD_ID128_FORMAT_STR "%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x"
#define SD_ID128_FORMAT_VAL(x) (x).bytes[0], (x).bytes[1], (x).bytes[2], (x).bytes[3], (x).bytes[4], (x).bytes[5], (x).bytes[6], (x).bytes[7], (x).bytes[8], (x).bytes[9], (x).bytes[10], (x).bytes[11], (x).bytes[12], (x).bytes[13], (x).bytes[14], (x).bytes[15]
/* Like SD_ID128_FORMAT_STR, but formats as UUID, not in plain format */
/* Like SD_ID128_FORMAT_STR, but formats as UUID, not in plain format (Strictly Big Endian byte order,
* i.e. treats everything as RFC4122 Variant 1 UUIDs, even if variant says otherwise, but matching other
* Linux userspace behaviour.) */
#define SD_ID128_UUID_FORMAT_STR "%02x%02x%02x%02x-%02x%02x-%02x%02x-%02x%02x-%02x%02x%02x%02x%02x%02x"
#define SD_ID128_CONST_STR(x) \