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