Data API

This section contains the general DataVaccinator Client API calls. More...

Typedefs
typedef int32_t(*	dvIndexCb) (void *usrCtx, const char *vid, const char *data, ruList *indexWords)

Functions
DVAPI int32_t	dvAddIndexWord (ruList *indexWords, const char *appId, const char *word)
DVAPI int32_t	dvAddSearchWord (ruList *searchWords, const char *appId, const char *word)
DVAPI int32_t	dvAdd (dvCtx dc, const char *data, ruList indexWords, char **vid)
DVAPI int32_t	dvUpdate (dvCtx dc, const char *vid, const char *data, ruList indexWords)
DVAPI int32_t	dvGet (dvCtx dc, ruList vids, ruMap *vidMap)
DVAPI int32_t	dvGetVid (ruMap vidMap, const char *vid, char **pid)
DVAPI int32_t	dvSearch (dvCtx dc, ruList searchWords, ruList *vids)
DVAPI int32_t	dvDelete (dvCtx dc, ruList vids)
DVAPI int32_t	dvWipe (dvCtx dc, ruList vids)
DVAPI int32_t	dvChangeAppId (dvCtx dc, const char *newId, ruList vids, ruMap *vidMap, dvIndexCb indexCb, void *indexCtx)

Detailed Description

This section contains the general DataVaccinator Client API calls.

Typedef Documentation

dvIndexCb

typedef int32_t(* dvIndexCb) (void *usrCtx, const char *vid, const char *data, ruList *indexWords)

A function that generates a list of index word entries based on the given PID.

Parameters

usrCtx	Opaque context to be passed to the function.
vid	The VID that represents the given PID data. This is supplied in case it is useful.
data	The PID data to vaccinate and extract index word entries from.
indexWords	Where the ruList of index word entries should be stored. The returned ruList will be freed with ruListFree when no longer needed.

Returns

RUE_OK on success or an error code.

Function Documentation

dvAdd()

DVAPI int32_t dvAdd	(	dvCtx	dc,
		const char *	data,
		ruList	indexWords,
		char **	vid
	)

Creates a new PID entry in the DataVaccinator Vault.

Parameters

dc	The dvCtx to work with.
data	The PID data to vaccinate.
indexWords	Optional index word terms under which this data should be found via dvSearch. Use NULL for none.
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.

dvAddIndexWord()

DVAPI int32_t dvAddIndexWord	(	ruList *	indexWords,
		const char *	appId,
		const char *	word
	)

Adds the given word as an index word to the referenced ruList. This function is used when PID is sent to the DataVaccinator Vault with the functions dvAdd and dvUpdate. For making search word terms use dvAddSearchWord instead.

Parameters

indexWords	Pointer to an ruList that the index word will be added to. This list will be created if NULL, otherwise the given term will be added to the list present. The list must be freed with ruListFree when done with it.
appId	The app-id to use for term hashing.
word	index word under which data should be found via dvSearch.

Returns

RUE_OK on success or an error code.

dvAddSearchWord()

DVAPI int32_t dvAddSearchWord	(	ruList *	searchWords,
		const char *	appId,
		const char *	word
	)

Adds the given word as a search word to the referenced ruList. This function is used when searching for matching PID data with dvSearch .

Parameters

searchWords	Pointer to an ruList that the search word will be added to. This list will be created if NULL, otherwise the given term will be added to the list present. The list must be freed with ruListFree when done with it.
appId	The app-id to use for term hashing.
word	search word under which VID entries should be found via dvSearch.

Returns

RUE_OK on success or an error code.

dvChangeAppId()

DVAPI int32_t dvChangeAppId	(	dvCtx	dc,
		const char *	newId,
		ruList	vids,
		ruMap *	vidMap,
		dvIndexCb	indexCb,
		void *	indexCtx
	)

This function re-encrypts all given VID references with the app-id given in newId.

This may be needed if a user's app-id has been changed as a result of a compromise due to a leakage. Be sure to iterate over the returned VID Map.

Parameters

dc	The dvCtx with the old app-id to work with.
newId	The new app-id to re-encrypt each PID entry with.
vids	The list of VID entries that need re-encrypting.
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 check their stati.
indexCb	An optional dvIndexCb to call to set index word terms of each re-encrypted PID entry.
indexCtx	An optional context that will be passed into indexCb as the usrCtx parameter.

Returns

RUE_OK on success or an error code. Total success is only provided when the returned VID Map solely consists of entries with status RUE_OK.

This example to change the app-id can also be found in examples/changeappid.c:

#include <vaccinator.h>
#include <string.h>
 
// This index callback simply takes the first 8 characters of the data and
// adds it to the search index. This callback is required for dvChangeAppId if
// index terms are to be migrated. Its use elsewhere is optional.
int32_t indexCb (void *usrCtx, const char *vid, const char *data, ruList *indexWords) {
    // vid is passed in, so it is available should it be of use.
    // This example does not use it, though.
    #define startLen 8
    char termBuf[startLen + 1];
    const char* appId = (const char*) usrCtx;
    char* term = (char*) data;
    if (strlen(term) > startLen) {
        memcpy(termBuf, data, startLen);
        termBuf[startLen] = '\0';
        term = &termBuf[0];
    }
    // The actual index term is added to the list in this step.
    return dvAddIndexWord(indexWords, appId, term);
}
 
