From b5c27ebca449c41fbd8a4e37ade98e963c370dd3 Mon Sep 17 00:00:00 2001 From: Zbigniew Jędrzejewski-Szmek Date: Sat, 26 Aug 2023 13:07:32 +0200 Subject: man: document sd_id128_get_app_specific --- man/rules/meson.build | 3 ++- man/sd_id128_get_machine.xml | 41 +++++++++++++++++++++++++++++------------ 2 files changed, 31 insertions(+), 13 deletions(-) diff --git a/man/rules/meson.build b/man/rules/meson.build index eaaf4adb1b..2884cc32b4 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -672,7 +672,8 @@ manpages = [ ''], ['sd_id128_get_machine', '3', - ['sd_id128_get_boot', + ['sd_id128_get_app_specific', + 'sd_id128_get_boot', 'sd_id128_get_boot_app_specific', 'sd_id128_get_invocation', 'sd_id128_get_machine_app_specific'], diff --git a/man/sd_id128_get_machine.xml b/man/sd_id128_get_machine.xml index 40b9b6f582..fc13ae50f4 100644 --- a/man/sd_id128_get_machine.xml +++ b/man/sd_id128_get_machine.xml @@ -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 @@ -89,9 +106,9 @@ 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 tries to read and parse the following: -- cgit v1.2.3