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

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.

6 files changed, 35 insertions, 29 deletions

diff --git a/man/machine-id.xml b/man/machine-id.xml
index f61634fde5..d5d3a1a299 100644
--- a/man/machine-id.xml
+++ b/man/machine-id.xml
@@ -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>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>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 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 */
diff --git a/man/sd-id128.xml b/man/sd-id128.xml
index 1890f6d6a5..716c62522d 100644
--- a/man/sd-id128.xml
+++ b/man/sd-id128.xml
@@ -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>
 
diff --git a/man/sd_id128_get_machine.xml b/man/sd_id128_get_machine.xml
index caf4caa300..a778f8a2b0 100644
--- a/man/sd_id128_get_machine.xml
+++ b/man/sd_id128_get_machine.xml
@@ -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
diff --git a/man/sd_id128_randomize.xml b/man/sd_id128_randomize.xml
index 0bc1d0abd8..52fa089ec3 100644
--- a/man/sd_id128_randomize.xml
+++ b/man/sd_id128_randomize.xml
@@ -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
diff --git a/man/sd_id128_to_string.xml b/man/sd_id128_to_string.xml
index 54cab1af5a..469768050b 100644
--- a/man/sd_id128_to_string.xml
+++ b/man/sd_id128_to_string.xml
@@ -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>.
diff --git a/src/systemd/sd-id128.h b/src/systemd/sd-id128.h
index ab209c8c7d..90d4bbf14e 100644
--- a/src/systemd/sd-id128.h
+++ b/src/systemd/sd-id128.h
@@ -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)                                           \