X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=man%2Fsd_id128_get_machine.xml;h=e7326422b5c9e6c4718dcbff428300d4f7e485c2;hb=8df592e92ab19c628d558f621f2dfbe9a3589c91;hp=a3fcfb55247aa484c9c23383caefa288148678d6;hpb=1532f28b7cf3e6e02e74691450b2b5379be6b805;p=elogind.git
diff --git a/man/sd_id128_get_machine.xml b/man/sd_id128_get_machine.xml
index a3fcfb552..e7326422b 100644
--- a/man/sd_id128_get_machine.xml
+++ b/man/sd_id128_get_machine.xml
@@ -44,7 +44,9 @@
sd_id128_get_machine
+ sd_id128_get_machine_app_specific
sd_id128_get_boot
+ sd_id128_get_invocation
Retrieve 128-bit IDs
@@ -57,22 +59,44 @@
sd_id128_t *ret
+
+ int sd_id128_get_machine_app_specific
+ sd_id128_t app_id
+ sd_id128_t *ret
+
+
int sd_id128_get_boot
sd_id128_t *ret
+
+ int sd_id128_get_invocation
+ sd_id128_t *ret
+
+
Description
- sd_id128_get_machine() returns the
- machine ID of the executing host. This reads and parses the
- machine-id5
- file. This function caches the machine ID internally to make
- retrieving the machine ID a cheap operation.
+ sd_id128_get_machine() returns the machine ID of the executing host. This reads and
+ parses the machine-id5
+ 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
+ sd_id128_get_machine_app_specific() is provided, see below.
+
+ sd_id128_get_machine_app_specific() is similar to
+ sd_id128_get_machine(), 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
+ sd_id128_get_machine() 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 journalctl --new-id128, 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.
sd_id128_get_boot() returns the boot ID
of the executing kernel. This reads and parses the
@@ -83,12 +107,16 @@
for more information. This function also internally caches the
returned ID to make this call a cheap operation.
- Note that sd_id128_get_boot() always
- returns a UUID v4 compatible ID.
- sd_id128_get_machine() will also return a
- UUID v4-compatible ID on new installations but might not on older.
- It is possible to convert the machine ID into a UUID v4-compatible
- one. For more information, see
+ sd_id128_get_invocation() returns the invocation ID of the currently executed
+ service. In its current implementation, this reads and parses the $INVOCATION_ID environment
+ variable that the service manager sets when activating a service, see
+ systemd.exec5 for details. The
+ ID is cached internally. In future a different mechanism to determine the invocation ID may be added.
+
+ Note that sd_id128_get_machine_app_specific(), sd_id128_get_boot()
+ and sd_id128_get_invocation() always return UUID v4 compatible IDs.
+ sd_id128_get_machine() will also return a UUID v4-compatible ID on new installations but might
+ not on older. It is possible to convert the machine ID into a UUID v4-compatible one. For more information, see
machine-id5.
For more information about the sd_id128_t
@@ -107,22 +135,45 @@
Notes
- The sd_id128_get_machine() and
- sd_id128_get_boot() interfaces are available
- as a shared library, which can be compiled and linked to with the
- libelogind pkg-config1
- file.
+ The sd_id128_get_machine(), sd_id128_get_machine_app_specific()
+ sd_id128_get_boot() and sd_id128_get_invocation() interfaces are
+ available as a shared library, which can be compiled and linked to with the
+ libsystemd pkg-config1 file.
+
+
+
+ Examples
+
+
+ Application-specific machine ID
+
+ Here's a simple example for an application specific machine ID:
+
+ #include <systemd/sd-id128.h>
+#include <stdio.h>
+
+#define OUR_APPLICATION_ID SD_ID128_MAKE(c2,73,27,73,23,db,45,4e,a6,3b,b9,6e,79,b5,3e,97)
+
+int main(int argc, char *argv[]) {
+ sd_id128_t id;
+ sd_id128_get_machine_app_specific(OUR_APPLICATION_ID, &id);
+ printf("Our application ID: " SD_ID128_FORMAT_STR "\n", SD_ID128_FORMAT_VAL(id));
+ return 0;
+}
+
See Also
- elogind1,
+ systemd1,
sd-id1283,
machine-id5,
- random4,
- sd_id128_randomize3
+ systemd.exec5,
+ sd_id128_randomize3,
+ random4