DataVaccinator Client Documentation

Copyright

2022 Datavaccinator

Introduction

This is a DataVaccinator Client library which is designed for native use on PC based computer systems running Linux/Unix or Microsoft Windows operating systems.

DataVaccinator protects your sensitive data known as PID against abuse. The service allows you to split out your PID data at the very moment it is generated and uses advanced pseudonymisation techniques to replace it with a corresponding VID.

Thus, DataVaccinator reduces cyber security risks in the health, industry, finance and any other sector and helps service providers, device manufacturers, data generating and data handling parties to manage sensitive data in a secure and GDPR-compliant manner. In contrast to other offerings, DataVaccinator industrialises pseudonymisation, thereby making pseudonymisation replicable and affordable.

The API of this library has two main parts to it:

• The General API contains global and lifecycle functions.
• The general Data API contains most of the runtime functions.
• The specialized Publishing API relates to the part of sharing PID data with other parties.
• The Error Codes are for DataVaccinator Client and the others are regify-util Error Codes.

Data Specification

The general DataVaccinator Vault data specification can be found here https://github.com/DataVaccinator/dv-vault/blob/master/docs/DataVaccinator-protocol.adoc#data This section focuses on the implementation of the payload part. It is documented here to facilitate cross platform compatibility with other DataVaccinator Client implementations. Our payload is authenticated https://en.wikipedia.org/wiki/Authenticated_encryption#MAC-then-Encrypt_(MtE) style.

The following use of bytes in variables implies usage of actual bytes and not hex encoded representations thereof. Our payload is implemented in the following way:

cs = last 2 bytes of the app-id
ivbytes = randomBytes ( 16 )
ivhex = hexencode ( ivbytes )

sumbytes = sha256 ( PID )
bytes = PID + PKCS#7 Padding + sumbytes
cipherbytes = aes256cbc ( ivbytes , bytes )
payload = base64 (cipherbytes )

data = "aes-256-cbc:" + cs + ":" + ivhex + ":b:" + payload

Example Usage

This usage example can also be found under examples/datause.c:

#include <vaccinator.h>
#include <string.h>
 
int32_t headerCb(void* usrCtx, dvSetHeaderFn setHeader, void* headerCtx) {
    // This a static example that ignores the userCtx
    return setHeader(headerCtx, "Cache-Control", "max-age=60");
}
 
int32_t postCb(void* usrCtx, dvSetPostFn setPostField, void* postCtx) {
    // abort the request when usrCtx is not set as we need it here
    if (!usrCtx) return RUE_PARAMETER_NOT_SET;
 
    const char* user = "testuser";
    int32_t ret = setPostField(postCtx, "username", (void*)user, strlen(user));
    // abort the request on failure
    if (ret) return ret;
    // usrCtx could be any kind of structure, we just showcase a string here.
    char* passwd = (char*) usrCtx;
    return setPostField(postCtx, "password", (void*)passwd, strlen(passwd));
}
 
