Python tutorial for Hermes-core

In this tutorial, we are going to launch storage entities for data, public and encryption keys, and will save/delete/edit the data with the help of a Hermes-core console app, as well as grant/revoke access to the data for other users. All this will be carried out cryptographically.

Launching the storage entities

The infrastructure of Hermes-core is divided into 3 parts (you can read more about each entity here and in the scientific paper on Hermes):
- Data store (data storage entity),
- Keystore (storage entity for keys with the help of which the data is encrypted),
- Credential store (storage entity for the users' public keys with the help of which the authentification and authorization take place).

Register service's keys in the Credential store

The service examples have hardcoded private/public keys. To simplify the first run, we placed the public keys into the repository close to examples. Those files have filenames that are base64-encoded names of services that are declared in docs/examples/c/mid_hermes/common/config.h and have binary content of public keys.

cp docs/examples/c/service_keys/* db/credential_store/

Generating user keys

Here we are using our key generator and command it to save a private key in a folder with the name user1.priv, and put the public key into the folder that will be assigned to/available to Credential store — db/credential_store. The filename will be a user identifier in base64. In our case, it is going to be user1.

Note: It is important that the filename is in the correct base64 format as consequently it will be used as the user identifier.

Creating the first document

Folder structure

This is an example folder structure — you probably have something similar right now. Docs/examples/c contains the core components of Hermes-core. The Python client is located in docs/examples/python folder. The database folder db contains encrypted data and access keys / tokens.

--meta first-file — additional metadata that might be used by the current implementation of the Data store.

--config=docs/examples/python/config.json — config file with connection settings and public keys that will be used to establish Secure Session with Credential/Key/Data stores with predefined values for this example.

The command remains the same, only --add was changed to --read and this time we don't have to set the --meta. In all the following commands, the changes will most often be about changing the command type and the --meta parameter will be added/deleted.

So now the content and the meta data we transferred before is displayed for us.
All this data is stored as files in the previously created folder ls db/data_store which will contain a folder with the name that matches the filename of the added file in base64 format — dGVzdGZpbGU=.
This ls db/data_store/dGVzdGZpbGU= folder will contain 3 files:

data
mac
meta

To make sure that your data is truly encrypted, you can display it using:

cat db/data_store/dGVzdGZpbGU=/data

The output will be unprintable because the encrypted data is in binary state and you will not find the traces of the initial data in it.
Currently, only the person (user) who had added the data can make can make changes to it.

But let's change the initial file and update it in Hermes-core:

echo "some new content" > testfile

And let's take another look at what is stored in Hermes-core now. The content is not changed, because we haven't pushed new testfile to data store.

ROTATING data and keys

At this step, let's perform data and key(s) rotation as user2. This rotation means re-encrypting the data using new keys.
To make sure that the key and data rotation indeed takes place (because the data is binary and it would be hard to tell one batch of encrypted data from another), we need to calculate the hash-sum of the encrypted file before and after rotation and check if they match (they shouldn't). If after rotation we read the data again and get the same decrypted data output, it means that the rotation was successful.

Let's calculate and save the hashsum of the ecnrypted file (which is located in db/data_store/dGVzdGZpbGU=/data) into a temporary file:

If the diff command provides some text output, it means that the files (hashsums) we are comparing are different. Otherwise, there would be no text output. So the key and data rotation (its re-encryption using new encryption keys) was successful.

To make sure that the data stays the same, let's read the data (as user3) again:

The MidHermes.getBlock error confirms that it's now impossible to get the block as it had been deleted.
So the data is gone, deleted by user2 who gained all the permissions.

Summary

As you can see, launching the storage entities for data, public and encryption keys for Hermes-core is easy, and the process of granting/revoking permissions (access) to the data between authorised users in Hermes-core is very straightforward and convenient.

We hope that this tutorial was fun and informative and that you now have gained enough understanding of how the things work with Hermes-core — and that now you’ll try using it or build a Hermes-based app of your own.