X-Git-Url: http://git.ipfire.org/?a=blobdiff_plain;f=man%2Fsd_id128_get_machine.xml;h=8b58e0fcf1d5f626b9f6e27b5a669252693d50ab;hb=13a69c120bc584e90f863f821710b3b5294cd206;hp=bb85d8839f4daa6de6567347aa3aeb5e91a5598c;hpb=9df91db5e09a53cffd9df846c113108d0bd9726f;p=thirdparty%2Fsystemd.git diff --git a/man/sd_id128_get_machine.xml b/man/sd_id128_get_machine.xml index bb85d8839f4..8b58e0fcf1d 100644 --- a/man/sd_id128_get_machine.xml +++ b/man/sd_id128_get_machine.xml @@ -1,7 +1,7 @@ - + @@ -17,6 +17,7 @@ sd_id128_get_machine + sd_id128_get_app_specific sd_id128_get_machine_app_specific sd_id128_get_boot sd_id128_get_boot_app_specific @@ -33,6 +34,13 @@ sd_id128_t *ret + + int sd_id128_get_app_specific + sd_id128_t base + sd_id128_t app_id + sd_id128_t *ret + + int sd_id128_get_machine_app_specific sd_id128_t app_id @@ -69,16 +77,25 @@ ID from this machine ID, in an irreversible (cryptographically secure) way. To make this easy sd_id128_get_machine_app_specific() is provided, see below. + sd_id128_get_app_specific() returns a machine ID that is a combination of the + base and app_id parameters. Internally, this function + calculates HMAC-SHA256 of the app_id parameter keyed by the + base parameter, and truncates this result to fit in + sd_id128_t and turns it into a valid Variant 1 Version 4 UUID, in accordance + with RFC 4122. Neither of the two input + parameters can be calculated from the output parameter ret. + sd_id128_get_machine_app_specific() is similar to - sd_id128_get_machine(), but retrieves a machine ID that is specific to the application that is - identified by the indicated application ID. It is recommended to use this function instead of - sd_id128_get_machine() when passing an ID to untrusted environments, in order to make sure - that the original machine ID may not be determined externally. This way, the ID used by the application remains - stable on a given machine, but cannot be easily correlated with IDs used in other applications on the same - machine. The application-specific ID should be generated via a tool like systemd-id128 new, - and may be compiled into the application. This function will return the same application-specific ID for each - combination of machine ID and application ID. Internally, this function calculates HMAC-SHA256 of the application - ID, keyed by the machine ID. + sd_id128_get_machine(), but retrieves a machine ID that is specific to the + application that is identified by the indicated application ID. It is recommended to use this function + instead of sd_id128_get_machine() when passing an ID to untrusted environments, in + order to make sure that the original machine ID may not be determined externally. This way, the ID used + by the application remains stable on a given machine, but cannot be easily correlated with IDs used in + other applications on the same machine. The application-specific ID should be generated via a tool like + systemd-id128 new, and may be compiled into the application. This function will return + the same application-specific ID for each combination of machine ID and application ID. Internally, this + function calls sd_id128_get_app_specific() with the result from + sd_id128_get_machine() and the app_id parameter. sd_id128_get_boot() returns the boot ID of the executing kernel. This reads and parses the /proc/sys/kernel/random/boot_id file exposed by the kernel. It is randomly generated early @@ -86,25 +103,39 @@ project='man-pages'>random4 for more information. This function also internally caches the returned ID to make this call a cheap operation. It is recommended to use this ID as-is only in trusted environments. In untrusted environments it is recommended to - derive an application specific ID using sd_id128_get_machine_app_specific(), see below. + derive an application specific ID using sd_id128_get_boot_app_specific(), see below. sd_id128_get_boot_app_specific() is analogous to - sd_id128_get_machine_app_specific() but returns an ID that changes between boots. Some - machines may be used for a long time without rebooting, hence the boot ID may remain constant for a long time, and - has properties similar to the machine ID during that time. + sd_id128_get_machine_app_specific(), but returns an ID that changes between + boots. Some machines may be used for a long time without rebooting, hence the boot ID may remain constant + for a long time, and has properties similar to the machine ID during that time. sd_id128_get_invocation() returns the invocation ID of the currently executed - service. In its current implementation, this reads and parses the $INVOCATION_ID environment - variable that the service manager sets when activating a service, see - systemd.exec5 for details. The - ID is cached internally. In future a different mechanism to determine the invocation ID may be added. - - 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 - machine-id5. + service. In its current implementation, this tries to read and parse the following: + + + The $INVOCATION_ID environment variable that the service manager sets when + activating a service. + + + An entry in the kernel keyring that the system service manager sets when activating a service. + + + + See systemd.exec5 + for details. The ID is cached internally. In future a different mechanism to determine the invocation ID + may be added. + + 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 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 + sd_id128_get_machine(), as mentioned. For more information about the sd_id128_t type see @@ -125,40 +156,72 @@ -ENOENT - Returned by sd_id128_get_machine(), - sd_id128_get_machine_app_specific(), and - sd_id128_get_boot_app_specific() when /etc/machine-id is - missing. + Returned by sd_id128_get_machine() and + sd_id128_get_machine_app_specific() when /etc/machine-id + is missing. + + -ENOMEDIUM - Returned by sd_id128_get_machine(), - sd_id128_get_machine_app_specific(), and - sd_id128_get_boot_app_specific() when /etc/machine-id is - empty or all zeros. + Returned by sd_id128_get_machine() and + sd_id128_get_machine_app_specific() when /etc/machine-id + is empty or all zeros. Also returned by sd_id128_get_invocation() when the + invocation ID is all zeros. + + + + + + -ENOPKG + + Returned by sd_id128_get_machine() and + sd_id128_get_machine_app_specific() when the content of + /etc/machine-id is uninitialized. + + + + + + -ENOSYS + + Returned by sd_id128_get_boot() and + sd_id128_get_boot_app_specific() when /proc/ is not + mounted. + + -ENXIO Returned by sd_id128_get_invocation() if no invocation ID is - set. + set. Also returned by sd_id128_get_app_specific(), + sd_id128_get_machine_app_specific(), and + sd_id128_get_boot_app_specific() when the app_id + parameter is all zeros. + + - -EIO + -EUCLEAN Returned by any of the functions described here when the configured value has - invalid format. + invalid format. + + -EPERM Requested information could not be retrieved because of insufficient permissions. - + + + @@ -191,18 +254,28 @@ As man:sd-id128(3) macro: + + History + sd_id128_get_machine() and + sd_id128_get_boot() were added in version 187. + sd_id128_get_invocation() was added in version 232. + sd_id128_get_machine_app_specific() was added in version 233. + sd_id128_get_boot_app_specific() was added in version 240. + sd_id128_get_app_specific() was added in version 255. + + See Also - - systemd1, - systemd-id1281, - sd-id1283, - machine-id5, - systemd.exec5, - sd_id128_randomize3, - random4 - + + systemd1 + systemd-id1281 + sd-id1283 + machine-id5 + systemd.exec5 + sd_id128_randomize3 + random4 +