
\begin{DoxyItemize}
\item infos = Information about fcrypt plugin is in keys below
\item infos/author = Peter Nirschl \href{mailto:peter.nirschl@gmail.com}{\tt peter.\+nirschl@gmail.\+com}
\item infos/licence = B\+SD
\item infos/provides = sync filefilter crypto
\item infos/needs =
\item infos/recommends =
\item infos/placements = pregetstorage postgetstorage precommit
\item infos/ordering = sync
\item infos/status = unittest nodep configurable
\item infos/metadata =
\item infos/description = File Encryption
\end{DoxyItemize}\hypertarget{md_src_plugins_fcrypt_README_src_plugins_fcrypt_README_md}{}\section{fcrypt Plugin}\label{md_src_plugins_fcrypt_README_src_plugins_fcrypt_README_md}
\subsection*{Introduction}

This plugin enables file based encryption and decryption using G\+PG. Also an option for signing and verifying files using G\+PG is provided.

This plugin encrypts backend files before the commit is executed (thus {\ttfamily precommit}). The plugin decrypts the backend files before the getstorage opens it (thus {\ttfamily pregetstorage}). After the getstorage plugin has read the backend file, the plugin decrypts the backend file again (thus {\ttfamily postgetstorage}).

\subsection*{Security Considerations}

There are two things to consider when using the {\ttfamily fcrypt} plugin\+:


\begin{DoxyEnumerate}
\item Decrypted data is visible on the file system for a short period of time.
\item Decrypted data might end up on a hard disk or some other persistent storage.
\end{DoxyEnumerate}

The plugin directs G\+PG to write its (decrypted) output to a temporary directory. From there on the data can be processed by other plugins. After the {\ttfamily get} phase is over, {\ttfamily fcrypt} overwrites the temporary file and unlinks it afterwards. However, if the application crashes during {\ttfamily get} the decrypted data may remain in the temporary directory.

If the temporary directory is mounted on a hard disk, G\+PG writes the decrypted data on that disk. Thus we recommend to either mount {\ttfamily /tmp} to a R\+AM disk or specify another path as temporary directory within the plugin configuration (see Configuration below).

\subsection*{Known Issues}

If you encounter the following error at {\ttfamily kdb mount}\+:


\begin{DoxyCode}
The command kdb mount terminated unsuccessfully with the info:
Too many plugins!
The plugin sync can't be positioned at position precommit anymore.
Try to reduce the number of plugins!

Failed because precommit with 7 is larger than 6
Please report the issue at https://issues.libelektra.org/
\end{DoxyCode}


you might want to consider disabling the sync plugin by entering\+:


\begin{DoxyCode}
kdb set /sw/elektra/kdb/#0/current/plugins ""
kdb set system/sw/elektra/kdb/#0/current/plugins ""
\end{DoxyCode}


Please note that this is a workaround until a more sustainable solution is found.

\subsection*{Dependencies}

\subsubsection*{Crypto Plugin}

This plugin uses parts of the {\ttfamily crypto} plugin.

\subsubsection*{Gnu\+PG (G\+PG)}

Please refer to \hyperlink{md_src_plugins_crypto_README_src_plugins_crypto_README_md}{crypto}.

\subsection*{Restrictions}

Please refer to \hyperlink{md_src_plugins_crypto_README_src_plugins_crypto_README_md}{crypto}.

\subsection*{Examples}

You can mount the plugin with encryption enabled like this\+:


\begin{DoxyCode}
kdb mount test.ecf /t fcrypt "encrypt/key=DDEBEF9EE2DC931701338212DAF635B17F230E8D"
\end{DoxyCode}


If you only want to sign the configuration file, you can mount the plugin like this\+:


\begin{DoxyCode}
kdb mount test.ecf /t fcrypt "sign/key=DDEBEF9EE2DC931701338212DAF635B17F230E8D"
\end{DoxyCode}


Both options {\ttfamily encrypt/key} and {\ttfamily sign/key} can be combined\+:


\begin{DoxyCode}
kdb mount test.ecf /t fcrypt \(\backslash\)
  "encrypt/key=DDEBEF9EE2DC931701338212DAF635B17F230E8D,sign/key=DDEBEF9EE2DC931701338212DAF635B17F230E8D"
\end{DoxyCode}


If you create a key under {\ttfamily /t}


\begin{DoxyCode}
kdb set /t/a "hello world"
\end{DoxyCode}


you will notice that you can not read the plain text of {\ttfamily test.\+ecf} because it has been encrypted by G\+PG.

But you can still access {\ttfamily /t/a} with {\ttfamily kdb get}\+:


\begin{DoxyCode}
kdb get /t/a
\end{DoxyCode}


If you are looking for a more interactive example, have a look at the following A\+S\+C\+I\+Icast at\+:

\href{https://asciinema.org/a/153014}{\tt https\+://asciinema.\+org/a/153014}

\subsection*{Configuration}

\subsubsection*{Signatures}

The G\+PG signature keys can be specified as {\ttfamily sign/key} directly. If you want to use more than one key for signing, just enumerate like\+:


\begin{DoxyCode}
sign/key/#0
sign/key/#1
\end{DoxyCode}


If more than one key is defined, every private key is used to sign the file of the backend.

If a signature is attached to a file, {\ttfamily fcrypt} automatically verifies its content whenever the file is being read.

Note that the signed file is stored in the internal format of G\+PG. So you only see binary data when opening the signed configuration file directly. However, you can simply display the plain text content of the file by using G\+PG\+:


\begin{DoxyCode}
gpg2 -d signed.ecf
\end{DoxyCode}


\subsubsection*{G\+PG Configuration}

The G\+PG Configuration is described in \hyperlink{md_src_plugins_crypto_README_src_plugins_crypto_README_md}{crypto}.

\subsubsection*{Textmode}

{\ttfamily fcrypt} operates in textmode per default. In textmode {\ttfamily fcrypt} uses the {\ttfamily -\/-\/armor} option of G\+PG, thus the output of {\ttfamily fcrypt} is A\+S\+C\+II armored. If no encryption key is provided (i.\+e. only signature is requested) {\ttfamily fcrypt} uses the {\ttfamily -\/-\/clearsign} option of G\+PG.

Textmode can be disabled by setting {\ttfamily fcrypt/textmode} to {\ttfamily 0} in the plugin configuration.

\subsubsection*{Temporary Directory}

{\ttfamily fcrypt} uses the configuration option {\ttfamily fcrypt/tmpdir} to generate paths for temporary files during encryption and decryption. If no such configuration option is provided, {\ttfamily fcrypt} will try to use the environment variable {\ttfamily T\+M\+P\+D\+IR}. If {\ttfamily T\+M\+P\+D\+IR} is not set in the environment, {\ttfamily /tmp} is used as default directory.

The path of the temporary directory is forwarded to G\+PG via the {\ttfamily -\/o} option, so G\+PG will output to this path. The directory must be readable and writable by the user.

We recommend to specify a path that is mounted to a R\+AM disk. It is advisable to set restrictive access rules to this path, so that other users on the system can not access it. 