Elektra can protect the following aspects of your configuration\+:


\begin{DoxyEnumerate}
\item confidentiality (i.\+e. protection against unauthorized access), and
\item integrity (i.\+e. protection against unauthorized modification).
\end{DoxyEnumerate}

Elektra provides two plugins to achieve this protection\+:


\begin{DoxyEnumerate}
\item {\ttfamily crypto}, and
\item {\ttfamily fcrypt}.
\end{DoxyEnumerate}

\subsection*{Prerequisites -\/ Gnu\+PG}

For the rest of this tutorial we assume that you are somewhat familiar with Gnu\+PG (G\+PG). The documentation of Gnu\+PG can be found \href{https://gnupg.org/documentation/index.html}{\tt here}.

In order to find your G\+PG private key(s) you can use\+: \begin{DoxyVerb}    gpg2 --list-secret-keys
\end{DoxyVerb}


If G\+PG private keys are available, you see an output, that looks similar to this\+: \begin{DoxyVerb}    sec   rsa1024 2016-08-20 [SC]
              DDEBEF9EE2DC931701338212DAF635B17F230E8D
    uid           [ultimate] Elektra Unit Tests (DO NOT USE IN PRODUCTION) <unit-tests@libelektra.org>
    ssb   rsa1024 2016-08-20 [E]
\end{DoxyVerb}


The G\+PG key we use in this tutorial has the ID {\ttfamily D\+D\+E\+B\+E\+F9\+E\+E2\+D\+C931701338212\+D\+A\+F635\+B17\+F230\+E8D}.

A G\+PG private key is mandatory for the plugins to work. If you have no G\+PG private key available, you can generate one by entering the following command\+: \begin{DoxyVerb}    gpg2 --generate-key
\end{DoxyVerb}


The {\ttfamily fcrypt} plugin and the {\ttfamily crypto} plugin support both versions (version 1 and version 2) of G\+PG.

\subsection*{Introduction}

In this tutorial we explain the use of the {\ttfamily crypto} plugin and the {\ttfamily fcrypt} plugin by a simple example\+: We want to protect a password that is contained in an I\+N\+I-\/file.

The following example demonstrates how the I\+N\+I-\/file is mounted without encryption enabled. We create the password at {\ttfamily user/test/password} and display the contents of {\ttfamily test.\+ini}.

{\itshape Step 1\+:} Mount {\ttfamily test.\+ini}


\begin{DoxyCode}
kdb set /sw/elektra/kdb/#0/current/plugins ""
sudo kdb mount test.ini user/test ini
\end{DoxyCode}


{\itshape Step 2\+:} Set the password at {\ttfamily user/test/password} and display the contents of {\ttfamily test.\+ini}


\begin{DoxyCode}
kdb set user/test/password 1234
#> Create a new key user/test/password with string "1234"
kdb file user/test/password | xargs cat
#> password = 1234
\end{DoxyCode}


{\itshape Step 3\+:} (Optional) Cleanup


\begin{DoxyCode}
kdb rm user/test/password
kdb rm /sw/elektra/kdb/#0/current/plugins
sudo kdb umount user/test
\end{DoxyCode}


As you can see the password is stored in plain text. In this tutorial we demonstrate two different approaches towards confidentiality\+:


\begin{DoxyEnumerate}
\item with the {\ttfamily fcrypt} plugin, which encrypts the entire I\+N\+I-\/file, and
\item with the {\ttfamily crypto} plugin, which allows the encryption of specific key values only.
\end{DoxyEnumerate}

We also show how to approach integrity with the signature features of the {\ttfamily fcrypt} plugin.

\subsection*{Configuration File Encryption/\+Decryption}

The {\ttfamily fcrypt} plugin enables the encryption and decryption of entire configuration files, thus protecting the confidentiality of the configuration keys and values. {\ttfamily fcrypt} utilizes G\+PG for all cryptographic operations. The G\+PG key, which is used for encryption and decryption, is specified in the backend configuration under {\ttfamily encrypt/key}. \begin{DoxyVerb}    sudo kdb mount test.ini user/test fcrypt "encrypt/key=DDEBEF9EE2DC931701338212DAF635B17F230E8D" ini
\end{DoxyVerb}


If the above command fails, please take a look at the \href{https://master.libelektra.org/src/plugins/fcrypt/README.md#known-issues}{\tt Read\+Me of the {\ttfamily fcrypt} plugin}.

As a result the file {\ttfamily test.\+ini} is encrypted using Gnu\+PG. {\ttfamily fcrypt} will call the {\ttfamily gpg2} or {\ttfamily gpg} binary as follows\+: \begin{DoxyVerb}    gpg2 -o test.ini -a -r DDEBEF9EE2DC931701338212DAF635B17F230E8D -e test.ini.tmp
\end{DoxyVerb}


Note that {\ttfamily test.\+ini} can not only be decrypted by Elektra, but it is also possible to decrypt it with Gnu\+PG directly. You can try to decrypt {\ttfamily test.\+ini} with G\+PG\+: \begin{DoxyVerb}    gpg2 -d test.ini
\end{DoxyVerb}


The complete procedure looks like this\+:


\begin{DoxyCode}
kdb set /sw/elektra/kdb/#0/current/plugins ""
sudo kdb mount test.ini user/test fcrypt "encrypt/key=DDEBEF9EE2DC931701338212DAF635B17F230E8D" ini
kdb set user/test/password 1234
#> Create a new key user/test/password with string "1234"
kdb file user/test/password | xargs cat
\end{DoxyCode}


To clean up the environment we run\+:


\begin{DoxyCode}
kdb rm user/test/password
kdb rm /sw/elektra/kdb/#0/current/plugins
sudo kdb umount user/test
\end{DoxyCode}


\subsection*{Configuration File Signatures}

{\ttfamily fcrypt} also offers the option to sign and verify configuration files, thus protecting the integrity of the configuration values. If {\ttfamily sign/key} is specified in the backend configuration, {\ttfamily fcrypt} will forward the key ID for signing the configuration file.

An example backend configuration is given as follows\+: \begin{DoxyVerb}    sudo kdb mount test.ini user/test fcrypt "sign/key=DDEBEF9EE2DC931701338212DAF635B17F230E8D" ini
\end{DoxyVerb}


As a result the file {\ttfamily test.\+ini} will be signed using G\+PG. {\ttfamily fcrypt} will call the {\ttfamily gpg2} or {\ttfamily gpg} binary as follows\+: \begin{DoxyVerb}    gpg2 -o test.ini -a -u DDEBEF9EE2DC931701338212DAF635B17F230E8D -r DDEBEF9EE2DC931701338212DAF635B17F230E8D -s test.ini.tmp
\end{DoxyVerb}


If {\ttfamily test.\+ini} is modified, all following calls of {\ttfamily kdb get} will fail with an error message stating that the signature of the file could not be verified.

The complete example looks like this\+:


\begin{DoxyCode}
kdb set /sw/elektra/kdb/#0/current/plugins ""
sudo kdb mount test.ini user/test fcrypt "sign/key=DDEBEF9EE2DC931701338212DAF635B17F230E8D" ini
kdb set user/test/password 1234
#> Create a new key user/test/password with string "1234"
kdb file user/test/password | xargs cat
\end{DoxyCode}


To clean up the environment we run\+:


\begin{DoxyCode}
kdb rm user/test/password
kdb rm /sw/elektra/kdb/#0/current/plugins
sudo kdb umount user/test
\end{DoxyCode}


\subsubsection*{Combining Signatures and Encryption}

The options {\ttfamily sign/key} and {\ttfamily encrypt/key} can be combined together, resulting in configuration files, that are signed and encrypted.

Mounting {\ttfamily test.\+ini} with signatures and encryption enabled can be done like this\+: \begin{DoxyVerb}    sudo kdb mount test.ini user/test fcrypt "sign/key=DDEBEF9EE2DC931701338212DAF635B17F230E8D,encrypt/key=DDEBEF9EE2DC931701338212DAF635B17F230E8D" ini
\end{DoxyVerb}


The complete example looks like this\+:


\begin{DoxyCode}
kdb set /sw/elektra/kdb/#0/current/plugins ""
sudo kdb mount test.ini user/test fcrypt "sign/key=DDEBEF9EE2DC931701338212DAF635B17F230E8D,encrypt/key"
       ini
kdb set user/test/password 1234
#> Create a new key user/test/password with string "1234"
kdb file user/test/password | xargs cat
\end{DoxyCode}


To clean up the environment we run\+:


\begin{DoxyCode}
kdb rm user/test/password
kdb rm /sw/elektra/kdb/#0/current/plugins
sudo kdb umount user/test
\end{DoxyCode}


\subsection*{Configuration Value Encryption/\+Decryption}

So far we learned how to encrypt and decrypt entrie configuration files. Sometimes we only want to protect a smaller subset of configuration values in a bigger configuration setting. For this reason the {\ttfamily crypto} plugin was developed.

The {\ttfamily crypto} plugin is actually a family of plugins and comes with three different providers\+:


\begin{DoxyEnumerate}
\item {\ttfamily crypto\+\_\+gcrypt} using {\ttfamily libgcrypt},
\item {\ttfamily crypto\+\_\+openssl} using {\ttfamily libcrypto}, and
\item {\ttfamily crypto\+\_\+botan} using {\ttfamily Botan}.
\end{DoxyEnumerate}

We recommend that you use {\ttfamily crypto\+\_\+gcrypt} as it is the fastest variant. The variants of the {\ttfamily crypto} plugin work the same internally, but use a different crypto library for cryptographic operations.

The {\ttfamily crypto} plugins provide the option to encrypt and decrypt single configuration values (Keys) in a Keyset. G\+PG is required for the key-\/handling.

To follow our example of an encrypted password in {\ttfamily test.\+ini}, we first mount the I\+N\+I-\/file with the {\ttfamily crypto\+\_\+gcrypt} plugin enabled, like this\+: \begin{DoxyVerb}    sudo kdb mount test.ini user/test crypto_gcrypt "crypto/key=DDEBEF9EE2DC931701338212DAF635B17F230E8D" base64 ini
\end{DoxyVerb}


We recommend adding the {\ttfamily base64} plugin to the backend, because {\ttfamily crypto} will output binary data. Having binary data in configuration files is hardly ever feasible. {\ttfamily base64} encodes all binary values within a configuration file and transforms them into Base64 strings.

\subsubsection*{Marking Keys For Encryption}

To tell the {\ttfamily crypto} plugin which Keys it should process, the metakey {\ttfamily crypto/encrypt} is used. The {\ttfamily crypto} plugin searches for the metakey {\ttfamily crypto/encrypt}. If the value is equal to {\ttfamily 1}, the value of the Key will be encrypted.

We want to protect the password, that is stored under {\ttfamily user/test/password}. So we set the metakey as follows\+: \begin{DoxyVerb}    kdb setmeta user/test/password crypto/encrypt 1
\end{DoxyVerb}


Now we are safe to set the actual password\+: \begin{DoxyVerb}    kdb set user/test/password "1234"
\end{DoxyVerb}


The resulting I\+N\+I-\/file contains the following data\+: \begin{DoxyVerb}    #@META crypto/encrypt = 1
    password = @BASE64IyFjcnlwdG8wMBEAAADwPI+lqp+X2b6BIfLdRYgwxmAhVUPurqkQVAI78Pn4OYONbei4NfykMPvx9C9w91KT
\end{DoxyVerb}


You can access the password as usual with {\ttfamily kdb get}\+: \begin{DoxyVerb}    kdb get user/test/password
\end{DoxyVerb}


As a result you get \char`\"{}1234\char`\"{}.

\subsubsection*{Disabling Encryption}

You can disable the encryption by setting {\ttfamily crypto/encrypt} to a value other than {\ttfamily 1}, for example\+: \begin{DoxyVerb}    kdb setmeta user/test/password crypto/encrypt 0
\end{DoxyVerb}


\subsubsection*{Complete Example}

The complete example looks like this\+:


\begin{DoxyCode}
kdb set /sw/elektra/kdb/#0/current/plugins ""
sudo kdb mount test.ini user/test crypto\_gcrypt "crypto/key=DDEBEF9EE2DC931701338212DAF635B17F230E8D"
       base64 ini
kdb setmeta user/test/password crypto/encrypt 1
kdb file user/test/password | xargs cat
kdb set user/test/password 1234
#> Set string to "1234"
kdb set user/test/config "I am not encrypted"
#> Create a new key user/test/config with string "I am not encrypted"
kdb file user/test/password | xargs cat
\end{DoxyCode}


To disable encryption on {\ttfamily user/test/password}, we can run\+:


\begin{DoxyCode}
kdb setmeta user/test/password crypto/encrypt 0
kdb file user/test/password | xargs cat
\end{DoxyCode}


To clean up the environment we run\+:


\begin{DoxyCode}
kdb rm user/test/config
kdb rm user/test/password
kdb rm /sw/elektra/kdb/#0/current/plugins
sudo kdb umount user/test
\end{DoxyCode}
 