diff options
| -rw-r--r-- | man/machine-id.xml | 16 | ||||
| -rw-r--r-- | man/sd-id128.xml | 25 | ||||
| -rw-r--r-- | man/sd_id128_get_machine.xml | 8 | ||||
| -rw-r--r-- | man/sd_id128_randomize.xml | 6 | ||||
| -rw-r--r-- | man/sd_id128_to_string.xml | 5 | ||||
| -rw-r--r-- | src/systemd/sd-id128.h | 4 |
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) \ |