
\begin{DoxyItemize}
\item infos = Information about crypto 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\+S\+D
\item infos/provides = filefilter
\item infos/needs =
\item infos/recommends =
\item infos/placements = postgetstorage presetstorage \#ifdef E\+L\+E\+K\+T\+R\+A\+\_\+\+C\+R\+Y\+P\+T\+O\+\_\+\+A\+P\+I\+\_\+\+G\+C\+R\+Y\+P\+T \{\#src\+\_\+plugins\+\_\+crypto\+\_\+\+R\+E\+A\+D\+M\+E\+\_\+md\}
\item infos/status = experimental unfinished memleak \#else
\item infos/status = experimental unfinished \#endif
\item infos/metadata = crypto/encrypt
\item infos/description = Cryptographic operations
\end{DoxyItemize}

\section*{Crypto Plugin}

\subsection*{Introduction}

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.

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.

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.

The crypto plugin supports different libraries as provider for the cryptographic operations. At the moment the following crypto A\+P\+Is are supported\+:


\begin{DoxyItemize}
\item Open\+S\+S\+L (libcrypto)
\item libgcrypt
\end{DoxyItemize}

\subsection*{Dependencies}

\#ifdef E\+L\+E\+K\+T\+R\+A\+\_\+\+C\+R\+Y\+P\+T\+O\+\_\+\+A\+P\+I\+\_\+\+G\+C\+R\+Y\+P\+T
\begin{DoxyItemize}
\item {\ttfamily libgcrypt20-\/dev} or {\ttfamily libgcrypt-\/devel} \#endif \#ifdef E\+L\+E\+K\+T\+R\+A\+\_\+\+C\+R\+Y\+P\+T\+O\+\_\+\+A\+P\+I\+\_\+\+O\+P\+E\+N\+S\+S\+L
\item {\ttfamily libssl-\/dev} or {\ttfamily openssl-\/devel} \#endif
\end{DoxyItemize}

\subsection*{How to compile}

The following compile variants are available\+:


\begin{DoxyEnumerate}
\item crypto\+\_\+gcrypt
\item crypto\+\_\+openssl
\end{DoxyEnumerate}

Add \char`\"{}crypto\char`\"{} and the variants, that you want (you can add one of them or all), to the {\ttfamily P\+L\+U\+G\+I\+N\+S} variable in {\ttfamily C\+Make\+Cache.\+txt} and re-\/run {\ttfamily cmake}.

In order to add all compile variants you can add \char`\"{}\+C\+R\+Y\+P\+T\+O\char`\"{} to the {\ttfamily P\+L\+U\+G\+I\+N\+S} variable.

An example {\ttfamily C\+Make\+Cache.\+txt} may contain the following variable\+: \begin{DoxyVerb}PLUGINS=crypto;crypto_gcrypt;crypto_openssl
\end{DoxyVerb}


or it may look like\+: \begin{DoxyVerb}PLUGINS=CRYPTO
\end{DoxyVerb}


\subsubsection*{Manual Library Setup}

If you have a custom built Open\+S\+S\+L or libgcrypt on your system, you can tell C\+Make to use those by setting the following C\+Make variables.

For a custom Open\+S\+S\+L location set\+:


\begin{DoxyItemize}
\item {\itshape O\+P\+E\+N\+S\+S\+L\+\_\+\+I\+N\+C\+L\+U\+D\+E\+\_\+\+D\+I\+R} to the library's header files
\item {\itshape O\+P\+E\+N\+S\+S\+L\+\_\+\+L\+I\+B\+R\+A\+R\+I\+E\+S} to the library's binary file
\end{DoxyItemize}

For a custom libgcrypt location set\+:


\begin{DoxyItemize}
\item {\itshape L\+I\+B\+G\+C\+R\+Y\+P\+T\+\_\+\+I\+N\+C\+L\+U\+D\+E\+\_\+\+D\+I\+R} to the library's header files
\item {\itshape L\+I\+B\+G\+C\+R\+Y\+P\+T\+\_\+\+L\+I\+B\+R\+A\+R\+I\+E\+S} to the library's binary file
\end{DoxyItemize}

