Configuration¶

For information on configuring klutshnik, see the man-page klutshnik.cfg(5).

Command-line usage and examples¶

Long-term signing key¶

klutshnik uses EdDSA long-term signing keys for authentication towards the KMS servers. This key can be stored on disk and referenced in the klutshnik.cfg(5) config file. Alternatively klutshnik can take the client long-term signing key on the standard input. Note: If you are decrypting a file, the file itself is also expected on the standard input. In this case the ltsigkey and the file - if required - should be simply (in this order) concatenated.

It is warmly recommended to use pwdsphinx https://github.com/stef/pwdsphinx as a "storage" for the client long-term signing keys, since it handles keys also in a threshold setup in a most secure manner.

Key Names¶

KeyIds are the identifiers that you use to address your records, they can be any kind of string. Internally this name is hashed using the id_salt from the configurations [client] section into a unique key identifier. As this salt is necessary to access your records, it is strongly recommended to set the id_salt to some random value and to back up this value. If you use a commonly used salt (i.e. the default salt) chances are high that there are collisions for record ids, and that people can guess your record ids.

Command-line Operations¶

Initialize a new config¶

% klutshnik init

This checks if the ltsigkey_path variable is pointing at a non-existing file. If this is the case, then the client generates a new long-term signing-key, saves it at the pointed location and prints the public key on standard output. This public key value must be manually added to the config file setting the value for ltsigpub in the [client] section.

Furthermore this also checks if the directory pointed at by the keystore value in the [client] section exists and if not creates this.

Note it is recommended to store your private ltsigkey in a more secure location than your disk, if possible store it in a password manager, like pwdsphinx(1), see klutshnik.cfg(5) for more details.

Create a new key¶

Creating a new key is as simple as providing a key name and if ltsigkey_path is not configured the long-term signing private key on the standard input.

% klutshnik create <keyname> [<ltsigkey]

If everything went fine, the client outputs the public key, which can be used to encrypt files. These can be decrypted by the key referenced by the key name you provided.

This operation sets the long-term signing public key of the creator as the owner of the key, giving all permissions to them.

Encrypt a file¶

Encrypting a file requires the latest public key as provided by the create, rotate and refresh operations. Users who have no authorization to interact with the keyid on the KMS' must rely on any of the authorized users to provide the public key of the current epoch. This operation does not require a long-term signing key.

% klutshnik encrypt <public key> <plaintext >ciphertext

Decrypt a file¶

Decrypting a file just pipe the ciphertext into the process and get the plaintext on standard output. If you don't have your long-term signing key in your configuration, this is expected as a prefix to the encrypted file. Of course this works on the condition that enough KMS' are responding correctly and that the file has been updated with the delta of the current epoch.

% klutshnik decrypt [<ltsigkey] <ciphertext >plaintext

Rotate a key¶

Rotating a key can be done by specifying the name of the key that you want to rotate. Depending on your configuration, you must supply your long-term signing key on standard input. The output of this operation is:

•

the new public key, which you should distribute to anyone who is expected to encrypt to this key, and

•

your update delta token which is required to update the encryption of the files encrypted with this key.

It is essential to run the update procedure from the next section on all files encrypted with the rotated key by applying this update delta token to them.

Make sure that you keep this update token delta secret, if it leaks, it will neutralize the forward secrecy and post-compromise security properties of this protocol for the current and the previous key.

% klutshnik rotate <keyname> [<ltsigkey] >pubkey-and-delta

Update a file with a rotated key¶

Files encrypted with the key referenced by the key name can be bulk-updated by piping:

•

the update delta token from the rotate operation described in the previous section, and

•

the list of paths pointing at these files into the CLI client.

This operation does not require a long-term signing key. Furthermore this is an offline operation, there is no need for connectivity to the KMS', In fact this operation can run on the storage server itself.

% klutshnik update <delta  <files2update

Warning: Make sure that you keep the update token delta secret, if it leaks, it will neutralize the forward secrecy and post-compromise security properties of this protocol for the current and the previous key.

Refresh local key metadata¶

The client keeps a local cache of some key related metadata:

•

as the public key,

•

the current epoch,

•

the threshold,

•

the owner public key, and

•

the shares that can be combined into the public key.

When a client rotates a key, some of these values change. Other clients should refresh their own local copy of these by running a refresh operation.

% klutshnik refresh <keyname> [<ltsigkey] >pk

This operation will output the current public key associated with the keyname on standard output.

Delete a key¶

This operation deletes the shares of the key referenced by the keyname if the provided (either in the configuration file or on standard input) long-term signing key is authorized to do so.

% klutshnik delete <keyname> [<ltsigkey]

Authorize a user¶

Adding additional users and authorization permissions can be done by using the adduser operation. The parameters to this operation are

•

the keyname to which a new user is added,

•

the base64 encoded long-term public signing-key,

•

and a list of permissions, separated by commas: owner,decrypt,update,delete

The user executing this operation must be in possession of a long-term signing-key, which has the owner permission.

% klutshnik adduser <keyname> <b64 pubkey> <owner,decrypt,update,delete> [<ltsigkey]

The output of this operation is the base64 encoded serialized setup related to this key. This data is they keyid, and the [server] section with ltsigkey and ssl_cert files inlined. This "token" must be passed to the user who has been authorized, so they can import this into their own configuration.

Delete a user¶

A user which has the owner permission associated with their long-term signing key associated with a key referenced by the keyname can delete an user specified by their public key.

% klutshnik deluser <keyname> <b64 pubkey> [<ltsigkey]

List authorizations of users¶

A user which has the owner permission associated with their long-term signing key associated with a key referenced by the keyname can list all authorized users and their permissions.

% klutshnik listusers <keyname> [<ltsigkey]

Import Foreign Key Setup¶

Non-owner users who have been authorized - unless they have the same id_salt value and the same [server] section in their config as the owner -, must import the setup of the owner into their local keystore. The setup is exported by the owner automatically when running an adduser operation, this output must be passed to the user being authorized as follows:

% klutshnik import <keyid> <KLTCFG-...b64...> [<ltsigkey]

This command automatically runs internally a refresh operation to query the current epoch and public key related to this key. All this is stored in the local keystore of the user.