From 70fc4f57902290c48bec9acb2393ded84c09d4ca Mon Sep 17 00:00:00 2001
From: Lennart Poettering <lennart@poettering.net>
Date: Thu, 17 Nov 2016 17:07:46 +0100
Subject: sd-id128: add new sd_id128_get_machine_app_specific() API

This adds an API for retrieving an app-specific machine ID to sd-id128.
Internally it calculates HMAC-SHA256 with an 128bit app-specific ID as payload
and the machine ID as key.

(An alternative would have been to use siphash for this, which is also
cryptographically strong. However, as it only generates 64bit hashes it's not
an obvious choice for generating 128bit IDs.)

Fixes: #4667
---
 man/machine-id.xml | 15 ++++++++-------
 1 file changed, 8 insertions(+), 7 deletions(-)

(limited to 'man/machine-id.xml')

diff --git a/man/machine-id.xml b/man/machine-id.xml
index a722649de4..3c261bffcc 100644
--- a/man/machine-id.xml
+++ b/man/machine-id.xml
@@ -71,13 +71,14 @@
     <para>This machine ID adheres to the same format and logic as the
     D-Bus machine ID.</para>
 
-    <para>This ID uniquely identifies the host. It should be considered "confidential", and must not
-    be exposed in untrusted environments, in particular on the network. If a stable unique
-    identifier that is tied to the machine is needed for some application, the machine ID or any
-    part of it must not be used directly. Instead the machine ID should be hashed with a
-    cryptographic, keyed hash function, using a fixed, application-specific key. That way the ID
-    will be properly unique, and derived in a constant way from the machine ID but there will be no
-    way to retrieve the original machine ID from the application-specific one.</para>
+    <para>This ID uniquely identifies the host. It should be considered "confidential", and must not be exposed in
+    untrusted environments, in particular on the network. If a stable unique identifier that is tied to the machine is
+    needed for some application, the machine ID or any part of it must not be used directly. Instead the machine ID
+    should be hashed with a cryptographic, keyed hash function, using a fixed, application-specific key. That way the
+    ID will be properly unique, and derived in a constant way from the machine ID but there will be no way to retrieve
+    the original machine ID from the application-specific one. The
+    <citerefentry><refentrytitle>sd_id128_get_machine_app_specific</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+    API provides an implementation of such an algorithm.</para>
 
     <para>The
     <citerefentry><refentrytitle>systemd-machine-id-setup</refentrytitle><manvolnum>1</manvolnum></citerefentry>
-- 
cgit v1.2.3-54-g00ecf