\subsubsection*{Mac O\+S X}

Both variants of the plugin compile under Mac O\+S X \char`\"{}\+El Capitan\char`\"{} (Version 10.\+11.\+3 (15\+D21)).

For the {\ttfamily crypto\+\_\+gcrypt} variant download and install either \href{https://www.macports.org/}{\tt Mac\+Ports} or \href{http://brew.sh/}{\tt Homebrew}. Use one of those tools to download and install {\ttfamily libgcrypt}. If you choose Mac\+Ports, you can set the C\+Make variables like this\+:


\begin{DoxyItemize}
\item {\itshape L\+I\+B\+G\+C\+R\+Y\+P\+T\+\_\+\+I\+N\+C\+L\+U\+D\+E\+\_\+\+D\+I\+R} to {\ttfamily /opt/local/include/}
\item {\itshape L\+I\+B\+G\+C\+R\+Y\+P\+T\+\_\+\+L\+I\+B\+R\+A\+R\+I\+E\+S} to {\ttfamily /opt/local/lib/libgcrypt.dylib}
\end{DoxyItemize}

The C\+Make command might look something like\+: \begin{DoxyVerb}    cmake -DLIBGCRYPT_INCLUDE_DIR="/opt/local/include/" -DLIBGCRYPT_LIBRARIES="/opt/local/lib/libgcrypt.dylib" -DPLUGINS="crypto;crypto_gcrypt;" /path_to_elektra_src
\end{DoxyVerb}


For the {\ttfamily crypto\+\_\+openssl} variant a custom-\/built Open\+S\+S\+L library is neccessary as the Mac\+Ports or Homebrew variants do not seem to work. Download the latest version of the Open\+S\+S\+L library from the \href{https://www.openssl.org/source/}{\tt project homepage} and compile it. Copy the header files and the binary files to a location where all users can access them.

Set the C\+Make variables {\ttfamily O\+P\+E\+N\+S\+S\+L\+\_\+\+I\+N\+C\+L\+U\+D\+E\+\_\+\+D\+I\+R} and {\ttfamily O\+P\+E\+N\+S\+S\+L\+\_\+\+L\+I\+B\+R\+A\+R\+I\+E\+S} to your desired location.

\subsection*{Restrictions}

The crypto plugin will encrypt and decrypt values using A\+E\+S-\/256 in C\+B\+C mode.

The key derivation is still W\+I\+P.

\subsubsection*{Planned Features}


\begin{DoxyItemize}
\item Encryption of values
\item Decryption of values
\item Key derivation by metadata (password provided within a meta-\/key)
\item Key derivation by using a specified key-\/file (like the S\+S\+H client does)
\item Key derivation by utilizing the pgp-\/agent
\end{DoxyItemize}

The encryption and decryption of values is a straight forward process, once the key and I\+V are supplied. The key-\/derivation process in a library is a bit tricky.

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 P\+G\+P agent, etc.

The following example configuration illustrates this concept\+: \begin{DoxyVerb}    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
\end{DoxyVerb}


Only keys marked with a certain meta-\/key will be considered for encryption/decryption.

\subsection*{Examples}

\subsubsection*{Metadata based encyption}

You specify the parameters of the cryptographic operations in a Key\+Set together with the keys to be encrypted. The following parameters are required\+:


\begin{DoxyItemize}
\item {\bfseries Key} -\/ the symmetric cryptographic key for encryption
\item {\bfseries I\+V} -\/ the initialization vector (I\+V) that is required by the C\+B\+C mode
\end{DoxyItemize}

The following keys are required for metadata based encryption\+: \begin{DoxyVerb}    /elektra/modules/crypto/key
    /elektra/modules/crypto/iv
\end{DoxyVerb}


You can use the following meta-\/key to mark a key for encryption\+: \begin{DoxyVerb}    crypto/encrypt
\end{DoxyVerb}


If this meta-\/key has a value with a string-\/length greater than 0 ({\ttfamily strlen() $>$ 0}) then the crypto-\/plugin will try to encrypt it. 