int main ( int argc, char **argv ) {
    int ret;
    KvStore *kvs = NULL;
    dvCtx dc = NULL;
    const char *name = "John Doe", *address = "Mystreet 42";
    const char *passwd = "mysecret", *logfile = CACHE_DIR "/debug.log";
    char *namevid = NULL, *addrvid = NULL, *a1 = NULL;
    ruList vids = NULL, indexTerms = NULL, searchTerms = NULL, foundVids = NULL;
    ruMap data = NULL;
    ruSinkCtx rsc = NULL;
 
    do {
        // local cache
        if (!ruIsDir(CACHE_DIR)) {
            ret = ruMkdir(CACHE_DIR, 0755, false);
            if (!ruIsDir(CACHE_DIR)) {
                printf("failed to create folder '%s' ec [%d]\n", CACHE_DIR, ret);
                break;
            }
        }
        kvs = ruNewFileStore(CACHE_DIR, &ret);
        if (ret) break;
 
        if (argc > 1) {
            a1 = argv[1];
            // -d turns on verbose debug logging
            // -v turns on verbose debug logging with curl debug logging
            if (ruStrEquals(a1, "-v") || ruStrEquals(a1, "-d")) {
                rsc = ruSinkCtxNew(logfile, NULL, NULL);
                ruSetLogger(ruFileLogSink, RU_LOG_VERB, rsc, true, true);
            } else {
                a1 = NULL;
            }
        }
 
        // setup
        ret = dvNew(&dc, PROVIDER_URL, APPID, kvs);
        if (ret) break;
        // check for easy SSL mode
        if (ruStrEquals("1", ruGetenv("EASYSSL"))) {
            // disable certificate checks
            ret = dvSetProp(dc, DV_SKIP_CERT_CHECK, "1");
            if (ret) break;
        }
        if (ruStrEquals(a1, "-v")) {
            // turn on curl debug logging
            ret = dvSetProp(dc, DV_CURL_LOGGING, "1");
            if (ret) break;
        }
        // sample usage of the header callback
        ret = dvSetHeaderCb(dc, &headerCb, NULL);
        if (ret) break;
        // Mask our password in the logs so it is replace by ^^^SECRET^^^
        // or whatever was set by DV_SECRET_PLACE_HOLDER last
        // APPID has already been masked by dvNew
        ret = ruCleanAdd(ruGetCleaner(), passwd, "^^^SECRET^^^");
        if (ret) break;
        // sample usage of the post fields callback
        ret = dvSetPostCb(dc, &postCb, (void *) passwd);
        if (ret) break;
 
        // add data
        ret = dvAdd(dc, name, NULL, &namevid);
        if (ret) break;
        printf("namevid: %s\n", namevid);
 
        // add searchable data
        ret = dvAddIndexWord(&indexTerms, APPID, address);
        if (ret) break;
        ret = dvAdd(dc, address, indexTerms, &addrvid);
        if (ret) break;
        printf("addrvid: %s\n", addrvid);
 
        // retrieve data
        vids = ruListNew(NULL);
        ret = ruListAppend(vids, namevid);
        if (ret) break;
        ret = ruListAppend(vids, addrvid);
        if (ret) break;
        ret = dvGet(dc, vids, &data);
        if (ret) break;
        ruIterator li = ruListIter(vids);
        for(char *out, *vd = ruIterNext(li, char*); li;
            vd = ruIterNext(li, char*)) {
            ret = dvGetVid(data, vd, &out);
            if (ret == RUE_OK) {
                printf("pid for vid: '%s' is: '%s'\n", vd, out);
            }
        }
        ruMapFree(data);
        data = NULL;
 
        // search data
        ret = dvAddSearchWord(&searchTerms, APPID, "Mystreet");
        if (ret) break;
        ret = dvSearch(dc, searchTerms, &foundVids);
        if (ret) break;
        li = ruListIter(foundVids);
        for(char* vd = ruIterNext(li, char*); li; vd = ruIterNext(li, char*)) {
            printf("found vid: '%s'\n", vd);
        }
 
        // wipe cache
        ret = dvWipe(dc, vids);
        if (ret) break;
 
        // delete data
        ret = dvDelete(dc, vids);
        if (ret) break;
 
        ret = dvDelete(dc, foundVids);
        if (ret) break;
 
    } while (false);
 
    if (namevid) free(namevid);
    if (addrvid) free(addrvid);
    if (vids) ruListFree(vids);
    if (indexTerms) ruListFree(indexTerms);
    if (searchTerms) ruListFree(searchTerms);
    if (foundVids) ruListFree(foundVids);
    if (data) ruMapFree(data);
    if (dc) dvFree(dc);
    if (kvs) ruFreeStore(kvs);
    if (a1) {
        printf("You will find debug logging in '%s'\n", logfile);
    }
    ruSinkCtxFree(rsc);
 
    return ret;
}