Working with KVDBs

• KVDBs allow users to access key-value databases.
• Each Context can contain any number of KVDBs with a unique identifier (kvdbId) used to distinguish them.
• KVDBs do not need to have unique names or assigned public keys.

Permissions

KVDBs differentiate two types of users - Managers and Regular Users. The table below shows the differences in their permissions:

The values above are the default policy values defined by PrivMX. To read more about Policies and learn how to modify them, go to Policies.

var kvdbApi : KvdbApi

let KVDB_ID = "ID of your KVDB"
let KVDB_ENTRY_KEY = "KEY"
let KVDB_ENTRY_KEY_1 = "KEY_1"
let KVDB_ENTRY_KEY_2 = "KEY_2"

Working with KVDBs

To access KVDBs methods, get the field kvdbApi from the active endpointSession. Session should be initialized with [.kvdb] and passed to PrivMXEndpoint. You can use a guard let statement to ensure the kvdbApi field is not null and avoid having to deal with optionals.

guard let sessionKvdbApi = endpointSession?.kvdbApi
else {return}
kvdbApi = sessionKvdbApi

In the below code snippets we assume that kvdbApi has been assigned like this.

Creating KVDBs

To create a KVDB, you need a name and a list of public key - userID pairs. Due to the fact that each KVDB is inside a Context, all the public keys have to be registered inside the given Context. You can do it using PrivMX Bridge API.

// ...

let publicMeta = Data()
let privateMeta = Data()

let kvdbId = try kvdbApi.createKvdb(
	in: CONTEXT_ID,
	for: [privmx.endpoint.core.UserWithPubKey(
		userId: USER1_ID,
		pubKey: USER1_PUBLIC_KEY)
		],
	managedBy: [privmx.endpoint.core.UserWithPubKey(
		userId: USER1_ID,
		pubKey: USER1_PUBLIC_KEY)
		],
	withPublicMeta: Data(),
	withPrivateMeta: Data())
}

// ...

Listing KVDBs

Your application may include multiple KVDBs, each associated with different Contexts. You can retrieve a list of all KVDBs within a given Context. This list will include useful metadata about the KVDBs, such as the creation date, last message upload date, user list, and information about the last modification. However, to optimize performance, the list will only include the total number of entries in each KVDB, not the full entry content.

Getting a list of KVDBs available for the user in the given Context:

// ...

let kvdbList = try kvdbApi.listKvdbs(
	from: CONTEXT_ID,
	basedOn: privmx.endpoint.core.PagingQuery(
		skip: 0,
		limit: 25,
		sortOrder: .desc))

// ...

As a result you will receive a privmx.KvdbsList object.

Getting a single KVDB:

// ...

let KVDB_ID = "ID of your KVDB"
		
let kvdb = kvdbApi.getKvdb(KVDB_ID)

// ...

A detailed description of the Kvdb object fields can be found in API Reference.

Modifying KVDBs

Depending on your project's specification, it may be necessary to modify a KVDB. It could be e.g. changing the name or adding/removing users. Each user with management rights is able to modify KVDB, delete them as a whole or only particular entries.

Three additional options are available when changing the list of users inside a KVDB:

• force - applies an update, without checking the current version;
• forceGenerateNewKey - re-encrypts entries in the KVDB. It's useful when a user is removed and we want to prevent them from accessing the KVDB.
• policies - allow you to manage access to KVDB and entries. Read more about Policies.

Updating a KVDB means overwriting it with the provided data. To successfully update a KVDB, you must specify its current version. The version field is mandatory to handle multiple updates on the server and it is incremented by 1 with each update.

The updateKvdb(_:atVersion:replacingUsers:replacingManagers:replacingPublicMeta:replacingPrivateMeta:force:forceGenerateNewKey:) method needs all the parameters as in the createKvdb(in:for:managedBy:withPublicMeta:withPrivateMeta:) method and a few more.

If you want to update one of the parameters – provide it in a new modified form. If, on the other hand, you want to leave the parameter unchanged – provide it as it was before.

// ...

let KVDB_ID = "ID of your KVDB"

let currentKvdb = try kvdbApi.getKvdb(KVDB_ID)

try kvdbApi.updateKvdb(
	kvdbId,
	atVersion: currentKvdb.version,
	replacingUsers: [privmx.endpoint.core.UserWithPubKey(
		userId: USER1_ID,
		pubKey: USER1_PUBLIC_KEY)
		],
	replacingManagers: [privmx.endpoint.core.UserWithPubKey(
		userId: USER1_ID,
		pubKey: USER1_PUBLIC_KEY)
		],
	replacingPublicMeta: Data(from:currentKvdb.publicMeta),
	replacingPrivateMeta: Data(from: currentKvdb.privateMeta),
	force: false,
	forceGenerateNewKey: false)

// ...

Deleting KVDBs

To delete a KVDB, use deleteKvdb(_:) method.

// ...
let KVDB_ID = "ID of your KVDB"

try kvdbApi.deleteKvdb(KVDB_ID)
//...