1 <?xml version='
1.0'
?> <!--*-nxml-*-->
2 <!DOCTYPE refentry PUBLIC
"-//OASIS//DTD DocBook XML V4.5//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
6 <refentry id=
"sd_id128_get_machine" xmlns:
xi=
"http://www.w3.org/2001/XInclude">
9 <title>sd_id128_get_machine
</title>
10 <productname>systemd
</productname>
14 <refentrytitle>sd_id128_get_machine
</refentrytitle>
15 <manvolnum>3</manvolnum>
19 <refname>sd_id128_get_machine
</refname>
20 <refname>sd_id128_get_app_specific
</refname>
21 <refname>sd_id128_get_machine_app_specific
</refname>
22 <refname>sd_id128_get_boot
</refname>
23 <refname>sd_id128_get_boot_app_specific
</refname>
24 <refname>sd_id128_get_invocation
</refname>
25 <refpurpose>Retrieve
128-bit IDs
</refpurpose>
30 <funcsynopsisinfo>#include
<systemd/sd-id128.h
></funcsynopsisinfo>
33 <funcdef>int
<function>sd_id128_get_machine
</function></funcdef>
34 <paramdef>sd_id128_t *
<parameter>ret
</parameter></paramdef>
38 <funcdef>int
<function>sd_id128_get_app_specific
</function></funcdef>
39 <paramdef>sd_id128_t
<parameter>base
</parameter></paramdef>
40 <paramdef>sd_id128_t
<parameter>app_id
</parameter></paramdef>
41 <paramdef>sd_id128_t *
<parameter>ret
</parameter></paramdef>
45 <funcdef>int
<function>sd_id128_get_machine_app_specific
</function></funcdef>
46 <paramdef>sd_id128_t
<parameter>app_id
</parameter></paramdef>
47 <paramdef>sd_id128_t *
<parameter>ret
</parameter></paramdef>
51 <funcdef>int
<function>sd_id128_get_boot
</function></funcdef>
52 <paramdef>sd_id128_t *
<parameter>ret
</parameter></paramdef>
56 <funcdef>int
<function>sd_id128_get_boot_app_specific
</function></funcdef>
57 <paramdef>sd_id128_t
<parameter>app_id
</parameter></paramdef>
58 <paramdef>sd_id128_t *
<parameter>ret
</parameter></paramdef>
62 <funcdef>int
<function>sd_id128_get_invocation
</function></funcdef>
63 <paramdef>sd_id128_t *
<parameter>ret
</parameter></paramdef>
70 <title>Description
</title>
72 <para><function>sd_id128_get_machine()
</function> returns the machine ID of the executing host. This reads and
73 parses the
<citerefentry><refentrytitle>machine-id
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
74 file. This function caches the machine ID internally to make retrieving the machine ID a cheap operation. This ID
75 may be used wherever a unique identifier for the local system is needed. However, it is recommended to use this ID
76 as-is only in trusted environments. In untrusted environments it is recommended to derive an application specific
77 ID from this machine ID, in an irreversible (cryptographically secure) way. To make this easy
78 <function>sd_id128_get_machine_app_specific()
</function> is provided, see below.
</para>
80 <para><function>sd_id128_get_app_specific()
</function> returns a machine ID that is a combination of the
81 <parameter>base
</parameter> and
<parameter>app_id
</parameter> parameters. Internally, this function
82 calculates HMAC-SHA256 of the
<parameter>app_id
</parameter> parameter keyed by the
83 <parameter>base
</parameter> parameter, and truncates this result to fit in
84 <structname>sd_id128_t
</structname> and turns it into a valid Variant
1 Version
4 UUID, in accordance
85 with
<ulink url=
"https://tools.ietf.org/html/rfc4122">RFC
4122</ulink>. Neither of the two input
86 parameters can be calculated from the output parameter
<parameter>ret
</parameter>.
</para>
88 <para><function>sd_id128_get_machine_app_specific()
</function> is similar to
89 <function>sd_id128_get_machine()
</function>, but retrieves a machine ID that is specific to the
90 application that is identified by the indicated application ID. It is recommended to use this function
91 instead of
<function>sd_id128_get_machine()
</function> when passing an ID to untrusted environments, in
92 order to make sure that the original machine ID may not be determined externally. This way, the ID used
93 by the application remains stable on a given machine, but cannot be easily correlated with IDs used in
94 other applications on the same machine. The application-specific ID should be generated via a tool like
95 <command>systemd-id128 new
</command>, and may be compiled into the application. This function will return
96 the same application-specific ID for each combination of machine ID and application ID. Internally, this
97 function calls
<function>sd_id128_get_app_specific()
</function> with the result from
98 <function>sd_id128_get_machine()
</function> and the
<parameter>app_id
</parameter> parameter.
</para>
100 <para><function>sd_id128_get_boot()
</function> returns the boot ID of the executing kernel. This reads and parses
101 the
<filename>/proc/sys/kernel/random/boot_id
</filename> file exposed by the kernel. It is randomly generated early
102 at boot and is unique for every running kernel instance. See
<citerefentry
103 project='man-pages'
><refentrytitle>random
</refentrytitle><manvolnum>4</manvolnum></citerefentry> for more
104 information. This function also internally caches the returned ID to make this call a cheap operation. It is
105 recommended to use this ID as-is only in trusted environments. In untrusted environments it is recommended to
106 derive an application specific ID using
<function>sd_id128_get_boot_app_specific()
</function>, see below.
</para>
108 <para><function>sd_id128_get_boot_app_specific()
</function> is analogous to
109 <function>sd_id128_get_machine_app_specific()
</function>, but returns an ID that changes between
110 boots. Some machines may be used for a long time without rebooting, hence the boot ID may remain constant
111 for a long time, and has properties similar to the machine ID during that time.
</para>
113 <para><function>sd_id128_get_invocation()
</function> returns the invocation ID of the currently executed
114 service. In its current implementation, this tries to read and parse the following:
117 <para>The
<varname>$INVOCATION_ID
</varname> environment variable that the service manager sets when
118 activating a service.
</para>
121 <para>An entry in the kernel keyring that the system service manager sets when activating a service.
125 See
<citerefentry><refentrytitle>systemd.exec
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
126 for details. The ID is cached internally. In future a different mechanism to determine the invocation ID
129 <para>Note that
<function>sd_id128_get_machine_app_specific()
</function>,
130 <function>sd_id128_get_boot()
</function>,
<function>sd_id128_get_boot_app_specific()
</function>, and
131 <function>sd_id128_get_invocation()
</function> always return UUID Variant
1 Version
4 compatible IDs.
132 <function>sd_id128_get_machine()
</function> will also return a UUID Variant
1 Version
4 compatible ID on
133 new installations but might not on older. It is possible to convert the machine ID non-reversibly into a
134 UUID Variant
1 Version
4 compatible one. For more information, see
135 <citerefentry><refentrytitle>machine-id
</refentrytitle><manvolnum>5</manvolnum></citerefentry>. It is
136 hence guaranteed that these functions will never return the ID consisting of all zero or all one bits
137 (
<constant>SD_ID128_NULL
</constant>,
<constant>SD_ID128_ALLF
</constant>) — with the possible exception of
138 <function>sd_id128_get_machine()
</function>, as mentioned.
</para>
140 <para>For more information about the
<literal>sd_id128_t
</literal>
142 <citerefentry><refentrytitle>sd-id128
</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
</para>
146 <title>Return Value
</title>
148 <para>Those calls return
0 on success (in which case
<parameter>ret
</parameter> is filled in),
149 or a negative errno-style error code.
</para>
152 <title>Errors
</title>
153 <para>Returned errors may indicate the following problems:
</para>
157 <term><constant>-ENOENT
</constant></term>
159 <listitem><para>Returned by
<function>sd_id128_get_machine()
</function> and
160 <function>sd_id128_get_machine_app_specific()
</function> when
<filename>/etc/machine-id
</filename>
163 <xi:include href=
"version-info.xml" xpointer=
"v242"/></listitem>
167 <term><constant>-ENOMEDIUM
</constant></term>
169 <listitem><para>Returned by
<function>sd_id128_get_machine()
</function> and
170 <function>sd_id128_get_machine_app_specific()
</function> when
<filename>/etc/machine-id
</filename>
171 is empty or all zeros. Also returned by
<function>sd_id128_get_invocation()
</function> when the
172 invocation ID is all zeros.
</para>
174 <xi:include href=
"version-info.xml" xpointer=
"v242"/></listitem>
178 <term><constant>-ENOPKG
</constant></term>
180 <listitem><para>Returned by
<function>sd_id128_get_machine()
</function> and
181 <function>sd_id128_get_machine_app_specific()
</function> when the content of
182 <filename>/etc/machine-id
</filename> is
<literal>uninitialized
</literal>.
</para>
184 <xi:include href=
"version-info.xml" xpointer=
"v253"/></listitem>
188 <term><constant>-ENOSYS
</constant></term>
190 <listitem><para>Returned by
<function>sd_id128_get_boot()
</function> and
191 <function>sd_id128_get_boot_app_specific()
</function> when
<filename>/proc/
</filename> is not
194 <xi:include href=
"version-info.xml" xpointer=
"v253"/></listitem>
198 <term><constant>-ENXIO
</constant></term>
200 <listitem><para>Returned by
<function>sd_id128_get_invocation()
</function> if no invocation ID is
201 set. Also returned by
<function>sd_id128_get_app_specific()
</function>,
202 <function>sd_id128_get_machine_app_specific()
</function>, and
203 <function>sd_id128_get_boot_app_specific()
</function> when the
<parameter>app_id
</parameter>
204 parameter is all zeros.
</para>
206 <xi:include href=
"version-info.xml" xpointer=
"v242"/></listitem>
210 <term><constant>-EUCLEAN
</constant></term>
212 <listitem><para>Returned by any of the functions described here when the configured value has
213 invalid format.
</para>
215 <xi:include href=
"version-info.xml" xpointer=
"v253"/></listitem>
219 <term><constant>-EPERM
</constant></term>
221 <listitem><para>Requested information could not be retrieved because of insufficient permissions.
224 <xi:include href=
"version-info.xml" xpointer=
"v242"/></listitem>
230 <xi:include href=
"libsystemd-pkgconfig.xml" />
233 <title>Examples
</title>
236 <title>Application-specific machine ID
</title>
238 <para>First, generate the application ID:
</para>
239 <programlisting>$ systemd-id128 -p new
241 c273277323db454ea63bb96e79b53e97
244 c2732773-
23db-
454e-a63b-b96e79b53e97
246 As man:sd-id128(
3) macro:
247 #define MESSAGE_XYZ SD_ID128_MAKE(c2,
73,
27,
73,
23,db,
45,
4e,a6,
3b,b9,
6e,
79,b5,
3e,
97)
251 <para>Then use the new identifier in an example application:
</para>
253 <programlisting><xi:include href=
"id128-app-specific.c" parse=
"text" /></programlisting>
258 <title>History
</title>
259 <para><function>sd_id128_get_machine()
</function> and
260 <function>sd_id128_get_boot()
</function> were added in version
187.
</para>
261 <para><function>sd_id128_get_invocation()
</function> was added in version
232.
</para>
262 <para><function>sd_id128_get_machine_app_specific()
</function> was added in version
233.
</para>
263 <para><function>sd_id128_get_boot_app_specific()
</function> was added in version
240.
</para>
264 <para><function>sd_id128_get_app_specific()
</function> was added in version
255.
</para>
268 <title>See Also
</title>
271 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
272 <citerefentry><refentrytitle>systemd-id128
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
273 <citerefentry><refentrytitle>sd-id128
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
274 <citerefentry><refentrytitle>machine-id
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
275 <citerefentry><refentrytitle>systemd.exec
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
276 <citerefentry><refentrytitle>sd_id128_randomize
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
277 <citerefentry project='man-pages'
><refentrytitle>random
</refentrytitle><manvolnum>4</manvolnum></citerefentry>