int main ( int argc, char **argv ) {
    int ret = RUE_OK;
    dvCtx dc = NULL;
    const char *name = "John Doe", *address = "Mystreet 42", *oldId = "old" APPID;
    char *namevid = NULL, *addrvid = NULL;
    ruList vids = NULL, indexTerms = NULL;
    ruMap vidMap = NULL;
 
    do {
 
        // setup
        ret = dvNew(&dc, PROVIDER_URL, oldId, 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;
        }
 
        vids = ruListNew(NULL);
 
        // since we have a search callback let's use it to make our search term
        ret = indexCb((void *) oldId, NULL, name, &indexTerms);
        if (ret != RUE_OK) break;
        // add data
        ret = dvAdd(dc, name, indexTerms, &namevid);
        if (ret != RUE_OK) break;
        ret = ruListAppend(vids, namevid);
        if (ret != RUE_OK) break;
        if (indexTerms) {
            ruListFree(indexTerms);
            indexTerms = NULL;
        }
 
        ret = indexCb((void *) oldId, NULL, address, &indexTerms);
        if (ret != RUE_OK) break;
        ret = dvAdd(dc, address, indexTerms, &addrvid);
        if (ret != RUE_OK) break;
        ret = ruListAppend(vids, addrvid);
        if (ret != RUE_OK) break;
        if (indexTerms) {
            ruListFree(indexTerms);
            indexTerms = NULL;
        }
 
        // change appids
        ret = dvChangeAppId(dc, APPID, vids, &vidMap,
                            indexCb, APPID);
        if (ret != RUE_OK) break;
        // verify results
        bool hasErrors = false;
        ruIterator li = ruListIter(vids);
        for(char *out, *vd = ruIterNext(li, char*); li;
            vd = ruIterNext(li, char*)) {
            ret = dvGetVid(vidMap, vd, &out);
            if (ret == DVE_INVALID_CREDENTIALS) {
                printf("vid: '%s' was not decrypted needing the appid with checksum '%s'\n",
                       vd, out);
                hasErrors = true;
            } else if (ret != RUE_OK) {
                printf("vid: '%s' was not migrated with status: %d\n",
                       vd, ret);
                hasErrors = true;
            }
        }
        if (hasErrors) break;
 
        printf("Successfully converted all entries\n");
        // change to the new appid.
        ret = dvSetProp(dc, DV_APP_ID, APPID);
        if (ret != RUE_OK) break;
 
    } while (false);
 
    if (namevid) free(namevid);
    if (addrvid) free(addrvid);
    if (vids) ruListFree(vids);
    if (indexTerms) ruListFree(indexTerms);
    if (vidMap) ruMapFree(vidMap);
    if (dc) dvFree(dc);
 
    return ret;
}

dvDelete()

DVAPI int32_t dvDelete	(	dvCtx	dc,
		ruList	vids
	)

Deletes given list of VID entries from the DataVaccinator Vault.

Parameters

dc	The dvCtx to work with.
vids	List of VID entries to be deleted.

Returns

RUE_OK on success or an error code.

dvGet()

DVAPI int32_t dvGet	(	dvCtx	dc,
		ruList	vids,
		ruMap *	vidMap
	)

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

Parameters

dc	The dvCtx to work with.
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.

dvGetVid()

DVAPI int32_t dvGetVid	(	ruMap	vidMap,
		const char *	vid,
		char **	pid
	)

Retrieves the associated PID data for given VID from the given VID Map and returns its associated status code.

Parameters

vidMap	The VID Map to retrieve the value from.
vid	VID entry to retrieve.
pid	Where to store the returned PID data. This data should be copied and must not be freed. It is freed along with the vidMap.

Returns

The status code of the associated VID Map entry or RUE_PARAMETER_NOT_SET etc for missing/invalid parameters.

dvSearch()

DVAPI int32_t dvSearch	(	dvCtx	dc,
		ruList	searchWords,
		ruList *	vids
	)

Retrieves an ruList of VID entries that matched the given search word entries.

Parameters

dc	The dvCtx to work with.
searchWords	An ruList of previously in dvAddSearchWord specified search word terms to query. These terms are ANDed.
vids	Where the ruList of found VID values will be stored. The returned ruList should be freed with ruListFree when no longer needed. The individual list entries may need to be copied as they are freed along with the list.

Returns

RUE_OK on success or an error code.

dvUpdate()

DVAPI int32_t dvUpdate	(	dvCtx	dc,
		const char *	vid,
		const char *	data,
		ruList	indexWords
	)

Updates an existing PID entry in the DataVaccinator Vault with new PID.

Parameters

dc	The dvCtx to work with.
vid	The VID whose data to update.
data	The PID to update it with.
indexWords	Optional index word terms under which this data should be found via dvSearch. Use NULL for none.

Returns

RUE_OK on success or an error code.

dvWipe()

DVAPI int32_t dvWipe	(	dvCtx	dc,
		ruList	vids
	)

Wipes all or given list of VID entries from the local cache.

Parameters

dc	The dvCtx to work with.
vids	List of VID entries to be deleted. Leave NULL to wipe all entries.

Returns

RUE_OK on success or an error code.