nid - Network Identificator generating tool
============================================

Turns a natural identifier into a stable, anonymized surrogate key. You
feed it an identifying string - a name plus birth date and place, an SSN /
SIN, a driver's licence number, or any other natural or surrogate key - and
it prints back a short hashed ID.

The point is record linkage without sharing the private key. An institution
collecting statistics can recognise the same person across records while
never holding the underlying personal data. Because the mapping is
deterministic, if another institution later hashes the same input with the
same algorithm it produces the same ID, so the two can link their records.
That only works if every party runs the same algorithm, so the tool (not the
keys) is what gets distributed.

The ID is the MD5 digest of the input, base64-encoded, trimmed to a 22-char
token. Written in small, dependency-free C; MD5 and base64 are bundled.


Usage
-----

    nid "string"                 hash that argument
    echo "string" | nid          or read one line from stdin (filter mode)

    nid "Firstname Secondname 01011968 myCatName articles"

Options:
    -h    help
    -d    debug tracing to stderr

The whole argument (or stdin line) is the key, so keep the fields and their
order identical everywhere the same person must resolve to the same ID.


Build
-----

    make            # build ./nid
    make ut         # build and run the in-place unit tests
    make ut-asan    # run the tests under AddressSanitizer + UBSan
    make pedantic   # strict warnings (-pedantic -Wstrict-prototypes ...)
    make release    # -O2
    make clean

A stock C99 toolchain is the only requirement.


Note on the hash
----------------

MD5 is used here as a fast, portable, demonstrative digest, not as a
cryptographic guarantee. Any other encoder - a stronger hash from a Linux
project or a commercial one - can be dropped in, as long as every party
that must link records uses the identical algorithm. For real
anonymization, prefer a keyed/salted modern hash and treat the algorithm
and any salt as a shared secret.


Coding style
------------

This code follows the same discipline as ais: C99, warning-free under
-std=c99 -Wall -Wextra (and the stricter `make pedantic`); bounded strings
only (snprintf, never strcpy/sprintf/vsprintf); functions, not fragile
macros; modules return, only the CLI exits (via die()); one concept per
file; and AddressSanitizer/UBSan-clean (`make ut-asan`). The rules and their
rationale live in ais rather than being repeated here:

    https://github.com/Anode1/ais/blob/main/doc/dev/STYLE.md

md5.c/.h is third-party (RSA Data Security MD5); its UINT4 was pinned to a
32-bit type so the digest is correct on 64-bit platforms.


License
-------

Apache License 2.0 (see the source headers). Author: Vasili Gavrilov
(GitHub: https://github.com/Anode1).


===================================================================
Reference / Citation:

This tool is part of the toolkit accompanying:

  Gavrilov, V. (2026). The Atree Format: A Scalable Binary-Path
  Notation for Ancestral Genealogies, with an Application to
  Lineage Matching. Zenodo.
  https://doi.org/10.5281/zenodo.20587715

The DOI above is the canonical (concept) DOI; it always resolves to
the latest version of the paper.