- that the original machine ID may not be determined externally. The application-specific ID should be generated via
- a tool like <command>journalctl --new-id128</command>, 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.</para>
-
- <para><function>sd_id128_get_boot()</function> returns the boot ID
- of the executing kernel. This reads and parses the
- <filename>/proc/sys/kernel/random/boot_id</filename> file exposed
- by the kernel. It is randomly generated early at boot and is
- unique for every running kernel instance. See
- <citerefentry project='man-pages'><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry>
- for more information. This function also internally caches the
- returned ID to make this call a cheap operation.</para>
+ 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 <command>systemd-id128 new</command>,
+ 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.</para>
+
+ <para><function>sd_id128_get_boot()</function> returns the boot ID of the executing kernel. This reads and parses
+ the <filename>/proc/sys/kernel/random/boot_id</filename> file exposed by the kernel. It is randomly generated early
+ at boot and is unique for every running kernel instance. See <citerefentry
+ project='man-pages'><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry> 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 <function>sd_id128_get_machine_app_specific()</function>, see below.</para>
+
+ <para><function>sd_id128_get_boot_app_specific()</function> is analogous to
+ <function>sd_id128_get_machine_app_specific()</function> 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.</para>