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=d3c92fb53bb92ec00914aa4b51bd21d88e887128;hp=6bee7ad9c127f28ec644bc39670bdc796268fcce;hpb=e9dd9f9547350c7dc0473583b5c2228dc8f0ab76;p=elogind.git diff --git a/man/sd_id128_get_machine.xml b/man/sd_id128_get_machine.xml index 6bee7ad9c..e7326422b 100644 --- a/man/sd_id128_get_machine.xml +++ b/man/sd_id128_get_machine.xml @@ -1,137 +1,180 @@ + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> - - sd_id128_get_machine - systemd - - - - Developer - Lennart - Poettering - lennart@poettering.net - - - - - - sd_id128_get_machine - 3 - - - - sd_id128_get_machine - sd_id128_get_boot - Retrieve 128-bit IDs - - - - - #include <systemd/sd-id128.h> - - - int sd_id128_get_machine - sd_id128_t* ret - - - - int sd_id128_get_boot - 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_boot() returns - the boot ID of the executing kernel. This reads and - parses the - /proc/sys/kernel/random/boot_id - file exposed by the kernel. It is randomly generated - early at boot and is unique for every running kernel - instance. See - random4 - 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 - machine-id5. - - For more information about the - sd_id128_t type see - sd-id1283. - - - - Return Value - - The two calls return 0 on success (in which - case ret is filled in), or a - negative errno-style error code. - - - - Notes - - The sd_id128_get_machine() - and sd_id128_get_boot() - interfaces are available as shared library, which can - be compiled and linked to with the - libsystemd-id128 pkg-config1 - file. - - - - See Also - - - systemd1, - sd-id1283, - machine-id5, - random4, - sd_id128_randomize3 - - + + sd_id128_get_machine + elogind + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_id128_get_machine + 3 + + + + sd_id128_get_machine + sd_id128_get_machine_app_specific + sd_id128_get_boot + sd_id128_get_invocation + Retrieve 128-bit IDs + + + + + #include <elogind/sd-id128.h> + + + int sd_id128_get_machine + 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. 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 + /proc/sys/kernel/random/boot_id file exposed + by the kernel. It is randomly generated early at boot and is + unique for every running kernel instance. See + random4 + for more information. This function also internally caches the + returned ID to make this call a cheap operation. + + 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 + type see + sd-id1283. + + + + Return Value + + The two calls return 0 on success (in which case + ret is filled in), or a negative + errno-style error code. + + + + Notes + + 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 + + + systemd1, + sd-id1283, + machine-id5, + systemd.exec5, + sd_id128_randomize3, + random4 + +