Debian Codegraph @

upstream/debian-unstable/man3/sd_id128_get_machine.3

raw
1 '\" t
2 .TH "SD_ID128_GET_MACHINE" "3" "" "systemd 261~rc3" "sd_id128_get_machine"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 sd_id128_get_machine, sd_id128_get_app_specific, sd_id128_get_machine_app_specific, sd_id128_get_boot, sd_id128_get_boot_app_specific, sd_id128_get_invocation \- Retrieve 128\-bit IDs
24 .SH "SYNOPSIS"
25 .sp
26 .ft B
27 .nf
28 #include <systemd/sd\-id128\&.h>
29 .fi
30 .ft
31 .HP \w'int\ sd_id128_get_machine('u
32 .BI "int sd_id128_get_machine(sd_id128_t\ *" "ret" ");"
33 .HP \w'int\ sd_id128_get_app_specific('u
34 .BI "int sd_id128_get_app_specific(sd_id128_t\ " "base" ", sd_id128_t\ " "app_id" ", sd_id128_t\ *" "ret" ");"
35 .HP \w'int\ sd_id128_get_machine_app_specific('u
36 .BI "int sd_id128_get_machine_app_specific(sd_id128_t\ " "app_id" ", sd_id128_t\ *" "ret" ");"
37 .HP \w'int\ sd_id128_get_boot('u
38 .BI "int sd_id128_get_boot(sd_id128_t\ *" "ret" ");"
39 .HP \w'int\ sd_id128_get_boot_app_specific('u
40 .BI "int sd_id128_get_boot_app_specific(sd_id128_t\ " "app_id" ", sd_id128_t\ *" "ret" ");"
41 .HP \w'int\ sd_id128_get_invocation('u
42 .BI "int sd_id128_get_invocation(sd_id128_t\ *" "ret" ");"
43 .HP \w'int\ sd_id128_get_invocation_app_specific('u
44 .BI "int sd_id128_get_invocation_app_specific(sd_id128_t\ " "app_id" ", sd_id128_t\ *" "ret" ");"
45 .SH "DESCRIPTION"
46 .PP
47 \fBsd_id128_get_machine()\fR
48 returns the machine ID of the executing host\&. This reads and parses the
49 \fBmachine-id\fR(5)
50 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 irreversible (cryptographically secure) way\&. To make this easy
51 \fBsd_id128_get_machine_app_specific()\fR
52 is provided, see below\&.
53 .PP
54 \fBsd_id128_get_app_specific()\fR
55 returns a machine ID that is a combination of the
56 \fIbase\fR
57 and
58 \fIapp_id\fR
59 parameters\&. Internally, this function calculates HMAC\-SHA256 of the
60 \fIapp_id\fR
61 parameter keyed by the
62 \fIbase\fR
63 parameter, and truncates this result to fit in
64 sd_id128_t
65 and turns it into a valid Variant 1 Version 4 UUID, in accordance with
66 \m[blue]\fBRFC 4122\fR\m[]\&\s-2\u[1]\d\s+2\&. Neither of the two input parameters can be calculated from the output parameter
67 \fIret\fR\&.
68 .PP
69 \fBsd_id128_get_machine_app_specific()\fR
70 is similar to
71 \fBsd_id128_get_machine()\fR, 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
72 \fBsd_id128_get_machine()\fR
73 when passing an ID to untrusted environments, in order to make sure 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
74 \fBsystemd\-id128 new\fR, 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 calls
75 \fBsd_id128_get_app_specific()\fR
76 with the result from
77 \fBsd_id128_get_machine()\fR
78 and the
79 \fIapp_id\fR
80 parameter\&.
81 .PP
82 \fBsd_id128_get_boot()\fR
83 returns the boot ID of the executing kernel\&. This reads and parses the
84 /proc/sys/kernel/random/boot_id
85 file exposed by the kernel\&. It is randomly generated early at boot and is unique for every running kernel instance\&. See
86 \fBrandom\fR(4)
87 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
88 \fBsd_id128_get_boot_app_specific()\fR, see below\&.
89 .PP
90 \fBsd_id128_get_boot_app_specific()\fR
91 is analogous to
92 \fBsd_id128_get_machine_app_specific()\fR, 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\&.
93 .PP
94 \fBsd_id128_get_invocation()\fR
95 returns the invocation ID of the currently executed service\&. In its current implementation, this tries to read and parse the following:
96 .sp
97 .RS 4
98 .ie n \{\
99 \h'-04'\(bu\h'+03'\c
100 .\}
101 .el \{\
102 .sp -1
103 .IP \(bu 2.3
104 .\}
105 The
106 \fI$INVOCATION_ID\fR
107 environment variable that the service manager sets when activating a service\&.
108 .RE
109 .sp
110 .RS 4
111 .ie n \{\
112 \h'-04'\(bu\h'+03'\c
113 .\}
114 .el \{\
115 .sp -1
116 .IP \(bu 2.3
117 .\}
118 An entry in the kernel keyring that the system service manager sets when activating a service\&.
119 .RE
120 .sp
121 See
122 \fBsystemd.exec\fR(5)
123 for details\&. The ID is cached internally\&. In future a different mechanism to determine the invocation ID may be added\&.
124 .PP
125 \fBsd_id128_get_invocation_app_specific()\fR
126 derives an application\-specific ID from the invocation ID\&.
127 .PP
128 Note that
129 \fBsd_id128_get_machine_app_specific()\fR,
130 \fBsd_id128_get_boot()\fR,
131 \fBsd_id128_get_boot_app_specific()\fR,
132 \fBsd_id128_get_invocation()\fR
133 and
134 \fBsd_id128_get_invocation_app_specific\fR
135 always return UUID Variant 1 Version 4 compatible IDs\&.
136 \fBsd_id128_get_machine()\fR
137 will also return a UUID Variant 1 Version 4 compatible ID on new installations but might not on older\&. It is possible to convert the machine ID non\-reversibly into a UUID Variant 1 Version 4 compatible one\&. For more information, see
138 \fBmachine-id\fR(5)\&. It is hence guaranteed that these functions will never return the ID consisting of all zero or all one bits (\fBSD_ID128_NULL\fR,
139 \fBSD_ID128_ALLF\fR) \(em with the possible exception of
140 \fBsd_id128_get_machine()\fR, as mentioned\&.
141 .PP
142 For more information about the
143 "sd_id128_t"
144 type see
145 \fBsd-id128\fR(3)\&.
146 .SH "RETURN VALUE"
147 .PP
148 Those calls return 0 on success (in which case
149 \fIret\fR
150 is filled in), or a negative errno\-style error code\&.
151 .SS "Errors"
152 .PP
153 Returned errors may indicate the following problems:
154 .PP
155 \fB\-ENOENT\fR
156 .RS 4
157 Returned by
158 \fBsd_id128_get_machine()\fR
159 and
160 \fBsd_id128_get_machine_app_specific()\fR
161 when
162 /etc/machine\-id
163 is missing\&.
164 .sp
165 Added in version 242\&.
166 .RE
167 .PP
168 \fB\-ENOMEDIUM\fR
169 .RS 4
170 Returned by
171 \fBsd_id128_get_machine()\fR
172 and
173 \fBsd_id128_get_machine_app_specific()\fR
174 when
175 /etc/machine\-id
176 is empty or all zeros\&. Also returned by
177 \fBsd_id128_get_invocation()\fR
178 when the invocation ID is all zeros\&.
179 .sp
180 Added in version 242\&.
181 .RE
182 .PP
183 \fB\-ENOPKG\fR
184 .RS 4
185 Returned by
186 \fBsd_id128_get_machine()\fR
187 and
188 \fBsd_id128_get_machine_app_specific()\fR
189 when the content of
190 /etc/machine\-id
191 is
192 "uninitialized"\&.
193 .sp
194 Added in version 253\&.
195 .RE
196 .PP
197 \fB\-ENOSYS\fR
198 .RS 4
199 Returned by
200 \fBsd_id128_get_boot()\fR
201 and
202 \fBsd_id128_get_boot_app_specific()\fR
203 when
204 /proc/
205 is not mounted\&.
206 .sp
207 Added in version 253\&.
208 .RE
209 .PP
210 \fB\-ENXIO\fR
211 .RS 4
212 Returned by
213 \fBsd_id128_get_invocation()\fR
214 if no invocation ID is set\&. Also returned by
215 \fBsd_id128_get_app_specific()\fR,
216 \fBsd_id128_get_machine_app_specific()\fR, and
217 \fBsd_id128_get_boot_app_specific()\fR
218 when the
219 \fIapp_id\fR
220 parameter is all zeros\&.
221 .sp
222 Added in version 242\&.
223 .RE
224 .PP
225 \fB\-EUCLEAN\fR
226 .RS 4
227 Returned by any of the functions described here when the configured value has invalid format\&.
228 .sp
229 Added in version 253\&.
230 .RE
231 .PP
232 \fB\-EPERM\fR
233 .RS 4
234 Requested information could not be retrieved because of insufficient permissions\&.
235 .sp
236 Added in version 242\&.
237 .RE
238 .SH "NOTES"
239 .PP
240 Functions described here are available as a shared library, which can be compiled against and linked to with the
241 \fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
242 file\&.
243 .PP
244 The code described here uses
245 \fBgetenv\fR(3), which is declared to be not multi\-thread\-safe\&. This means that the code calling the functions described here must not call
246 \fBsetenv\fR(3)
247 from a parallel thread\&. It is recommended to only do calls to
248 \fBsetenv()\fR
249 from an early phase of the program when no other threads have been started\&.
250 .SH "EXAMPLES"
251 .PP
252 \fBExample\ \&1.\ \&Application\-specific machine ID\fR
253 .PP
254 First, generate the application ID:
255 .sp
256 .if n \{\
257 .RS 4
258 .\}
259 .nf
260 $ systemd\-id128 \-p new
261 As string:
262 c273277323db454ea63bb96e79b53e97
263
264 As UUID:
265 c2732773\-23db\-454e\-a63b\-b96e79b53e97
266
267 As man:sd\-id128(3) macro:
268 #define MESSAGE_XYZ SD_ID128_MAKE(c2,73,27,73,23,db,45,4e,a6,3b,b9,6e,79,b5,3e,97)
269 \&.\&.\&.
270 .fi
271 .if n \{\
272 .RE
273 .\}
274 .PP
275 Then use the new identifier in an example application:
276 .sp
277 .if n \{\
278 .RS 4
279 .\}
280 .nf
281 /* SPDX\-License\-Identifier: MIT\-0 */
282
283 #include <stdio\&.h>
284 #include <systemd/sd\-id128\&.h>
285
286 #define OUR_APPLICATION_ID SD_ID128_MAKE(c2,73,27,73,23,db,45,4e,a6,3b,b9,6e,79,b5,3e,97)
287
288 int main(int argc, char *argv[]) {
289 sd_id128_t id;
290 sd_id128_get_machine_app_specific(OUR_APPLICATION_ID, &id);
291 printf("Our application ID: " SD_ID128_FORMAT_STR "\en", SD_ID128_FORMAT_VAL(id));
292 return 0;
293 }
294 .fi
295 .if n \{\
296 .RE
297 .\}
298 .SH "HISTORY"
299 .PP
300 \fBsd_id128_get_machine()\fR
301 and
302 \fBsd_id128_get_boot()\fR
303 were added in version 187\&.
304 .PP
305 \fBsd_id128_get_invocation()\fR
306 was added in version 232\&.
307 .PP
308 \fBsd_id128_get_machine_app_specific()\fR
309 was added in version 233\&.
310 .PP
311 \fBsd_id128_get_boot_app_specific()\fR
312 was added in version 240\&.
313 .PP
314 \fBsd_id128_get_app_specific()\fR
315 was added in version 255\&.
316 .PP
317 \fBsd_id128_get_invocation_app_specific()\fR
318 was added in version 256\&.
319 .SH "SEE ALSO"
320 .PP
321 \fBsystemd\fR(1), \fBsystemd-id128\fR(1), \fBsd-id128\fR(3), \fBmachine-id\fR(5), \fBsystemd.exec\fR(5), \fBsd_id128_randomize\fR(3), \fBrandom\fR(4)
322 .SH "NOTES"
323 .IP " 1." 4
324 RFC 4122
325 .RS 4
326 \%https://tools.ietf.org/html/rfc4122
327 .RE