'\" t .TH "SD_ID128_GET_MACHINE" "3" "" "elogind 239.3" "sd_id128_get_machine" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .\" http://bugs.debian.org/507673 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" ----------------------------------------------------------------- .\" * set default formatting .\" ----------------------------------------------------------------- .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) .ad l .\" ----------------------------------------------------------------- .\" * MAIN CONTENT STARTS HERE * .\" ----------------------------------------------------------------- .SH "NAME" sd_id128_get_machine, sd_id128_get_machine_app_specific, sd_id128_get_boot, sd_id128_get_invocation \- Retrieve 128\-bit IDs .SH "SYNOPSIS" .sp .ft B .nf #include .fi .ft .HP \w'int\ sd_id128_get_machine('u .BI "int sd_id128_get_machine(sd_id128_t\ *" "ret" ");" .HP \w'int\ sd_id128_get_machine_app_specific('u .BI "int sd_id128_get_machine_app_specific(sd_id128_t\ " "app_id" ", sd_id128_t\ *" "ret" ");" .HP \w'int\ sd_id128_get_boot('u .BI "int sd_id128_get_boot(sd_id128_t\ *" "ret" ");" .HP \w'int\ sd_id128_get_invocation('u .BI "int sd_id128_get_invocation(sd_id128_t\ *" "ret" ");" .SH "DESCRIPTION" .PP \fBsd_id128_get_machine()\fR returns the machine ID of the executing host\&. This reads and parses the \fBmachine-id\fR(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 \fBsd_id128_get_machine_app_specific()\fR is provided, see below\&. .PP \fBsd_id128_get_machine_app_specific()\fR is similar to \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 \fBsd_id128_get_machine()\fR 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 \fBjournalctl \-\-new\-id128\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 calculates HMAC\-SHA256 of the application ID, keyed by the machine ID\&. .PP \fBsd_id128_get_boot()\fR 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 \fBrandom\fR(4) for more information\&. This function also internally caches the returned ID to make this call a cheap operation\&. .PP \fBsd_id128_get_invocation()\fR returns the invocation ID of the currently executed service\&. In its current implementation, this reads and parses the \fI$INVOCATION_ID\fR environment variable that the service manager has to set when activating a service\&. If \fI$INVOCATION_ID\fR was not set by the service manager, the function returns \-ENXIO\&. The ID is cached internally\&. In future a different mechanism to determine the invocation ID may be added\&. .PP Note that \fBsd_id128_get_machine_app_specific()\fR, \fBsd_id128_get_boot()\fR and \fBsd_id128_get_invocation()\fR always return UUID v4 compatible IDs\&. \fBsd_id128_get_machine()\fR 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 \fBmachine-id\fR(5)\&. .PP For more information about the "sd_id128_t" type see \fBsd-id128\fR(3)\&. .SH "RETURN VALUE" .PP Those calls return 0 on success (in which case \fIret\fR is filled in), or a negative errno\-style error code\&. In particular, \fBsd_id128_get_machine()\fR and \fBsd_id128_get_machine_app_specific()\fR return \fB\-ENOENT\fR if /etc/machine\-id is missing, and \fB\-ENOMEDIUM\fR if is empty or all zeros\&. .SH "NOTES" .PP These APIs are implemented as a shared library, which can be compiled and linked to with the \fBlibelogind\fR\ \&\fBpkg-config\fR(1) file\&. .SH "EXAMPLES" .PP \fBExample\ \&1.\ \&Application\-specific machine ID\fR .PP Here\*(Aqs a simple example for an application specific machine ID: .sp .if n \{\ .RS 4 .\} .nf #include #include #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 "\en", SD_ID128_FORMAT_VAL(id)); return 0; } .fi .if n \{\ .RE .\} .SH "SEE ALSO" .PP \fBelogind\fR(8), \fBsd-id128\fR(3), \fBmachine-id\fR(5), \fBsd_id128_randomize\fR(3), \fBrandom\fR(4)