man/sd_id128_get_machine.xml

   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.5/docbookx.dtd">
   4 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
   5
   6 <refentry id="sd_id128_get_machine" xmlns:xi="http://www.w3.org/2001/XInclude">
   7
   8   <refentryinfo>
   9     <title>sd_id128_get_machine</title>
  10     <productname>systemd</productname>
  11   </refentryinfo>
  12
  13   <refmeta>
  14     <refentrytitle>sd_id128_get_machine</refentrytitle>
  15     <manvolnum>3</manvolnum>
  16   </refmeta>
  17
  18   <refnamediv>
  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>
  26   </refnamediv>
  27
  28   <refsynopsisdiv>
  29     <funcsynopsis>
  30       <funcsynopsisinfo>#include &lt;systemd/sd-id128.h&gt;</funcsynopsisinfo>
  31
  32       <funcprototype>
  33         <funcdef>int <function>sd_id128_get_machine</function></funcdef>
  34         <paramdef>sd_id128_t *<parameter>ret</parameter></paramdef>
  35       </funcprototype>
  36
  37       <funcprototype>
  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>
  42       </funcprototype>
  43
  44       <funcprototype>
  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>
  48       </funcprototype>
  49
  50       <funcprototype>
  51         <funcdef>int <function>sd_id128_get_boot</function></funcdef>
  52         <paramdef>sd_id128_t *<parameter>ret</parameter></paramdef>
  53       </funcprototype>
  54
  55       <funcprototype>
  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>
  59       </funcprototype>
  60
  61       <funcprototype>
  62         <funcdef>int <function>sd_id128_get_invocation</function></funcdef>
  63         <paramdef>sd_id128_t *<parameter>ret</parameter></paramdef>
  64       </funcprototype>
  65
  66       <funcprototype>
  67         <funcdef>int <function>sd_id128_get_invocation_app_specific</function></funcdef>
  68         <paramdef>sd_id128_t <parameter>app_id</parameter></paramdef>
  69         <paramdef>sd_id128_t *<parameter>ret</parameter></paramdef>
  70       </funcprototype>
  71
  72     </funcsynopsis>
  73   </refsynopsisdiv>
  74
  75   <refsect1>
  76     <title>Description</title>
  77
  78     <para><function>sd_id128_get_machine()</function> returns the machine ID of the executing host. This reads and
  79     parses the <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>
  80     file. This function caches the machine ID internally to make retrieving the machine ID a cheap operation. This ID
  81     may be used wherever a unique identifier for the local system is needed. However, it is recommended to use this ID
  82     as-is only in trusted environments. In untrusted environments it is recommended to derive an application specific
  83     ID from this machine ID, in an irreversible (cryptographically secure) way. To make this easy
  84     <function>sd_id128_get_machine_app_specific()</function> is provided, see below.</para>
  85
  86     <para><function>sd_id128_get_app_specific()</function> returns a machine ID that is a combination of the
  87     <parameter>base</parameter> and <parameter>app_id</parameter> parameters. Internally, this function
  88     calculates HMAC-SHA256 of the <parameter>app_id</parameter> parameter keyed by the
  89     <parameter>base</parameter> parameter, and truncates this result to fit in
  90     <structname>sd_id128_t</structname> and turns it into a valid Variant 1 Version 4 UUID, in accordance
  91     with <ulink url="https://tools.ietf.org/html/rfc4122">RFC 4122</ulink>. Neither of the two input
  92     parameters can be calculated from the output parameter <parameter>ret</parameter>.</para>
  93
  94     <para><function>sd_id128_get_machine_app_specific()</function> is similar to
  95     <function>sd_id128_get_machine()</function>, but retrieves a machine ID that is specific to the
  96     application that is identified by the indicated application ID. It is recommended to use this function
  97     instead of <function>sd_id128_get_machine()</function> when passing an ID to untrusted environments, in
  98     order to make sure that the original machine ID may not be determined externally. This way, the ID used
  99     by the application remains stable on a given machine, but cannot be easily correlated with IDs used in
 100     other applications on the same machine. The application-specific ID should be generated via a tool like
 101     <command>systemd-id128 new</command>, and may be compiled into the application. This function will return
 102     the same application-specific ID for each combination of machine ID and application ID. Internally, this
 103     function calls <function>sd_id128_get_app_specific()</function> with the result from
 104     <function>sd_id128_get_machine()</function> and the <parameter>app_id</parameter> parameter.</para>
 105
 106     <para><function>sd_id128_get_boot()</function> returns the boot ID of the executing kernel. This reads and parses
 107     the <filename>/proc/sys/kernel/random/boot_id</filename> file exposed by the kernel. It is randomly generated early
 108     at boot and is unique for every running kernel instance. See <citerefentry
 109     project='man-pages'><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry> for more
 110     information. This function also internally caches the returned ID to make this call a cheap operation. It is
 111     recommended to use this ID as-is only in trusted environments. In untrusted environments it is recommended to
 112     derive an application specific ID using <function>sd_id128_get_boot_app_specific()</function>, see below.</para>
 113
 114     <para><function>sd_id128_get_boot_app_specific()</function> is analogous to
 115     <function>sd_id128_get_machine_app_specific()</function>, but returns an ID that changes between
 116     boots. Some machines may be used for a long time without rebooting, hence the boot ID may remain constant
 117     for a long time, and has properties similar to the machine ID during that time.</para>
 118
 119     <para><function>sd_id128_get_invocation()</function> returns the invocation ID of the currently executed
 120     service. In its current implementation, this tries to read and parse the following:
 121     <itemizedlist>
 122       <listitem>
 123         <para>The <varname>$INVOCATION_ID</varname> environment variable that the service manager sets when
 124         activating a service.</para>
 125       </listitem>
 126       <listitem>
 127         <para>An entry in the kernel keyring that the system service manager sets when activating a service.
 128         </para>
 129       </listitem>
 130     </itemizedlist>
 131     See <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 132     for details. The ID is cached internally. In future a different mechanism to determine the invocation ID
 133     may be added.</para>
 134
 135     <para><function>sd_id128_get_invocation_app_specific()</function> derives an application-specific ID from
 136     the invocation ID.</para>
 137
 138     <para>Note that <function>sd_id128_get_machine_app_specific()</function>,
 139     <function>sd_id128_get_boot()</function>, <function>sd_id128_get_boot_app_specific()</function>,
 140     <function>sd_id128_get_invocation()</function> and
 141     <function>sd_id128_get_invocation_app_specific</function> always return UUID Variant 1 Version 4
 142     compatible IDs. <function>sd_id128_get_machine()</function> will also return a UUID Variant 1 Version 4
 143     compatible ID on new installations but might not on older. It is possible to convert the machine ID
 144     non-reversibly into a UUID Variant 1 Version 4 compatible one. For more information, see
 145     <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>. It is
 146     hence guaranteed that these functions will never return the ID consisting of all zero or all one bits
 147     (<constant>SD_ID128_NULL</constant>, <constant>SD_ID128_ALLF</constant>) — with the possible exception of
 148     <function>sd_id128_get_machine()</function>, as mentioned.</para>
 149
 150     <para>For more information about the <literal>sd_id128_t</literal>
 151     type see
 152     <citerefentry><refentrytitle>sd-id128</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
 153   </refsect1>
 154
 155   <refsect1>
 156     <title>Return Value</title>
 157
 158     <para>Those calls return 0 on success (in which case <parameter>ret</parameter> is filled in),
 159     or a negative errno-style error code.</para>
 160
 161     <refsect2>
 162       <title>Errors</title>
 163       <para>Returned errors may indicate the following problems:</para>
 164
 165       <variablelist>
 166         <varlistentry>
 167           <term><constant>-ENOENT</constant></term>
 168
 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 missing.</para>
 172
 173           <xi:include href="version-info.xml" xpointer="v242"/></listitem>
 174         </varlistentry>
 175
 176         <varlistentry>
 177           <term><constant>-ENOMEDIUM</constant></term>
 178
 179           <listitem><para>Returned by <function>sd_id128_get_machine()</function> and
 180           <function>sd_id128_get_machine_app_specific()</function> when <filename>/etc/machine-id</filename>
 181           is empty or all zeros. Also returned by <function>sd_id128_get_invocation()</function> when the
 182           invocation ID is all zeros.</para>
 183
 184           <xi:include href="version-info.xml" xpointer="v242"/></listitem>
 185         </varlistentry>
 186
 187         <varlistentry>
 188           <term><constant>-ENOPKG</constant></term>
 189
 190           <listitem><para>Returned by <function>sd_id128_get_machine()</function> and
 191           <function>sd_id128_get_machine_app_specific()</function> when the content of
 192           <filename>/etc/machine-id</filename> is <literal>uninitialized</literal>.</para>
 193
 194           <xi:include href="version-info.xml" xpointer="v253"/></listitem>
 195         </varlistentry>
 196
 197         <varlistentry>
 198           <term><constant>-ENOSYS</constant></term>
 199
 200           <listitem><para>Returned by <function>sd_id128_get_boot()</function> and
 201           <function>sd_id128_get_boot_app_specific()</function> when <filename>/proc/</filename> is not
 202           mounted.</para>
 203
 204           <xi:include href="version-info.xml" xpointer="v253"/></listitem>
 205         </varlistentry>
 206
 207         <varlistentry>
 208           <term><constant>-ENXIO</constant></term>
 209
 210           <listitem><para>Returned by <function>sd_id128_get_invocation()</function> if no invocation ID is
 211           set. Also returned by <function>sd_id128_get_app_specific()</function>,
 212           <function>sd_id128_get_machine_app_specific()</function>, and
 213           <function>sd_id128_get_boot_app_specific()</function> when the <parameter>app_id</parameter>
 214           parameter is all zeros.</para>
 215
 216           <xi:include href="version-info.xml" xpointer="v242"/></listitem>
 217         </varlistentry>
 218
 219         <varlistentry>
 220           <term><constant>-EUCLEAN</constant></term>
 221
 222           <listitem><para>Returned by any of the functions described here when the configured value has
 223           invalid format.</para>
 224
 225           <xi:include href="version-info.xml" xpointer="v253"/></listitem>
 226         </varlistentry>
 227
 228         <varlistentry>
 229           <term><constant>-EPERM</constant></term>
 230
 231           <listitem><para>Requested information could not be retrieved because of insufficient permissions.
 232           </para>
 233
 234           <xi:include href="version-info.xml" xpointer="v242"/></listitem>
 235         </varlistentry>
 236       </variablelist>
 237     </refsect2>
 238   </refsect1>
 239
 240   <xi:include href="libsystemd-pkgconfig.xml" />
 241
 242   <refsect1>
 243     <title>Examples</title>
 244
 245     <example>
 246       <title>Application-specific machine ID</title>
 247
 248       <para>First, generate the application ID:</para>
 249       <programlisting>$ systemd-id128 -p new
 250 As string:
 251 c273277323db454ea63bb96e79b53e97
 252
 253 As UUID:
 254 c2732773-23db-454e-a63b-b96e79b53e97
 255
 256 As man:sd-id128(3) macro:
 257 #define MESSAGE_XYZ SD_ID128_MAKE(c2,73,27,73,23,db,45,4e,a6,3b,b9,6e,79,b5,3e,97)
 258 ...
 259 </programlisting>
 260
 261       <para>Then use the new identifier in an example application:</para>
 262
 263       <programlisting><xi:include href="id128-app-specific.c" parse="text" /></programlisting>
 264     </example>
 265   </refsect1>
 266
 267   <refsect1>
 268     <title>History</title>
 269     <para><function>sd_id128_get_machine()</function> and
 270     <function>sd_id128_get_boot()</function> were added in version 187.</para>
 271     <para><function>sd_id128_get_invocation()</function> was added in version 232.</para>
 272     <para><function>sd_id128_get_machine_app_specific()</function> was added in version 233.</para>
 273     <para><function>sd_id128_get_boot_app_specific()</function> was added in version 240.</para>
 274     <para><function>sd_id128_get_app_specific()</function> was added in version 255.</para>
 275     <para><function>sd_id128_get_invocation_app_specific()</function> was added in version 256.</para>
 276   </refsect1>
 277
 278   <refsect1>
 279     <title>See Also</title>
 280
 281     <para><simplelist type="inline">
 282       <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 283       <member><citerefentry><refentrytitle>systemd-id128</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 284       <member><citerefentry><refentrytitle>sd-id128</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
 285       <member><citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
 286       <member><citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
 287       <member><citerefentry><refentrytitle>sd_id128_randomize</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
 288       <member><citerefentry project='man-pages'><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry></member>
 289     </simplelist></para>
 290   </refsect1>
 291
 292 </refentry>