\subsection*{Issue}

The crypto plugin applies cryptographic operations to Keys and Key\+Sets. In order to do that it needs keys and initialization vectors (I\+V). The problem is how to retrieve or derivate those keys in a safe way and how to pass them on to the underlying crypto libraries (Open\+S\+S\+L and libgcrypt at the time of writing).

\subsection*{Constraints}

The solution must be reasonable to the user (not just experimental setups).

The key handling should follow best practises when dealing with cryptographic operations, thus\+:


\begin{DoxyItemize}
\item the combination of key and I\+V must not be used twice for symmetric encryption
\item the key and I\+V material must be as random as possible (using an S\+N\+R\+G)
\item the key is not exposed to other Elektra modules or the user
\end{DoxyItemize}

\subsection*{Assumptions}


\begin{DoxyItemize}
\item The user knows or is willing to learn how to use G\+P\+G.
\item The user is willing to configure {\ttfamily pinentry} on her system, as it does not always run out of the box (depending on the distribution)
\item The user knows how to create and identify an asymmetric key pair using {\ttfamily gpg}
\end{DoxyItemize}

\subsection*{Considered Alternatives}

We considered passing the key and I\+V in form of plugin configuration and meta-\/keys, but this approach possibly exposes the key to other modules. Thus our constraints are violated.

Also we considered using the gpg-\/agent (or pcscd, which uses a similar protocol) for providing asymmetric cryptographic operations. The problem with gpg-\/agent is that it only provides operations which require the private part of the key-\/pair (i.\+e. signing and decrypting). We would still have to implement the counterpart operations (i.\+e. verifying and encrypting) on our own. Starting the gpg-\/agent and the whole interprocess communication is either tedious work (when implemented by oneself) or adds another dependency (when using libassuan). So we do not consider the gpg-\/agent to be a viable option.

\subsection*{Decision}

\subsubsection*{General Approach}

The introduction of a G\+P\+G interface enables the user to utilize her existing key-\/pairs for cryptographic operations in Elektra. The private key is used for encrypting a random sequence, which serves as seed for a key derivation function (K\+D\+F). This way we can safely derivate cryptographic keys for symmetric value encryption. Both Open\+S\+S\+L and libgcrypt have built-\/in support for the P\+B\+K\+D\+F2 (see R\+F\+C 2898).

The P\+B\+K\+D\+F2 needs an iteration number and a salt in order to work. Those values will be stored per Key as Meta\+Key.

\subsubsection*{Implementation Details}

During the {\bfseries mount phase} a random master password {\itshape r} is being generated. {\itshape r} is sent to the gpg binary for encryption. The resulting encrypted master password {\itshape m} is stored in the plugin configuration at {\ttfamily config/master\+Challenge}.

During the {\bfseries set phase} the master password {\itshape m} is sent to the gpg binary for decryption in order to retrieve {\itshape r}. The following steps will be repeated for every Key {\itshape k}, that is supposed to be encrypted. A random salt {\itshape s(k)} is generated. By applying the P\+B\+K\+D\+F2 (mentioned earlier) with {\itshape r} and {\itshape s(k)}, the cryptographic key {\itshape e(k)} and the initialization vector {\itshape i(k)} is being derived. The value of {\itshape k} will be encrypted using {\itshape e(k)} and {\itshape i(k)}. The seed {\itshape s(k)} will be encoded as prefix into the encrypted value.

During the {\bfseries get phase} the master password {\itshape m} is sent to the gpg binary for decryption in order to retrieve {\itshape r}. The following steps will be repeated for every Key {\itshape k}, that is supposed to be decrypted. The salt {\itshape s(k)} is read from the encrypted message. By applying the P\+B\+K\+D\+F2 with {\itshape r} and {\itshape s(k)} the values of {\itshape e(k)} and {\itshape i(k)} are restored. Then the encrypted message can be decrypted.

\subsection*{Argument}

The solution is reasonable to all users who are in favor of G\+P\+G. Also the solution might lead to a decline in dependencies (i.\+e. all cryptographic operations could be handled by the gpg binary).

The constraints considering the key handling are met.

\subsection*{Implications}

To manipulate the plugin configuration during the {\bfseries mount phase} a hook is required within the {\ttfamily Backend\+Builder}. See pull request \href{https://github.com/ElektraInitiative/libelektra/pull/733}{\tt \#733} for full discussion.

\subsection*{Related decisions}

\subsection*{Notes}