Publishing API

This section contains the general publishing API calls. More...

Functions
DVAPI int32_t	dvPublish (dvCtx dc, const char *passwd, int durationDays, const char *data, char **vid)
DVAPI int32_t	dvGetPublished (dvCtx dc, const char *passwd, ruList vids, ruMap *vidMap)

Detailed Description

This section contains the general publishing API calls.

The publishing API are additional functions for specific purpose. In distributed systems it may be necessary to provide the PID payload to external parties. An example could be the health or police sector, where datasets including sensitive PID may need to be exchanged. But even in such cases, the pseudonymisation should not become broken. Thus, it is the better to exchange pseudonymized datasets with VID entries and then grant access to the PID payload to the receiving party.

This is what the publishing functions allow you to do. Obviously, the receiving party should not know your app-id and therefore the publishing functions need a separate password for encryption. This is a new key you then share with the receiving party, together with the created VID entries.

Published payloads have different behavior:

1. They have an expiration date which has them automatically deleted in the DataVaccinator Vault when they expire.
2. They cannot get updated.
3. They do not support the Search API.
4. They can be accessed by another Service Provider if they know the VID.
5. They are encrypted with a different password than your usual app-id.
6. There is no caching for published items.

Below is a typical process for exchanging pseudonymized information, herein referred to as exchange data, using DataVaccinator :

1. Make sure the receiving party is has a login to your DataVaccinator Vault instance:
   1. They need their own SID and SPW.
   2. Their system has to be IP whitelisted.
   3. You may have to contact your DataVaccinator Vault provider to enable this (if you’re not hosting the DataVaccinator Vault by yourself).
2. Exchange a secure password for usage with DataVaccinator between you and the receiving party.
3. Push the PID datasets to exchange to the DataVaccinator Vault using the dvPublish function and attach the resulting VID entries to your exchange data.
4. Send your exchange data to the receiving party.
5. The receiving party uses its SID / SPW and the dvGetPublished function to retrieve the PID information as needed using your supplied VID entries.

This publishing example can also be found under examples/publish.c:

#include <vaccinator.h>
 
int main ( int argc, char **argv ) {
    int ret = RUE_OK;
    dvCtx dc = NULL;
    const char *name = "John Doe", *passwd = "mysecret";
    char *namevid = NULL;
    ruList vids = NULL;
    ruMap data = NULL;
 
    do {
        // setup
        ret = dvNew(&dc, PROVIDER_URL, APPID, NULL);
        if (ret != RUE_OK) break;
 
        // check for easy SSL mode
        if (ruStrCmp("1", ruGetenv("EASYSSL")) == 0) {
            // disable certificate checks
            ret = dvSetProp(dc, DV_SKIP_CERT_CHECK, "1");
            if (ret) break;
        }
 
        // publish data
        int durationDays = 1;
        ret = dvPublish(dc, passwd, durationDays, name, &namevid);
        if (ret != RUE_OK) break;
 
        // retrieve data
        vids = ruListNew(NULL);
        ret = ruListAppend(vids, namevid);
        if (ret != RUE_OK) break;
 
        ret = dvGetPublished(dc, passwd, vids, &data);
        if (ret != RUE_OK) 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) break;
            printf("pid for vid: '%s' is: '%s'\n", vd, out);
        }
        ruMapFree(data);
        data = NULL;
 
    } while (false);
 
    if (namevid) free(namevid);
    if (vids) ruListFree(vids);
    if (data) ruMapFree(data);
    if (dc) dvFree(dc);
    return ret;
}

Function Documentation

dvGetPublished()

DVAPI int32_t dvGetPublished	(	dvCtx	dc,
		const char *	passwd,
		ruList	vids,
		ruMap *	vidMap
	)

Retrieves a VID Map for the given list of published VID entries.

Parameters

dc	The dvCtx to work with.
passwd	The password that was used when dvPublish was called by the publishing party.
vids	An ruList of VID entries to retrieve the VID Map for.
vidMap	Where the returned VID Map will be stored. It is good practice to iterate over the given list of VID entries and to use dvGetVid to retrieve its entries.

Returns

RUE_OK on success or an error code.

dvPublish()

DVAPI int32_t dvPublish	(	dvCtx	dc,
		const char *	passwd,
		int	durationDays,
		const char *	data,
		char **	vid
	)

Creates a new PID entry for publishing.

Parameters

dc	The dvCtx to work with.
passwd	A password which will be used in place of the regular app-id. This password must be shared with the receiving party in order to allow them access to this PID data.
durationDays	The numbers of days from now until the published data will be deleted from the DataVaccinator Vault. Allowed values are between 1 and 365.
data	The PID data to vaccinate.
vid	Where the corresponding VID for the given data will be stored on success. Free this with ruFree when done with it.

Returns

RUE_OK on success or an error code.