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 @@ Relation to OSF UUIDs - Note that the machine ID historically is not an OSF UUID as - defined by RFC - 4122, nor a Microsoft GUID; however, starting with systemd - v30, newly generated machine IDs do qualify as v4 UUIDs. + Note that the machine ID historically is not an OSF UUID as defined by RFC 4122, 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. - 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 id being an + 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 id being an unsigned character array: /* 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 @@ Description - sd-id128.h 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 RFC - 4122 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. + sd-id128.h 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 + RFC 4122 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. See @@ -101,8 +99,7 @@ int main(int argc, char **argv) { puts("Match for coredumps: MESSAGE_ID=" SD_MESSAGE_COREDUMP_STR); -} - +} SD_ID128_CONST_STR() 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) { } SD_ID128_UUID_FORMAT_STR is similar to - SD_ID128_FORMAT_STR but includes separating hyphens to conform to the - "canonical representation". - + SD_ID128_FORMAT_STR but includes separating hyphens to conform to the "canonical + representation". This formats the string based on RFC4122 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. Use sd_id128_equal() to compare two 128-bit IDs: 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 @@ Note that sd_id128_get_machine_app_specific(), sd_id128_get_boot(), sd_id128_get_boot_app_specific(), and - sd_id128_get_invocation() always return UUID v4 compatible IDs. - sd_id128_get_machine() 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 + sd_id128_get_invocation() always return UUID Variant 1 Version 4 compatible IDs. + sd_id128_get_machine() 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 machine-id5. It is hence guaranteed that these functions will never return the ID consisting of all zero or all one bits (SD_ID128_NULL, SD_ID128_ALLF) — 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 @@ /dev/urandom kernel random number generator. - Note that sd_id128_randomize() 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 - (SD_ID128_NULL, SD_ID128_ALLF). + Note that sd_id128_randomize() 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 (SD_ID128_NULL, SD_ID128_ALLF). For more information about the sd_id128_t 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 @@ NULL the function will validate the passed ID string, but not actually return it in parsed form. + Note that when parsing 37 character UUIDs this is done strictly in Big Endian byte order, + i.e. according to RFC4122 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. + For more information about the sd_id128_t type see sd-id1283. 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) \