dmi_anonymize

Synopsis

#include <opendmi/anonymize.h>

bool dmi_anonymize(dmi_context_t *context, dmi_buffer_t *table);
bool dmi_anonymize_context(dmi_context_t *context);

Description

The dmi_anonymize function writes into table a copy of the structure table of an open context, in which the values identifying the system rather than describing it are replaced, so that the data can be shared, e.g. in a bug report or in a collection of test data. dmi_save writes such a copy into a dump file with DMI_SAVE_FLAG_ANONYMIZE, and so does the --anonymize option of opendmi-dump.

The values replaced are the ones of the attributes marked with DMI_ATTRIBUTE_FLAG_PRIVATE in the specifications of the structures: serial numbers, asset tags, UUIDs, MAC addresses and the like, of the standard structures and of the vendor-specific ones the enabled modules decode.

The copy has the very layout of the table, so that it decodes the way the table does, and everything but the replaced values stays as it is:

Every value is replaced with one of the same length. Strings keep their letters, digits and punctuation in place, e.g. a serial number of an upper case letter followed by digits is replaced with another one of that kind.
MAC addresses keep their first three bytes, which tell the manufacturer of the device rather than the device.
UUIDs keep their version and variant.
Values which identify nothing are kept: empty and blank strings, the placeholders firmware vendors leave in place, e.g. To Be Filled By O.E.M., values of one repeated byte, e.g. all zeros, and the values standing for "unspecified".

A value is replaced the same way wherever the table holds it, e.g. a service tag serving as the serial number of both the system and the chassis. A value which looks like an identifier, a single word holding digits, is also looked for in the rest of the table and replaced there, e.g. in the OEM strings, in the options of the system configuration, or in the bytes of a vendor-specific structure holding it in place. A value which does not, e.g. Battery 0 put in place of the serial number of a battery, is replaced only where the attribute holds it, so that the names it happens to be part of are kept.

The replacements are made from the values by a keyed hash, SipHash-2-4, whose key is taken from the random number generator of the system each time a table is anonymized and is never saved. The same value is thus replaced differently in every copy, and the original values cannot be recovered by trying the ones a serial number may take.

The context itself is left as it is: its structures keep the values they have been decoded with.

The dmi_anonymize_context function makes the copy the same way, puts it in place of the table of the context, and reads the structures anew from it, so that everything decoded from the context afterwards, e.g. an export, holds the replaced values, as the --anonymize option of opendmi-export does. The copy has the very layout of the table, so the platform and the extension modules told from the table stay the same. The structures read before are destroyed, so the pointers to them and to the information decoded from them are no longer valid. If the copy cannot be made or read, the context is left as it is.

Parameters

context: Open context, whose structures are decoded.
table: Buffer to write the copy into. The data it holds is replaced, and dropped if the copy fails to be made. A call refused for its arguments or for the state of the context leaves the buffer as it is.

Return value

dmi_anonymize returns true if the copy has been made, and dmi_anonymize_context if the context has been anonymized; both return false otherwise.

Errors

DMI_ERROR_ARGUMENT_NULL: Table is nullptr (dmi_anonymize only).
DMI_ERROR_STATE_INVALID: Context is not open, or it has been opened with DMI_CONTEXT_FLAG_OVERLAY, whose structures are decoded from copies carrying additional information entries rather than from the table.
DMI_ERROR_OUT_OF_MEMORY: Memory cannot be allocated.
DMI_ERROR_SYSTEM: Random key cannot be generated.
DMI_ERROR_INTERNAL: Structure is not encoded back into its own length.

Notes

Values of the structures no enabled module decodes are replaced only where they repeat a value found elsewhere, so a table carrying unknown OEM structures may still identify its system. The same holds for free-form strings, e.g. OEM strings (type 11), which are not replaced unless they hold such a value. The tables to be shared are worth a look before they are.