Data are stored in secure wallets protected and signed by their own AES-256 key.

Wallets are protected by a master key using AES-256-CBC and the wallet master key is protected by a user password. The wallet defines up to 7 slots that identify a password key that is able to unlock the master key. To open a wallet, it is necessary to unlock one of these 7 slots by providing the correct password. Wallet key slots are protected by the user's password and the PBKDF2-HMAC-256 algorithm, a random salt, a random counter and they are encrypted using AES-256-CBC. A wallet key slot can also be protected by a GPG private key.

Data stored in the wallet are protected by their own encryption keys using AES-256-CBC. Big contents are stored in several data blocks and each data block is encrypted by using its own AES-256-CBC encryption key. Encryption keys are protected by the master key using AES-256-CBC. Data blocks are then signed using HMAC-256.

A wallet can contain another wallet which is then protected by its own encryption keys and passwords (with 7 independent slots). Because the child wallet has its own master key, it is necessary to known the primary password and the child password to unlock the parent wallet first and then the child wallet.

Installation

You can install AKT by using the Debian 10 and Ubuntu 20.04 or 18.04 packages. First, setup to accept the signed packages:

wget -O - https://apt.vacs.fr/apt.vacs.fr.gpg.key | sudo apt-key add -

and choose one of the echo command according to your Linux distribution:

# Ubuntu 20.04
# echo "deb https://apt.vacs.fr/ubuntu-focal focal main" | sudo tee -a /etc/apt/sources.list.d/vacs.list
# Ubuntu 18.04
# echo "deb https://apt.vacs.fr/ubuntu-bionic bionic main" | sudo tee -a /etc/apt/sources.list.d/vacs.list
# Debian 10
# echo "deb https://apt.vacs.fr/debian-buster buster main" | sudo tee -a /etc/apt/sources.list.d/vacs.list

Then, launch the apt update command:

sudo apt-get update

and install the tool using:

sudo apt-get install -y akt

You can also build from the source by using the following commands:

sudo apt-get install -y make gnat-7 gprbuild git gnupg2 libfuse-dev
git clone --recursive https://github.com/stcarrez/ada-keystore.git
cd ada-keystore
./configure --enable-fuse

Using AKT

To setup a keystore file and protect it with your GPG key, use the following command:

akt create secure.akt --gpg your-gpg-key-id

The keystore content can be mounted as a filesystem so that the encrypted content are directly available to existing applications as regular files. The mount command starts the fuse daemon and puts the command as a background fuse daemon to serve as a fuse filesystem and make the content visible through the mount point.

akt mount secure.akt /mnt

After the mount is successful, you can copy or access any file stored in the secure keystore. By default the Fuse filesystem is configured to ask the kernel to avoid caching the decrypted content. This has an impact on the performance since every access requires to decrypt the content.

To unmount the filesystem, you must use the umount command.

umount /mnt

Sometimes, you may have to force the umount by running:

sudo umount /mnt

AKT stores information in secure wallets and protects the stored information by encrypting the content with different keys. AKT can be used to safely store passwords, credentials, bank accounts, documents and even directories.

Wallets are protected by a master key using AES-256 and the wallet master key is protected by a user password or a user GPG encrypted key. The wallet defines up to 7 slots that identify a password key that is able to unlock the master key. To open a wallet, it is necessary to unlock one of these 7 slots by providing the correct password. Wallet key slots are protected by the user's password and the PBKDF2-HMAC-256 algorithm, a random salt, a random counter and they are encrypted using AES-256.

Values stored in the wallet are protected by their own encryption keys using AES-256. A wallet can contain another wallet which is then protected by its own encryption keys and passwords (with 7 independent slots). Because the child wallet has its own master key, it is necessary to known the primary password and the child password to unlock the parent wallet first and then the child wallet.

The data is organized in 4K blocks whose primary content is encrypted either by the wallet master key or by the entry keys. The data block is signed by using HMAC-256. A data block can contain several values but each of them is protected by its own encryption key. Each value is also signed using HMAC-256.

