\hypertarget{doc_decisions_cryptograhic_key_handling_md_autotoc_md1095}{}\doxysection{Problem}\label{doc_decisions_cryptograhic_key_handling_md_autotoc_md1095}
The crypto plugin applies cryptographic operations to Keys and Key\+Sets. In order to do that it needs keys and initialization vectors (IV). 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\+SL and libgcrypt at the time of writing).\hypertarget{doc_decisions_cryptograhic_key_handling_md_autotoc_md1096}{}\doxysection{Constraints}\label{doc_decisions_cryptograhic_key_handling_md_autotoc_md1096}
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 IV must not be used twice for symmetric encryption
\item the key and IV material must be as random as possible (using an S\+N\+RG)
\item the key is not exposed to other Elektra modules or the user
\end{DoxyItemize}\hypertarget{doc_decisions_cryptograhic_key_handling_md_autotoc_md1097}{}\doxysection{Assumptions}\label{doc_decisions_cryptograhic_key_handling_md_autotoc_md1097}

\begin{DoxyItemize}
\item The user knows or is willing to learn how to use G\+PG.
\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}\hypertarget{doc_decisions_cryptograhic_key_handling_md_autotoc_md1098}{}\doxysection{Considered Alternatives}\label{doc_decisions_cryptograhic_key_handling_md_autotoc_md1098}
We considered passing the key and IV in form of plugin configuration and metakeys, 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.\hypertarget{doc_decisions_cryptograhic_key_handling_md_autotoc_md1099}{}\doxysection{Decision}\label{doc_decisions_cryptograhic_key_handling_md_autotoc_md1099}
\hypertarget{doc_decisions_cryptograhic_key_handling_md_autotoc_md1100}{}\doxysubsection{General Approach}\label{doc_decisions_cryptograhic_key_handling_md_autotoc_md1100}
The introduction of a G\+PG 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\+DF). This way we can safely derivate cryptographic keys for symmetric value encryption. Both Open\+S\+SL and libgcrypt have built-\/in support for the P\+B\+K\+D\+F2 (see R\+FC 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.\hypertarget{doc_decisions_cryptograhic_key_handling_md_autotoc_md1101}{}\doxysubsection{Implementation Details}\label{doc_decisions_cryptograhic_key_handling_md_autotoc_md1101}
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.\hypertarget{doc_decisions_cryptograhic_key_handling_md_autotoc_md1102}{}\doxysection{Rationale}\label{doc_decisions_cryptograhic_key_handling_md_autotoc_md1102}
The solution is reasonable to all users who are in favor of G\+PG. 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.\hypertarget{doc_decisions_cryptograhic_key_handling_md_autotoc_md1103}{}\doxysection{Implications}\label{doc_decisions_cryptograhic_key_handling_md_autotoc_md1103}
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}{\texttt{ \#733}} for full discussion.\hypertarget{doc_decisions_cryptograhic_key_handling_md_autotoc_md1104}{}\doxysection{Related Decisions}\label{doc_decisions_cryptograhic_key_handling_md_autotoc_md1104}
\hypertarget{doc_decisions_cryptograhic_key_handling_md_autotoc_md1105}{}\doxysection{Notes}\label{doc_decisions_cryptograhic_key_handling_md_autotoc_md1105}
