.TH "md_src_plugins_crypto_README" 3elektra "Sun May 29 2016" "Version 0.8.14" "Elektra" \" -*- nroff -*-
.ad l
.nh
.SH NAME
md_src_plugins_crypto_README \- README 

.IP "\(bu" 2
infos = Information about crypto plugin is in keys below
.IP "\(bu" 2
infos/author = Peter Nirschl peter.nirschl@gmail.com
.IP "\(bu" 2
infos/licence = BSD
.IP "\(bu" 2
infos/needs =
.IP "\(bu" 2
infos/provides = filefilter
.IP "\(bu" 2
infos/placements = postgetstorage presetstorage
.IP "\(bu" 2
infos/description = Cryptographic operations
.PP
.PP
This plugin is a filter plugin allowing Elektra to encrypt values before they are persisted and to decrypt values after they have been read from a backend\&.
.PP
The idea is to provide protection of sensible values before they are persisted\&. This means the value of a key needs to be encrypted before it is written to a file or a database\&. It also needs to be decrypted whenever an admissible access (read) is being performed\&.
.PP
The users of Elektra should not be bothered too much with the internals of the cryptographic operations\&. Also the cryptographic keys must never be exposed to the outside of the crypto module\&.
.PP
.SS "Dependencies"
.PP
.IP "\(bu" 2
\fClibgcrypt20-dev\fP or \fClibgcrypt-devel\fP
.PP
.PP
.SS "Restrictions"
.PP
The crypto plugin will encrypt and decrypt values using AES-256 in CBC mode\&.
.PP
The key derivation is still WIP\&.
.PP
.SS "Planned Features"
.PP
.IP "\(bu" 2
Encryption of values
.IP "\(bu" 2
Decryption of values
.IP "\(bu" 2
Key derivation by metadata (password provided within a meta-key)
.IP "\(bu" 2
Key derivation by using a specified key-file (like the SSH client does)
.IP "\(bu" 2
Key derivation by utilizing the pgp-agent
.PP
.PP
The encryption and decryption of values is a straight forward process, once the key and IV are supplied\&. The key-derivation process in a library is a bit tricky\&.
.PP
The crypto plugin itself can hold configuration data about the order of the applied key derivation functions\&. For example, if a password is provided by a meta-key, it will be used, otherwise we look for a key file\&. If no key file has been configured, we try to trigger the PGP agent, etc\&.
.PP
The following example configuration illustrates this concept: 
.PP
.nf
    system/elektra/crypto/config/key-derivation/#0 = meta
    system/elektra/crypto/config/key-derivation/#1 = file
    system/elektra/crypto/config/key-derivation/#2 = agent
    system/elektra/crypto/config/key-file/path/#0 = ~/.elektra/id_aes
    system/elektra/crypto/config/key-file/path/#1 = /etc/elektra/id_aes

.fi
.PP
.PP
Only keys marked with a certain meta-key will be considered for encryption/decryption\&.
.PP
.SS "Examples"
.PP
.SS "Metadata based encyption"
.PP
You specify the parameters of the cryptographic operations in a KeySet together with the keys to be encrypted\&. The following parameters are required:
.PP
.IP "\(bu" 2
\fBKey\fP - the symmetric cryptographic key for encryption
.IP "\(bu" 2
\fBIV\fP - the initialization vector (IV) that is required by the CBC mode
.PP
.PP
The following keys are required for metadata based encryption: 
.PP
.nf
    /elektra/modules/crypto/key-derivation/key
    /elektra/modules/crypto/key-derivation/iv

.fi
.PP
.PP
You can use the following meta-key to mark a key for encryption: 
.PP
.nf
    crypto/encrypt

.fi
.PP
.PP
If this meta-key has a value with a string-length greater than 0 (\fCstrlen() > 0\fP) then the crypto-plugin will try to encrypt it\&.