- <para><function>sd_id128_get_machine()</function> returns the
- machine ID of the executing host. This reads and parses the
- <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>
- file. This function caches the machine ID internally to make
- retrieving the machine ID a cheap operation.</para>
+ <para><function>sd_id128_get_machine()</function> returns the machine ID of the executing host. This reads and
+ parses the <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ file. This function caches the machine ID internally to make retrieving the machine ID a cheap operation. This ID
+ may be used wherever a unique identifier for the local system is needed. However, 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 from this machine ID, in an irreversable (cryptographically secure) way. To make this easy
+ <function>sd_id128_get_machine_app_specific()</function> is provided, see below.</para>
+
+ <para><function>sd_id128_get_machine_app_specific()</function> is similar to
+ <function>sd_id128_get_machine()</function>, 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
+ <function>sd_id128_get_machine()</function> when passing an ID to untrusted environments, in order to make sure
+ 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>