sd_id128_get_machine

systemd
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 <systemd/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-id 5 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 random 4 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.exec 5 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-id 5.

For more information about the `sd_id128_t` type see sd-id128 3.

## 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-config 1 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

systemd 1, sd-id128 3, machine-id 5, systemd.exec 5, sd_id128_randomize 3, random 4