The keystore uses several encryption keys at different levels to protect the content. A document stored in the keystore is split in data fragment and each data fragment is encrypted by using its own key. The data fragments are stored in specific data blocks so that they are physically separated from the encryption keys.

The data fragment encryption keys are stored in the directory blocks and they are encrypted by using a specific directory key.

For example, a 10K document will be split in 3 data fragments, each of them encrypted by their own AES-256 key. A 5K document will be encrypted with two AES-256 keys, one for the two data fragments. All these keys are protected by the wallet data key key. The directory part of the wallet which describes entries in the wallet is also encrypted by another wallet key: the directory key.

The tool allows to separate the data blocks which contain data fragments from other blocks. This allows to keep the wallet keys separate from the data. It is then possible to export the data blocks, which are encrypted in AES-256-CBC, to the Cloud without exposing the keys used for encryption.

If you want to know more about the implementation, have a look at the Ada Keystore Implementation chapter.

Using AKT

akt is the command line tool that you can use to protect and store your documents. It contains several commands:

• create: create the keystore
• edit: edit the value with an external editor
• get: get a value from the keystore
• help: print some help
• list: list values of the keystore
• remove: remove values from the keystore
• set: insert or update a value in the keystore

To create the secure file, use the following command and enter your secure password (it is recommended to use a long and complex password):

  akt create secure.akt

You may also protect the keystore by using your GPG key. In that case, you can use the --gpg option and specify one or several GPG key ids. Using GPG is probably the best method to protect your akt files.

  akt create secure.akt --gpg 0xFC15CA870BE470F9

At this step, the secure file is created and it can only be opened by providing the password you entered. To add something, use:

  akt set secure.akt bank.password 012345

To store a file, use the following command:

  akt store secure.akt contract.doc

If you want to retrieve a value, you can use one of:

  akt get secure.akt bank.password
  akt extract secure.akt contract.doc

You can also use the akt command together with the tar command to create secure backups. You can create the compressed tar file, pipe the result to the akt command to store the content in the wallet.

  tar czf - dir-to-backup | akt store secure.akt -- backup.tar.gz

To extract the backup you can use the extract command and feed the result to the tar command as follows:

  akt extract secure.akt -- backup.tar.gz | tar xzf -

Using Ada Keystore

The Ada Keystore is the Ada 2012 library that is behind AKT. It should be quite easy to integrate the library in an existing Ada application to protect for example some sensitive configuration file. The Keystore is the main package that provides operations to store information in secure wallets and protect the stored information by encrypting the content. To use it, add the following with clause at beginning of your GNAT project:

   with "keystoreada";

Creation

To create a keystore you will first declare a Wallet_File instance. You will also need a password that will be used to protect the wallet master key.

with Keystore.Files;
...
  WS   : Keystore.Files.Wallet_File;
  Pass : Keystore.Secret := Keystore.Create ("There was no choice but to be pioneers");

You can then create the keystore file by using the Create operation:

  WS.Create ("secure.akt", Pass);

Storing

Values stored in the wallet are protected by their own encryption keys using AES-256. The encryption key is generated when the value is added to the wallet by using the Add operation.

  WS.Add ("Grace Hopper", "If it's a good idea, go ahead and do it.");

The Get function allows to retrieve the value. The value is decrypted only when the Get operation is called.

  Citation : constant String := WS.Get ("Grace Hopper");

The Delete procedure can be used to remove the value. When the value is removed, the encryption key and the data are erased.

  WS.Delete ("Grace Hopper");

Getting AKT

You can get AKT by using the Ubuntu 18.04 binary packages. You can do this by running:

wget -O - http://apt.vacs.fr/apt.vacs.fr.gpg.key | sudo apt-key add -
sudo add-apt-repository "deb http://apt.vacs.fr/ubuntu-bionic bionic main"
sudo apt-get install akt

For other platforms, you have to get it from the sources. Install the GNAT Ada compiler, either the FSF version or the GNAT GPL version and then, run the following commands:

git clone --recursive https://github.com/stcarrez/ada-keystore.git
cd ada-keystore
./configure --disable-nls
make build install

You can browse the documentation online: Ada Keystore Guide.

