shaba/systemd
1
0
Fork 0
mirror of https://github.com/systemd/systemd.git synced 2024-12-23 21:35:11 +03:00
Code

man: document sd_id128_get_app_specific

Browse Source
This commit is contained in:
Zbigniew Jędrzejewski-Szmek 2023-08-26 13:07:32 +02:00
parent 62b4bee9bc
commit b5c27ebca4
2 changed files with 31 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
man/rules/meson.build
View File

@ -672,7 +672,8 @@ manpages = [
''], ''],
['sd_id128_get_machine', ['sd_id128_get_machine',
'3', '3',
['sd_id128_get_boot', ['sd_id128_get_app_specific',
'sd_id128_get_boot',
'sd_id128_get_boot_app_specific', 'sd_id128_get_boot_app_specific',
'sd_id128_get_invocation', 'sd_id128_get_invocation',
'sd_id128_get_machine_app_specific'], 'sd_id128_get_machine_app_specific'],

41
man/sd_id128_get_machine.xml
View File

@ -17,6 +17,7 @@
<refnamediv> <refnamediv>
<refname>sd_id128_get_machine</refname> <refname>sd_id128_get_machine</refname>
<refname>sd_id128_get_app_specific</refname>
<refname>sd_id128_get_machine_app_specific</refname> <refname>sd_id128_get_machine_app_specific</refname>
<refname>sd_id128_get_boot</refname> <refname>sd_id128_get_boot</refname>
<refname>sd_id128_get_boot_app_specific</refname> <refname>sd_id128_get_boot_app_specific</refname>
@ -33,6 +34,13 @@
<paramdef>sd_id128_t *<parameter>ret</parameter></paramdef> <paramdef>sd_id128_t *<parameter>ret</parameter></paramdef>
</funcprototype> </funcprototype>
<funcprototype>
<funcdef>int <function>sd_id128_get_app_specific</function></funcdef>
<paramdef>sd_id128_t <parameter>base</parameter></paramdef>
<paramdef>sd_id128_t <parameter>app_id</parameter></paramdef>
<paramdef>sd_id128_t *<parameter>ret</parameter></paramdef>
</funcprototype>
<funcprototype> <funcprototype>
<funcdef>int <function>sd_id128_get_machine_app_specific</function></funcdef> <funcdef>int <function>sd_id128_get_machine_app_specific</function></funcdef>
<paramdef>sd_id128_t <parameter>app_id</parameter></paramdef> <paramdef>sd_id128_t <parameter>app_id</parameter></paramdef>
@ -69,16 +77,25 @@
ID from this machine ID, in an irreversible (cryptographically secure) way. To make this easy ID from this machine ID, in an irreversible (cryptographically secure) way. To make this easy
<function>sd_id128_get_machine_app_specific()</function> is provided, see below.</para> <function>sd_id128_get_machine_app_specific()</function> is provided, see below.</para>
<para><function>sd_id128_get_app_specific()</function> returns a machine ID that is a combination of the
<parameter>base</parameter> and <parameter>app_id</parameter> parameters. Internally, this function
calculates HMAC-SHA256 of the <parameter>app_id</parameter> parameter keyed by the
<parameter>base</parameter> parameter, and truncates this result to fit in
<structname>sd_id128_t</structname> and turns it into a valid Variant 1 Version 4 UUID, in accordance
with <ulink url="https://tools.ietf.org/html/rfc4122">RFC 4122</ulink>. Neither of the two input
parameters can be calculated from the output parameter <parameter>ret</parameter>.</para>
<para><function>sd_id128_get_machine_app_specific()</function> is similar to <para><function>sd_id128_get_machine_app_specific()</function> is similar to
<function>sd_id128_get_machine()</function>, but retrieves a machine ID that is specific to the application that is <function>sd_id128_get_machine()</function>, but retrieves a machine ID that is specific to the
identified by the indicated application ID. It is recommended to use this function instead of application that is identified by the indicated application ID. It is recommended to use this function
<function>sd_id128_get_machine()</function> when passing an ID to untrusted environments, in order to make sure instead of <function>sd_id128_get_machine()</function> when passing an ID to untrusted environments, in
that the original machine ID may not be determined externally. This way, the ID used by the application remains order to make sure that the original machine ID may not be determined externally. This way, the ID used
stable on a given machine, but cannot be easily correlated with IDs used in other applications on the same by the application remains stable on a given machine, but cannot be easily correlated with IDs used in
machine. The application-specific ID should be generated via a tool like <command>systemd-id128 new</command>, other applications on the same machine. The application-specific ID should be generated via a tool like
and may be compiled into the application. This function will return the same application-specific ID for each <command>systemd-id128 new</command>, and may be compiled into the application. This function will return
combination of machine ID and application ID. Internally, this function calculates HMAC-SHA256 of the application the same application-specific ID for each combination of machine ID and application ID. Internally, this
ID, keyed by the machine ID.</para> function calls <function>sd_id128_get_app_specific()</function> with the result from
<function>sd_id128_get_machine()</function> and the <parameter>app_id</parameter> parameter.</para>
<para><function>sd_id128_get_boot()</function> returns the boot ID of the executing kernel. This reads and parses <para><function>sd_id128_get_boot()</function> returns the boot ID of the executing kernel. This reads and parses
the <filename>/proc/sys/kernel/random/boot_id</filename> file exposed by the kernel. It is randomly generated early the <filename>/proc/sys/kernel/random/boot_id</filename> file exposed by the kernel. It is randomly generated early
@ -89,9 +106,9 @@
derive an application specific ID using <function>sd_id128_get_boot_app_specific()</function>, see below.</para> derive an application specific ID using <function>sd_id128_get_boot_app_specific()</function>, see below.</para>
<para><function>sd_id128_get_boot_app_specific()</function> is analogous to <para><function>sd_id128_get_boot_app_specific()</function> is analogous to
<function>sd_id128_get_machine_app_specific()</function> but returns an ID that changes between boots. Some <function>sd_id128_get_machine_app_specific()</function>, but returns an ID that changes between
machines may be used for a long time without rebooting, hence the boot ID may remain constant for a long time, and boots. Some machines may be used for a long time without rebooting, hence the boot ID may remain constant
has properties similar to the machine ID during that time.</para> for a long time, and has properties similar to the machine ID during that time.</para>
<para><function>sd_id128_get_invocation()</function> returns the invocation ID of the currently executed <para><function>sd_id128_get_invocation()</function> returns the invocation ID of the currently executed
service. In its current implementation, this tries to read and parse the following: service. In its current implementation, this tries to read and parse the following: