From 9e694994681b0b2861553d0a50bca6623b546dd2 Mon Sep 17 00:00:00 2001 From: Gian Demarmels Date: Mon, 14 Feb 2022 00:03:06 +0100 Subject: CS thesis --- doc/cs/content/4_2_specification.tex | 790 +++++++++++++++++++++++++++++++++++ 1 file changed, 790 insertions(+) create mode 100644 doc/cs/content/4_2_specification.tex (limited to 'doc/cs/content/4_2_specification.tex') diff --git a/doc/cs/content/4_2_specification.tex b/doc/cs/content/4_2_specification.tex new file mode 100644 index 000000000..efe6a3c3d --- /dev/null +++ b/doc/cs/content/4_2_specification.tex @@ -0,0 +1,790 @@ +\chapter{Protocol Specification} +\label{chap:spec} +The proposed Taler protocols using the Clause Blind Schnorr Signature Scheme will be implemented as an additional option besides the existing \gls{RSABS} variant of the protocol as suggested by Christian Grothoff. +A Taler Exchange operator should be able to configure whether he wants to use \gls{RSABS} or \gls{CSBS}. +\\This variant allows to choose the signature scheme globally or per denomination. +Furthermore, it allows a change of signature scheme in a non-breaking way by revoking (or letting expire) a denomination and offering new denominations with the other scheme. +\\ +The following key points are specified in this chapter: +\begin{itemize} + \item Architecture of the different components + \item Explain and specify needed changes + \item Data strucutures + \item Public \acp{API} + \item Persistence + \item Used libraries +\end{itemize} + +\section{Architecture} +Before specifying the implementation of the different protocols, a deeper understanding of the technical architecture of Talers components is needed. +this section introduces the architecture of the exchange and wallet components and explains where the needed changes need to be implemented on a high-level. + +\subsection{Exchange} +An introduction to the exchange can be found in section \ref{sec:exchange}. +An exchange operator needs to run and maintain some additional services besides Taler's exchange. +Although this is not directly relevant for the implementation, it helps to better understand the environment in which the exchange runs. +The perspective of an exchange operator can be seen in figure \ref{fig:taler:exchange-operator-architecture}. + +\begin{figure}[h!] + \begin{adjustbox}{max totalsize={.9\textwidth}{.7\textheight},center} + \begin{tikzpicture} + \tikzstyle{def} = [node distance= 5em and 6.5em, inner sep=1em, outer sep=.3em]; + \node (origin) at (0,0) {}; + \node (exchange) [def,above=of origin,draw]{Exchange}; + \node (nexus) [def, draw, below right=of exchange] {Nexus}; + \node (corebanking) [def, draw, below left=of nexus] {Core Banking}; + \node (nginx) [def, draw, above=of exchange]{Nginx}; + \node (postgres) [def, draw, below left=of exchange]{Postgres}; + \node (postgres-nexus) [def, draw, below right=of nexus]{Postgres}; + + \tikzstyle{C} = [color=black, line width=1pt] + + \draw [<-, C] (exchange) -- (nginx) node [midway, above, sloped] (TextNode) {REST API}; + \draw [<-, C] (postgres) -- (exchange) node [midway, above, sloped] (TextNode) {SQL}; + \draw [<-, C] (postgres-nexus) -- (nexus) node [midway, above, sloped] (TextNode) {SQL}; + \draw [<-, C] (nexus) -- (exchange) node [midway, above, sloped] (TextNode) {Internal REST API}; + \draw [<-, C] (corebanking) -- (nexus) node [midway, above, sloped] (TextNode) {EBICS/FinTS}; + + \end{tikzpicture} + \end{adjustbox} + \caption{Taler exchange operator architecture (source: \cite{taler-presentation})} + \label{fig:taler:exchange-operator-architecture} +\end{figure} + +The software architecture of the exchange can be seen in figure \ref{fig:taler:exchange-architecture}. +The API runs under the httpd service, where the API endpoints need to be adjusted/added to incorporate the changes of this thesis. +The httpd server has no access to the private keys of the denomination and online signing keys. +Only the corresponding security module can perform operations requiring the private key. +Further the keys are also managed by these security modules. +To support \gls{CSBS} a new security module, which performs signature operations, is added. +To persist the new data structures, the postgres helpers need to be adjusted to serialize/deserialize the new \gls{CSBS} data structures. +More details on what changes are needed in these places is discussed in the following sections. + +\begin{figure}[h!] + \begin{center} + \begin{tikzpicture} + \tikzstyle{def} = [node distance=2em and 2.5em, inner sep=1em, outer sep=.3em]; + \node (origin) at (0,0) {}; + \node [blue] (httpd) [def,above=of origin,draw]{httpd}; + \node (secmod-rsa) [def, draw, right=of httpd] {secmod-rsa}; + \node (secmod-eddsa) [def, draw, left=of httpd] {secmod-eddsa}; + \node [blue](postgres) [def, draw, below=of httpd]{Postgres}; + \node [mGreen] (secmod-cs) [def, draw, left=of postgres]{secmod-cs}; + \node (aggregator) [def, draw, right=of postgres]{aggregator}; + \node (transfer) [def, draw, below left=of postgres]{transfer}; + \node (wirewatch) [def, draw, below right=of postgres]{wirewatch}; + \node (nexus) [def, draw, below=of postgres]{Nexus}; + + \tikzstyle{C} = [color=black, line width=1pt] + + \draw [<->, C] (httpd) -- (postgres) node [midway, above, sloped] (TextNode) {}; + \draw [<->, C] (httpd) -- (secmod-rsa) node [midway, above, sloped] (TextNode) {}; + \draw [<->, C] (httpd) -- (secmod-eddsa) node [midway, above, sloped] (TextNode) {}; + \draw [<->, C] (httpd) -- (secmod-cs) node [midway, above, sloped] (TextNode) {}; + \draw [<->, C] (aggregator) -- (postgres) node [midway, above, sloped] (TextNode) {}; + \draw [<->, C] (wirewatch) -- (postgres) node [midway, above, sloped] (TextNode) {}; + \draw [<->, C] (transfer) -- (postgres) node [midway, above, sloped] (TextNode) {}; + \draw [->, C] (transfer) -- (nexus) node [midway, above, sloped] (TextNode) {}; + \draw [<-, C] (wirewatch) -- (nexus) node [midway, above, sloped] (TextNode) {}; + \end{tikzpicture} + \end{center} + \caption{Taler exchange architecture (source: \cite{taler-presentation})} + \label{fig:taler:exchange-architecture} +\end{figure} + +\subsection{Wallet} +The architecture of the wallet implementation (as seen in figure \ref{fig:taler:wallet-architecture}) is quite straightforward. +To add support for \gls{CSBS} in the wallet, the cryptographic routines need to be reimplemented in Typescript. +Taler uses tweetnacl \cite{bern:tweetnacl} which provides functionality for the group operations. +There are existing \gls{hkdf} and \gls{fdh} implementations, that can be reused.\\ +Furthermore, the Taler protocols need to be adjusted to support \gls{CSBS} in the wallet-core. + +\begin{figure}[h!] + \begin{center} + \begin{tikzpicture} + \tikzstyle{def} = [node distance= 5em and 4.5em, inner sep=1em, outer sep=.3em]; + \node (origin) at (0,0) {}; + \node (gui) [def,above=of origin,draw]{wallet-gui}; + \node [blue](core) [def,below=of gui,draw]{wallet-core}; + \node (sync) [def, draw, below left=of core] {Sync}; + \node (taler) [def, draw, below right=of core] {Taler}; + \node (anastasis) [def, draw, below=of core] {Anastasis}; + + \tikzstyle{C} = [color=black, line width=1pt] + \draw [<->, C] (gui) -- (core) node [midway, above, sloped] (TextNode) {}; + \draw [<->, C] (core) -- (sync) node [midway, above, sloped] (TextNode) {Backup}; + \draw [<->, C] (core) -- (taler) node [midway, above, sloped] (TextNode) {Payment}; + \draw [<->, C] (core) -- (anastasis) node [midway, above, sloped] (TextNode) {Key Escrow}; + \end{tikzpicture} + \end{center} + \caption{Taler wallet architecture (source: \cite{taler-presentation})} + \label{fig:taler:wallet-architecture} +\end{figure} + +\section{Persistence} +The Clause Blind Schnorr Signature scheme is quite different to \gls{RSABS}. +Despite the differences, the database model does not need to be changed. +The only change needed an additional type field, specifying whether RSA or CS is used as signature algorithm. +To persist the new structs introduced with the support for \gls{CSBS}, only the postgres helpers need to support serialization and deserialization of the new structs. + +\section{Testing} +We will partially use test-driven development, meaning that we will write tests (at least for the known good case) before implementing functions, and extend them during and after development. +This allows us to check the functionality (code section, function(s)) during development, while being able to extend testing whenever we identify new test cases during development. + +Test cases can be used to verify different aspects of a functionality. +These are the ones we will focus on. +\begin{itemize} + \item \textbf{Known good}: + Known good cases test whether a functionality works as expected. + They are the most useful during development, because they indicate whether the code is working as expected. + \item \textbf{Known Bad}: + Known bad cases test whether functionality that is known not to work behaves as expected. + \item \textbf{Determinism}: + This case type checks whether the same input leads to the same output. + It is important for code that must work deterministic (same output), non-deterministic (e.g. random output) or based on a state that impacts the functionality. + \item \textbf{Performance testing}: + Performance testing is used to gather timing information that can be used to identify functionality with long duration, or to compare performance between different implementations or major changes. + We will restrict performance testing to the comparison of the Blind RSA Signature Scheme and the Clause Blind Schnorr Signature Scheme. +\end{itemize} + + +\section{Signature Scheme Operations in GNUnet} +\label{sec:specification-signature-scheme} + +The signature scheme operations implemented are needed in all other parts of the implementation. +Taler's cryptographic primitives (e.g. \gls{RSABS}, \gls{hkdf}, hash functions) are mostly implemented in GNUnet utils, therefore the Clause Blind Schnorr Signature routines will be implemented in GNUnet too. +It is important to provide a clear API for the cryptographic routines and to test them thoroughly. +Libsodium will be used for finite field arithmetic (\cite{libsodium:finite-field-arithmetic}) and for other functionality when available (e.g. for key generation). +Thus, a widely used and well tested cryptographic library is used for group operations. + +For \acl{FDH} and \gls{hkdf} existing implementations provided by GNUnet are used. +The \gls{hkdf} is used with SHA-512 for the extraction phase and SHA-256 for the expansion phase. + +\subsection{Data Structures} +Libsodium represents Ed25519 points and scalars as 32-byte char arrays. +To provide a more user-friendly \ac{API}, structs were created to represent each type. +For example \texttt{struct GNUNET\_CRYPTO\_CsPrivateKey} or \texttt{struct GNUNET\_CRYPTO\_RSecret} +The main reason is to increase readability and to prevent misusage of the \ac{API}. +Unlike RSA, our \gls{CSBS} on Ed25519 data structures have a fixed sizes. +The different data structures can be found in table \ref{tab:datastruct-crypto}. + +\begin{table}[ht] + \centering + \resizebox{0.95\textwidth}{!}{\begin{minipage}{\textwidth} + \colorlet{BFH-table}{BFH-MediumBlue!10} + \colorlet{BFH-tablehead}{BFH-MediumBlue!50} + \setupBfhTabular + \begin{tabular}{lll} + \rowcolor{BFH-tablehead} + \textbf{Values} & \textbf{Data Structure} & \textbf{Data Type} \\\hline + Curve25519 Scalar & {\small GNUNET\_CRYPTO\_Cs25519Scalar} & 32 byte char array\\\hline + Curve25519 Point & {\small GNUNET\_CRYPTO\_Cs25519Point} & 32 byte char array\\\hline + Private Key & {\small GNUNET\_CRYPTO\_CsPrivateKey} & {\small GNUNET\_CRYPTO\_Cs25519Scalar}\\\hline + Public Key & {\small GNUNET\_CRYPTO\_CsPublicKey} & {\small GNUNET\_CRYPTO\_Cs25519Point}\\\hline + $\alpha, \beta$ & {\small GNUNET\_CRYPTO\_CsBlindingSecret} & {\footnotesize 2x GNUNET\_CRYPTO\_Cs25519Scalar}\\\hline + $r$ & {\small GNUNET\_CRYPTO\_CsRSecret} & {\small GNUNET\_CRYPTO\_Cs25519Scalar}\\\hline + $R$ & {\small GNUNET\_CRYPTO\_CsRPublic} & {\small GNUNET\_CRYPTO\_Cs25519Point}\\\hline + $c$ & {\small GNUNET\_CRYPTO\_CsC} & {\small GNUNET\_CRYPTO\_Cs25519Scalar}\\\hline + $s$ & {\small GNUNET\_CRYPTO\_CsBlindS} & {\small GNUNET\_CRYPTO\_Cs25519Scalar}\\\hline + $s'$ & {\small GNUNET\_CRYPTO\_CsS} & {\small GNUNET\_CRYPTO\_Cs25519Scalar}\\\hline + $\sigma := \langle s',R' \rangle$ & {\small GNUNET\_CRYPTO\_CsSignature} & {\small GNUNET\_CRYPTO\_Cs25519Scalar}\\ + & & {\small GNUNET\_CRYPTO\_Cs25519Point}\\\hline + Nonce & {\small GNUNET\_CRYPTO\_CsNonce} & 32 byte char array\\\hline + \end{tabular} + \caption{Data structures for cryptographic routines} + \label{tab:datastruct-crypto} +\end{minipage}} +\end{table} + + + +\subsection{Library API} +The public \ac{API} and related data structures are specified in the C header file \url{src/include/gnunet_crypto_lib.h} in the GNUnet repository \cite{gnunet-git}. +It was developed in multiple iterations based on feedback from Christian Grothoff. +The complete C header \ac{API} can be found in the repository. +This section provides an overview of the implemented crypto API. + +Some design decisions need to be explained further: +\begin{itemize} + \item In order to prevent misusage of our implementation and increase readability, the functions that represent different stages in the signature scheme takes different data types as in- and output. + Internally most variables are either scalars or curve points (except for nonces, secrets and messages). + \item Operations that are performed twice in the Clause Blind Schnorr Signature Scheme (e.g. derivation of $ r $) do not have to be called twice. + Instead, the API returns an array of two instead of a single value.\\ + For these functions, we also optimized the \gls{hkdf} (as proposed by Christian Grothoff). + Instead of calling \gls{hkdf} twice (with different salts, e.g. "r0" and "r1"), we call it one time (e.g. with salt "r") and double the output length. + \item The cryptographic hash function used to derive $ c' $ (hash of $ R' $ and message) must map the results into the main subgroup for scalars, meaning that it has to be a \gls{fdh} (see \ref{sec:rsa-fdh}). +\end{itemize} + +The following API examples should provide an overview on how the API works and how to use it. + +First of all the API must provide functionality to create a \gls{25519} keypair as in listing \ref{lst:crypto-keypair-api} + +\begin{lstlisting}[style=bfh-c,language=C, caption={GNUnet create keypair API}, label={lst:crypto-keypair-api}] +/** + * Create a new random private key. + * + * @param[out] priv where to write the fresh private key + */ +void +GNUNET_CRYPTO_cs_private_key_generate ( + struct GNUNET_CRYPTO_CsPrivateKey *priv); + + +/** + * Extract the public key of the given private key. + * + * @param priv the private key + * @param[out] pub where to write the public key + */ +void +GNUNET_CRYPTO_cs_private_key_get_public ( + const struct GNUNET_CRYPTO_CsPrivateKey *priv, + struct GNUNET_CRYPTO_CsPublicKey *pub); +\end{lstlisting} + +The signer needs an API to generate his secret $r$ and calculate his public point $R$. +As specified in the redesign of the protocols, the r must not be chosen randomly because we need to provide \textit{\gls{abort-idempotency}}. However, the secret $r$ still needs to be \textit{unpredictable} and look random to the client. +The r\_derive API derives such a secret $r$ from a nonce and a long-term secret with \gls{hkdf}. +Further, the API ensures that a caller must generate two secret $r$ as in the Clause Blind Schnorr Signature scheme. This should discourage people from using the unsecure Blind Schnorr Signature scheme. See \ref{lst:crypto-rderive-api}. + + +\begin{lstlisting}[style=bfh-c,language=C, caption={GNUnet r derive API}, label={lst:crypto-rderive-api}] + /** + * Derive a new secret r pair r0 and r1. + * In original papers r is generated randomly + * To provide abort-idempotency, r needs to be derived but still needs to be UNPREDICTABLE + * To ensure unpredictability a new nonce should be used when a new r needs to be derived. + * Uses HKDF internally. + * Comment: Can be done in one HKDF shot and split output. + * + * @param nonce is a random nonce + * @param lts is a long-term-secret in form of a private key + * @param[out] r array containing derived secrets r0 and r1 + */ + void + GNUNET_CRYPTO_cs_r_derive (const struct GNUNET_CRYPTO_CsNonce *nonce, + const struct GNUNET_CRYPTO_CsPrivateKey *lts, + struct GNUNET_CRYPTO_CsRSecret r[2]); + + +/** + * Extract the public R of the given secret r. + * + * @param r_priv the private key + * @param[out] r_pub where to write the public key + */ + void + GNUNET_CRYPTO_cs_r_get_public (const struct GNUNET_CRYPTO_CsRSecret *r_priv, + struct GNUNET_CRYPTO_CsRPublic *r_pub); +\end{lstlisting} + + +Same as the r\_derive, the blinding secrets are also derived and not generated randomly. +The blinding secrets are generated by a client who provides a secret as seed to derive the secrets from as in listing \ref{lst:crypto-blinding-secrets-api}. + +\begin{lstlisting}[style=bfh-c,language=C, caption={GNUnet blinding secrets derive API}, label={lst:crypto-blinding-secrets-api}] +/** + * Derives new random blinding factors. + * In original papers blinding factors are generated randomly + * To provide abort-idempotency, blinding factors need to be derived but still need to be UNPREDICTABLE + * To ensure unpredictability a new nonce has to be used. + * Uses HKDF internally + * + * @param secret is secret to derive blinding factors + * @param secret_len secret length + * @param[out] bs array containing the two derivedGNUNET_CRYPTO_CsBlindingSecret + */ +void +GNUNET_CRYPTO_cs_blinding_secrets_derive ( + const struct GNUNET_CRYPTO_CsNonce *blind_seed, + struct GNUNET_CRYPTO_CsBlindingSecret bs[2]); +\end{lstlisting} + +Further the Clause Blind Schnorr API provides an API to calculate the two blinded c of the message with the two public $R$, the blinding factors and the public key as in listing \ref{lst:crypto-calc-c-api}. + +\begin{lstlisting}[style=bfh-c,language=C, caption={GNUnet calculate blinded c API}, label={lst:crypto-calc-c-api}] +/** + * Calculate two blinded c's + * Comment: One would be insecure due to Wagner's algorithm solving ROS + * + * @param bs array of the two blinding factor structs each containing alpha and beta + * @param r_pub array of the two signer's nonce R + * @param pub the public key of the signer + * @param msg the message to blind in preparation for signing + * @param msg_len length of message msg + * @param[out] blinded_c array of the two blinded c's + */ +void +GNUNET_CRYPTO_cs_calc_blinded_c ( + const struct GNUNET_CRYPTO_CsBlindingSecret bs[2], + const struct GNUNET_CRYPTO_CsRPublic r_pub[2], + const struct GNUNET_CRYPTO_CsPublicKey *pub, + const void *msg, + size_t msg_len, + struct GNUNET_CRYPTO_CsC blinded_c[2]); +\end{lstlisting} + +The sign function in our API is called sign\_derive, since we derive $b \in \{0,1\}$ from the long-term secret and then calculate the signature scalar of $c_b$. +See listing \ref{lst:crypto-sign-api}. + +\begin{lstlisting}[style=bfh-c,language=C, caption={GNUnet sign API}, label={lst:crypto-sign-api}] +/** + * Sign a blinded c + * This function derives b from a nonce and a longterm secret + * In original papers b is generated randomly + * To provide abort-idempotency, b needs to be derived but still need to be UNPREDICTABLE. + * To ensure unpredictability a new nonce has to be used for every signature + * HKDF is used internally for derivation + * r0 and r1 can be derived prior by using GNUNET_CRYPTO_cs_r_derive + * + * @param priv private key to use for the signing and as LTS in HKDF + * @param r array of the two secret nonce from the signer + * @param c array of the two blinded c to sign c_b + * @param nonce is a random nonce + * @param[out] blinded_signature_scalar where to write the signature + * @return 0 or 1 for b (see Clause Blind Signature Scheme) + */ +int +GNUNET_CRYPTO_cs_sign_derive( + const struct GNUNET_CRYPTO_CsPrivateKey *priv, + const struct GNUNET_CRYPTO_CsRSecret r[2], + const struct GNUNET_CRYPTO_CsC c[2], + const struct GNUNET_CRYPTO_CsNonce *nonce, + struct GNUNET_CRYPTO_CsBlindS *blinded_signature_scalar); +\end{lstlisting} + +The API for the unblind operation can be called with the blinding secrets and the signature scalar received from the signer as in listing \ref{lst:crypto-unblind-api}. + +\begin{lstlisting}[style=bfh-c,language=C, caption={GNUnet unblind API}, label={lst:crypto-unblind-api}] + /** + * Unblind a blind-signed signature using a c that was blinded + * + * @param blinded_signature_scalar the signature made on the blinded c + * @param bs the blinding factors used in the blinding + * @param[out] signature_scalar where to write the unblinded signature + */ +void +GNUNET_CRYPTO_cs_unblind ( + const struct GNUNET_CRYPTO_CsBlindS *blinded_signature_scalar, + const struct GNUNET_CRYPTO_CsBlindingSecret *bs, + struct GNUNET_CRYPTO_CsS *signature_scalar); +\end{lstlisting} + +The verify API takes the message and its signature with the public key and returns GNUNET\_OK for a valid signature and GNUNET\_SYSERR otherwhise. +See listing \ref{lst:crypto-verify-api}. + +\begin{lstlisting}[style=bfh-c,language=C,, caption={GNUnet verify API}, label={lst:crypto-verify-api}] + /** + * Verify whether the given message corresponds to the given signature and the + * signature is valid with respect to the given public key. + * + * @param sig signature that is being validated + * @param pub public key of the signer + * @param msg is the message that should be signed by @a sig (message is used to calculate c) + * @param msg_len is the message length + * @returns #GNUNET_YES on success, #GNUNET_SYSERR if signature invalid + */ + enum GNUNET_GenericReturnValue + GNUNET_CRYPTO_cs_verify (const struct GNUNET_CRYPTO_CsSignature *sig, + const struct GNUNET_CRYPTO_CsPublicKey *pub, + const void *msg, + size_t msg_len); +\end{lstlisting} + +\subsection{Testing} +For digital signature schemes, the most important test case is the \textit{known good} case where a signature is created and successfully validated. +This test case already tests very much in a digital signature scheme. +When the signature creation or verification has a bug, a test will not succeed, because the mathematic operations need to be correct to be validated correctly. + +The cryptographic operations are further tested for deterministicy (where it applies), meaning that multiple function calls with the same input must lead to the same output. + +Since libsodium is used for the finite field arithmetic operations and is a well tested library, many cryptographic tests are already done in libsodium. + +The performance is measured in a benchmark to see how performant \gls{CSBS} are in comparison to the RSA Blind Signature Scheme. + +\section{Taler Cryptographic Utilities} +Taler provides utility functions to support cryptographic operations.\\ +This chapter provides an overview of these utility functions and about the functionality they provide. + +\subsection{Planchet Creation} +In crypto.c many utility functions are provided to create planchets (for planchet details see \ref{fig:coin:states}), blinding secrets and much more. +One difference between \gls{RSABS} and \gls{CSBS} is, that the coin private key and RSA blinding secret can be created at the same point in time, since the RSA blinding secret is created randomly. +However, for Clause Blind Schnorr secrets an additional step is needed, the public $R_0$ and $R_1$ are required to calculate the blinding seed to derive the secrets. + +A planchet in the Clause Blind Schnorr Signature Scheme can be created as followed (implementation details ommited). + +\begin{enumerate} + \item Create planchet with new \ac{EdDSA} private key + \item Derive withdraw nonce + \item Request public $R_0, R_1$ from signer + \item Derive blinding seed + \item Prepare (blind) the planchet +\end{enumerate} + +After the planchet is created, it is sent to the exchange to be signed. + +\subsection{Taler CS Security Module} +The exchange segregates access to the private keys with separate security module processes. +The security module has sole access to the private keys of the online signing keys and thus, only a security module can create signatures. +The different \textit{taler-exchange-secmod} processes (separated by signature scheme) are managing the exchanges online signing keys. The RSA denomination keys for example are managed with \textit{taler-exchange-secmod-rsa}. + +Now a new \textit{taler-exchange-secmod-cs} needs to be created for managing the \gls{CSBS} denomination keys. +These security modules run on the same machine as the httpd process and they use UNIX Domain Sockets as method for \acl{IPC}. +A short introduction about UNIX Domain Sockets can be found in the blog post \cite{matt:unix-domain-sockets}. +Furthermore, the security modules are used to protect the online signing keys by performing the actual signing operations in the dedicated taler-secmod-cs process. +This abstraction makes it harder for an attacker who has already compromised the http daemon to gain access to the private keys. +However, such an attacker would still be able to sign arbitrary messages (see \cite{taler-documentation:exchange-operator-manual}). +A crypto helper exists for each security module, these functions can be called inside the exchange for operations requiring the private online signing keys. +The new Clause Schnorr security module and corresponding crypto helper provides the following functionality: +\begin{itemize} + \item Private Key Management and creation + \item Request public $R_0, R_1$ + \item Request a signature of a $c_0,c_1$ pair + \item Revoke an online signing key +\end{itemize} + +\subsection{Testing} +All of the operations have tests and are included in unit tests. +As a template for testing, the existing RSA tests were used and adjusted for \gls{CSBS}. + + +\section{Denomination Key Management} +Since we introduce a type of denomination keys, related operations like connection to the \gls{CSBS} security module, making the denominations available for customers, persisting them in the database and offline signing using the exchange's offline signature key have to be extended to incorporate the \acl{CS}. + +The exchange offline signer requests the future, not yet signed keys by calling GET \url{/management/keys} as described in table \ref{tab:management-keys-get}. \\\\ +\framebox[1.1\width]{\color{blue}\texttt{GET /management/keys}} +\begin{table}[ht] + \centering + \resizebox{0.9\textwidth}{!}{\begin{minipage}{\textwidth} + \colorlet{BFH-table}{BFH-MediumBlue!10} + \colorlet{BFH-tablehead}{BFH-MediumBlue!50} + \setupBfhTabular + \begin{tabular}{ll} + \rowcolor{BFH-tablehead} + \textbf{Field} & \textbf{Value} \\ + future\_denoms & Information about denomination keys \\ + future\_signkeys & Information about exchange online signing keys \\ + master\_pub & Exchange's master public key \\ + denom\_secmod\_public\_key & RSA security module public key \\ + denom\_secmod\_cs\_public\_key & \gls{CSBS} security module public key \\ + signkey\_secmod\_public\_key & Online singing security module public key \\ + \end{tabular} + \caption{GET \url{/management/keys} response data} + \label{tab:management-keys-get} +\end{minipage}} +\end{table} + +It then signs the keys and returns them using POST on the same \ac{URL} with the data described in table \ref{tab:management-keys-post}. \\\\ +\framebox[1.1\width]{\color{blue}\texttt{POST /management/keys}} +\begin{table}[ht] + \centering + \colorlet{BFH-table}{BFH-MediumBlue!10} + \colorlet{BFH-tablehead}{BFH-MediumBlue!50} + \setupBfhTabular + \begin{tabular}{ll} + \rowcolor{BFH-tablehead} + \textbf{Field} & \textbf{Value} \\ + denom\_sigs & Denomination key signatures \\ + signkey\_sigs & Online signing key signatures \\ + \end{tabular} + \caption{POST \url{/management/keys} response data} + \label{tab:management-keys-post} +\end{table} + +Wallets can then call GET \url{/keys} to obtain the current denominations and other information, the response is described in table \ref{tab:keys-get}. \\\\ +\framebox[1.1\width]{\color{blue}\texttt{GET /keys}} +\begin{table}[ht] + \centering + \colorlet{BFH-table}{BFH-MediumBlue!10} + \colorlet{BFH-tablehead}{BFH-MediumBlue!50} + \setupBfhTabular + \begin{tabular}{ll} + \rowcolor{BFH-tablehead} + \textbf{Field} & \textbf{Value} \\ + version & Exchange's protocol version \\ + currency & Currency \\ + master\_public\_key & Exchange's master public key \\ + reserve\_closing\_delay & Delay before reserves are closed \\ + signkeys & Exchange's online signing public keys \\ + recoup & Revoked keys \\ + denoms & List of denominations \\ + auditors & Auditors for this exchange \\ + list\_issue\_date & Timestamp \\ + eddsa\_pub & Exchange's online signing public key \\ + eddsa\_sig & Signature (use "eddsa\_pub" for verification) \\ + \end{tabular} + \caption{GET \url{/keys} response data} + \label{tab:keys-get} +\end{table} + + +\section{New Endpoint for $R$} +The withdraw and refresh protocols using the Claude Blind Schnorr Signature Scheme introduce an additional round trip. +In this round trip, the customer requests two $ R $ from the exchange. +The exchange uses a secret $ r $ to calculate $ R := rG $. +\\ +In contrast to the plain Clause Blind Schnorr Signature Scheme (see \ref{sec:clause-blind-schnorr-sig}), $ r $ isn't generated randomly but instead derived using a \gls{hkdf} with a nonce from the customer and a denomination private key (secret only known by the exchange). +This still ensures that the private $ r $ can't be anticipated, but has multiple advantages regarding \gls{abort-idempotency}. +\Gls{abort-idempotency} means that a withdraw or refresh operation can be aborted in any step and later tried again (using the same values) without yielding a different result. +The challenge for $ r, R $ regarding \gls{abort-idempotency} is to ensure that the same $ r $ is used during the complete signature creation process. + +The only drawback of this process is that we have to ensure that the same nonce and secret aren't used for different withdraw- or refresh-operations. +This is done during signature creation and will be described in the withdraw protocol section \ref{sec:specification-withdraw}. + + +\subsection{Public APIs and Data Structures} +This is a new functionality, meaning a new endpoint accessible to customers has to be introduced. +It will be made available in the exchange HTTP server under \framebox[1.1\width]{\color{blue}\texttt{POST /csr}} and will take the input parameters described in table \ref{tab:csr-request-data} (as \ac{JSON}). +\begin{table}[ht] + \centering + \resizebox{0.9\textwidth}{!}{\begin{minipage}{\textwidth} + \colorlet{BFH-table}{BFH-MediumBlue!10} + \colorlet{BFH-tablehead}{BFH-MediumBlue!50} + \setupBfhTabular + \begin{tabular}{lll} + \rowcolor{BFH-tablehead} + \textbf{Field} & \textbf{Type} & \textbf{Value} \\ + nonce & String & 32 Bytes encoded in Crockford base32 Hex \\ + denom\_pub\_hash & String & Denomination Public Key encoded in Crockford base32 Hex \\ + \end{tabular} + \caption{POST \url{/csr} request data} + \label{tab:csr-request-data} +\end{minipage}} +\end{table} + +The exchange will then check the denomination and return one of these HTTP status codes: +\begin{itemize} + \item \textbf{200 (HTTP\_OK)}: Request Successful + \item \textbf{400 (BAD\_REQUEST)}: Invalid input parameters + \item \textbf{404 (NOT\_FOUND)}: Denomination unknown or not Clause Schnorr + \item \textbf{410 (GONE)}: Denomination revoked/expired + \item \textbf{412 (PRECONDITION\_FAILED)}: Denomination not yet valid +\end{itemize} + +When the request was successful, the exchange returns the data described in table \ref{tab:csr-response-data} (as \ac{JSON}). +\begin{table}[ht] + \centering + \colorlet{BFH-table}{BFH-MediumBlue!10} + \colorlet{BFH-tablehead}{BFH-MediumBlue!50} + \setupBfhTabular + \begin{tabular}{lll} + \rowcolor{BFH-tablehead} + \textbf{Field} & \textbf{Type} & \textbf{Value} \\ + r\_pub\_0 & String & 32 Bytes encoded in Crockford base32 Hex \\ + r\_pub\_1 & String & 32 Bytes encoded in Crockford base32 Hex \\ + \end{tabular} + \caption{POST \url{/csr} response data} + \label{tab:csr-response-data} +\end{table} + + +\subsection{Persistence} +This API does not persist anything. +This is because the resulting $R_0, R_1$ are derived and can be derived in a later step. + + +\section{Withdraw Protocol} +\label{sec:specification-withdraw} +The withdraw protocol has been introduced in section \ref{sec:withdrawal}. +For the \acl{CS} necessary adjustments are described in section \ref{sec:withdraw-protocol-schnorr}. + + +\subsection{Public APIs and Data Structures} +\label{sec:specification-withdraw-public-api} +The existing endpoint is available under \texttt{POST /reserves/[reserve]/withdraw} where "reserve" is the reserve public key encoded as Crockford base32. +It takes the following input parameters described in table \ref{tab:withdraw-request-data} as JSON.\\\\ +\framebox[1.1\width]{\color{blue}\texttt{POST /reserves/[reserve]/withdraw}} +\begin{table}[ht] + \centering + \colorlet{BFH-table}{BFH-MediumBlue!10} + \colorlet{BFH-tablehead}{BFH-MediumBlue!50} + \setupBfhTabular + \begin{tabular}{ll} + \rowcolor{BFH-tablehead} + \textbf{Field} & \textbf{Value} \\ + denom\_pub\_hash & Denomination Public Key \\ + coin\_ev & RSA blinded coin public key \\ + reserve\_sig & Signature over the request using the reserve's private key \\ + \end{tabular} + \caption{Withdraw request data} + \label{tab:withdraw-request-data} +\end{table} + +In order to facilitate parsing, Christian Grothoff suggested to include the cipher type in the "coin\_ev" field, thus creating a nested \ac{JSON} (as described in table \ref{tab:withdraw-coin-ev-rsa}). +\begin{table}[ht] + \centering + \colorlet{BFH-table}{BFH-MediumBlue!10} + \colorlet{BFH-tablehead}{BFH-MediumBlue!50} + \setupBfhTabular + \begin{tabular}{lll} + \rowcolor{BFH-tablehead} + \textbf{Field} & \textbf{Type} & \textbf{Value} \\ + cipher & Integer & Denomination cipher: 1 stands for RSA \\ + rsa\_blinded\_planchet & String & RSA blinded coin public key \\ + \end{tabular} + \caption{Withdraw "coin\_ev" field (RSA)} + \label{tab:withdraw-coin-ev-rsa} +\end{table} + +For the Clause Schnorr implementation, the field "rsa\_blinded\_planchet" will be replaced with the necessary values as described in table \ref{tab:withdraw-coin-ev-cs}. +\begin{table}[ht] + \centering + \resizebox{0.85\textwidth}{!}{\begin{minipage}{\textwidth} + \colorlet{BFH-table}{BFH-MediumBlue!10} + \colorlet{BFH-tablehead}{BFH-MediumBlue!50} + \setupBfhTabular + \begin{tabular}{lll} + \rowcolor{BFH-tablehead} + \textbf{Field} & \textbf{Type} & \textbf{Value} \\ + cipher & Integer & Denomination cipher: 2 stands for \gls{CSBS} \\ + cs\_nonce & String & 32 Bytes encoded in Crockford base32 Hex \\ + cs\_blinded\_c0 & String & 32 Bytes encoded in Crockford base32 Hex \\ + cs\_blinded\_c1 & String & 32 Bytes encoded in Crockford base32 Hex \\ + \end{tabular} + \caption{Withdraw "coin\_ev" field (\gls{CSBS})} + \label{tab:withdraw-coin-ev-cs} +\end{minipage}} +\end{table} + +The exchange will then process the withdraw request and return one of these HTTP status codes: +\begin{itemize} + \item \textbf{200 (HTTP\_OK)}: Request Successful + \item \textbf{400 (BAD\_REQUEST)}: Invalid input parameters (can also happen if denomination cipher doesn't match with cipher in "coin\_ev") + \item \textbf{403 (FORBIDDEN)}: Signature contained in "reserve\_sig" invalid + \item \textbf{404 (NOT\_FOUND)}: Denomination unknown + \item \textbf{410 (GONE)}: Denomination revoked/expired + \item \textbf{412 (PRECONDITION\_FAILED)}: Denomination not yet valid +\end{itemize} + +When the request was successful, the exchange returns the RSA signature as JSON (described in table \ref{tab:withdraw-response-rsa}). +\begin{table}[ht] + \centering + \colorlet{BFH-table}{BFH-MediumBlue!10} + \colorlet{BFH-tablehead}{BFH-MediumBlue!50} + \setupBfhTabular + \begin{tabular}{lll} + \rowcolor{BFH-tablehead} + \textbf{Field} & \textbf{Type} & \textbf{Value} \\ + cipher & Integer & Denomination cipher: 1 stands for RSA \\ + blinded\_rsa\_signature & String & RSA signature \\ + \end{tabular} + \caption{Withdraw response (RSA)} + \label{tab:withdraw-response-rsa} +\end{table} + +Table \ref{tab:withdraw-response-cs} describes the response for \gls{CSBS}. +\begin{table}[ht] + \centering + \resizebox{0.85\textwidth}{!}{\begin{minipage}{\textwidth} + \colorlet{BFH-table}{BFH-MediumBlue!10} + \colorlet{BFH-tablehead}{BFH-MediumBlue!50} + \setupBfhTabular + \begin{tabular}{lll} + \rowcolor{BFH-tablehead} + \textbf{Field} & \textbf{Type} & \textbf{Value} \\ + cipher & Integer & Denomination cipher: 2 stands for \gls{CSBS} \\ + b & Integer & \gls{CSBS} signature session identifier (either 0 or 1) \\ + s & String & signature scalar (32 Bytes encoded in Crockford base32 Hex) \\ + \end{tabular} + \caption{Withdraw response (\gls{CSBS})} + \label{tab:withdraw-response-cs} +\end{minipage}} +\end{table} + + +\subsection{Persistence} +Persistence for withdrawing is implemented in the function \texttt{postgres\_do\_withdraw} in \texttt{src/exchangedb/plugin\_exchangedb\_postgres.c} +For \gls{CSBS}, persisting the blinded signature must be implemented. + + +\section{Deposit Protocol} +For the deposit protocol (described in section \ref{sec:deposit-protocol}) only the handling and verification of \gls{CSBS} signatures has to be added. + +\subsection{Public APIs and Data Structures} +Deposit is an existing endpoint available under \texttt{POST /coins/[coin public key]/deposit} where "coin public key" is encoded as Crockford base32. +Additional parameters are passed as JSON (as described in table \ref{tab:spend-request}).\\\\ +\framebox[1.1\width]{\color{blue}\texttt{POST /coins/[coin public key]/deposit}} +\begin{table}[ht] + \centering + \colorlet{BFH-table}{BFH-MediumBlue!10} + \colorlet{BFH-tablehead}{BFH-MediumBlue!50} + \setupBfhTabular + \begin{tabular}{ll} + \rowcolor{BFH-tablehead} + \textbf{Field} & \textbf{Value} \\ + % cipher & Denomination cipher: 2 stands for \gls{CSBS} \\ + % b & \gls{CSBS} signature session identifier (either 0 or 1) \\ + % s & signature scalar (32 Bytes encoded in Crockford base32 Hex) \\ + merchant\_payto\_uri & Account that is credited \\ + wire\_salt & Salt used by the merchant \\ + contribution & Amount to use for payment (for one specific coin) \\ + denom\_pub\_hash & Denomination public key hash \\ + ub\_sig & (unblinded) denomination signature of coin \\ + merchant\_pub & Merchant public key \\ + h\_contract\_terms & Contract terms hash \\ + coin\_sig & Deposit permission signature \\ + timestamp & Timestamp of generation \\ + refund\_deadline (optional) & Refund deadline \\ + wire\_transfer\_deadline (optional) & Wire transfer deadline \\ + \end{tabular} + \caption{Spend request} + \label{tab:spend-request} +\end{table} + +Relevant field for the \gls{CSBS} implementation is the field "ub\_sig" containing the unblinded denomination signature of the coin. +For RSA, the (nested) \ac{JSON} is described in table \ref{tab:spend-request-ubsig-rsa}. +\begin{table}[ht] + \centering + \colorlet{BFH-table}{BFH-MediumBlue!10} + \colorlet{BFH-tablehead}{BFH-MediumBlue!50} + \setupBfhTabular + \begin{tabular}{lll} + \rowcolor{BFH-tablehead} + \textbf{Field} & \textbf{Type} & \textbf{Value} \\ + cipher & Integer & Denomination cipher: 1 stands for RSA \\ + rsa\_signature & String & Unblinded RSA signature \\ + \end{tabular} + \caption{ub\_sig (RSA)} + \label{tab:spend-request-ubsig-rsa} +\end{table} + +Table \ref{tab:spend-request-ubsig-cs} describes the values in "ub\_sig" required for \gls{CSBS}. +\begin{table}[ht] + \centering + \resizebox{0.85\textwidth}{!}{\begin{minipage}{\textwidth} + \colorlet{BFH-table}{BFH-MediumBlue!10} + \colorlet{BFH-tablehead}{BFH-MediumBlue!50} + \setupBfhTabular + \begin{tabular}{lll} + \rowcolor{BFH-tablehead} + \textbf{Field} & \textbf{Type} & \textbf{Value} \\ + cipher & Integer & Denomination cipher: 2 stands for \gls{CSBS} \\ + cs\_signature\_r & String & Curve point $ R' $ (32 Bytes encoded in Crockford base32 Hex) \\ + cs\_signature\_s & String & Signature scalar (32 Bytes encoded in Crockford base32 Hex) \\ + \end{tabular} + \caption{ub\_sig (\gls{CSBS})} + \label{tab:spend-request-ubsig-cs} +\end{minipage}} +\end{table} + + +\subsection{Persistence} +Persistence is handled in the functions \texttt{postgres\_insert\_deposit} and\\ \texttt{postgres\_have\_deposit} located in \url{src/exchangedb/plugin_exchangedb_postgres.c}. +However, these functions are not containing \gls{CSBS}-specific persistence. +\\What needs to be adjusted however, is the function \texttt{postgres\_ensure\_coin\_known} called by the function \texttt{TEH\_make\_coin\_known} (located in \url{src/exchange/taler-exchange-httpd_db.c}). + + +% \section{Tipping} +% \subsection{Public APIs and Data Structures} +% \subsection{Code Location} +% \subsection{Persistence} +% \subsection{Used Libraries} + +% \section{Payback Protocol} +% \subsection{Public APIs and Data Structures} +% \subsection{Code Location} +% \subsection{Persistence} +% \subsection{Used Libraries} + + +% sollte ein Product Backlog das Ziel dieser Phase sein? -- cgit v1.2.3