The libsecret is the C library that gives access to the Secret Service API. The Ada Libsecret is an Ada binding for the C library. The Ada binding does not allow to access and use all of the functionalities implemented by the C library but it implements the most useful operations allowing to store, retrieve and delete some application secret data.

Understanding the Secret Service API

At first glance, the Secret Service API is not easy to use. Each secret is stored together with lookup attributes and a label. Lookup attributes are formed of key/value pairs. The label is the user friendly name that desktop key manager will use to display some information to the end user.

The Secret Service API is implemented by a keyring manager such as gnome-keyring-daemon or kwalletd. This is a daemon that is started when a user opens a desktop session. It manages the application secrets and protects their access. The secret database can be locked in which case the access to secrets is forbidden. Unlocking is possible but requires authentication by the user (in most cases a dialog popup window opens and asks to unlock the keyring).

When a client application wishes to retrieve one of its secret, it builds the lookup attributes that correspond to the secret to retrieve. The lookup attributes are not encrypted and they are not part of the secret. The client application uses the D-Bus IPC mechanism to ask the keyring manager for the secret. The keyring manager will manage for unlocking the database by asking the user to confirm the access. The keyring manager will then look in its database for the secret associated with the lookup attributes.

Note that the label cannot be used as a key to retrieve the secret since the same label can be associated with different lookup attributes.

Using the Ada Secret Service API

Setting up the project

After building and installing the Ada Libsecret library you will add the following line to your GNAT project file:

with "secret";

This definition will give you access to the Secret package and will handle the build and link support to use the libsecret C library.

Setting the lookup attributes

Attributes are defined by the Secret.Attributes package which provides the Map type that represents the lookup attributes. First, you will add the following with clause:

with Secret.Attributes;

to make available the operations and types provided by the package. Then, you will declare the attributes instance by using:

   List : Secret.Attributes.Map;

At this stage, the lookup attributes are empty and you can check that by using the Is_Null function that will return True in that case. You must now add at least one key/value pair in the attributes by using the Insert procedure:

   List.Insert ("secret-tool", "key-password");
   List.Insert ("user", "joe");

Applications are free about what attributes they use. The attributes have to be unique so that the application can identify and retrieve them. For example, the svn command uses two attributes to store the password to authenticate to svn remote repositories: domain and user. The domain represents the server URL and the user represents the user name to use for the connection. By using these two attributes, it is possible to store several passwords for different svn accounts.

Storing a secret

To store a secret, we will use the operations and types from the Secret.Services and Secret.Values packages. The following definitions:

with Secret.Services;
with Secret.Values;

will bring such definitions to the program. The secret service is represented by the Service_Type type and we will declare an instance of it as follows:

   Service : Secret.Services.Service_Type;

This service instance is a proxy to the Secret Service API and it communicates to the gnome-keyring-daemon by using the D-Bus protocol.

The secret value itself is represented by the Secret_Type and we can define and create such secret by using the Create function as follows:

   Value : Secret.Values.Secret_Type := Secret.Values.Create ("my-secret");

Storing the secret is done by the Store operation which associates the secret value to the lookup attributes and a label. As explained before, the lookup attributes represent the unique key to identify the secret. The label is used to give a user friendly name to the association. This label is used by the desktop password and key manager to give information to the user.

   Service.Store (List, "Secret tool password", Value);

Retreiving a secret

Retreiving a secret follows the same steps but involves using the Lookup function that returns the secret value from the lookup attributes. Care must be made to provide the same lookup attributes that were used during the store phase.

   Value : Secret.Values.Secret_Type := Service.Lookup (List);

The secret value should be checked by using the Is_Null function to verify that the value was found. The secret value itself is accessed by using the Get_Value function.

   if not Value.Is_Null then
      Ada.Text_IO.Put_Line (Value.Get_Value);
   end if;

Conclusion

By using the Ada Secret Service API, Ada applications can now securely store private information and protect resources for their users. The API is fairly simple and can be used to store OAuth access tokens, database passwords, and more...

Read the Ada Libsecret Documentation to learn more about the API.