4_2_specification.tex (41387B)
1 \chapter{Protocol Specification} 2 \label{chap:spec} 3 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. 4 A Taler Exchange operator should be able to configure whether he wants to use \gls{RSABS} or \gls{CSBS}. 5 \\This variant allows to choose the signature scheme globally or per denomination. 6 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. 7 \\ 8 The following key points are specified in this chapter: 9 \begin{itemize} 10 \item Architecture of the different components 11 \item Explain and specify needed changes 12 \item Data strucutures 13 \item Public \acp{API} 14 \item Persistence 15 \item Used libraries 16 \end{itemize} 17 18 \section{Architecture} 19 Before specifying the implementation of the different protocols, a deeper understanding of the technical architecture of Talers components is needed. 20 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. 21 22 \subsection{Exchange} 23 An introduction to the exchange can be found in section \ref{sec:exchange}. 24 An exchange operator needs to run and maintain some additional services besides Taler's exchange. 25 Although this is not directly relevant for the implementation, it helps to better understand the environment in which the exchange runs. 26 The perspective of an exchange operator can be seen in figure \ref{fig:taler:exchange-operator-architecture}. 27 28 \begin{figure}[h!] 29 \begin{adjustbox}{max totalsize={.9\textwidth}{.7\textheight},center} 30 \begin{tikzpicture} 31 \tikzstyle{def} = [node distance= 5em and 6.5em, inner sep=1em, outer sep=.3em]; 32 \node (origin) at (0,0) {}; 33 \node (exchange) [def,above=of origin,draw]{Exchange}; 34 \node (nexus) [def, draw, below right=of exchange] {Nexus}; 35 \node (corebanking) [def, draw, below left=of nexus] {Core Banking}; 36 \node (nginx) [def, draw, above=of exchange]{Nginx}; 37 \node (postgres) [def, draw, below left=of exchange]{Postgres}; 38 \node (postgres-nexus) [def, draw, below right=of nexus]{Postgres}; 39 40 \tikzstyle{C} = [color=black, line width=1pt] 41 42 \draw [<-, C] (exchange) -- (nginx) node [midway, above, sloped] (TextNode) {REST API}; 43 \draw [<-, C] (postgres) -- (exchange) node [midway, above, sloped] (TextNode) {SQL}; 44 \draw [<-, C] (postgres-nexus) -- (nexus) node [midway, above, sloped] (TextNode) {SQL}; 45 \draw [<-, C] (nexus) -- (exchange) node [midway, above, sloped] (TextNode) {Internal REST API}; 46 \draw [<-, C] (corebanking) -- (nexus) node [midway, above, sloped] (TextNode) {EBICS/FinTS}; 47 48 \end{tikzpicture} 49 \end{adjustbox} 50 \caption{Taler exchange operator architecture (source: \cite{taler-presentation})} 51 \label{fig:taler:exchange-operator-architecture} 52 \end{figure} 53 54 The software architecture of the exchange can be seen in figure \ref{fig:taler:exchange-architecture}. 55 The API runs under the httpd service, where the API endpoints need to be adjusted/added to incorporate the changes of this thesis. 56 The httpd server has no access to the private keys of the denomination and online signing keys. 57 Only the corresponding security module can perform operations requiring the private key. 58 Further the keys are also managed by these security modules. 59 To support \gls{CSBS} a new security module, which performs signature operations, is added. 60 To persist the new data structures, the postgres helpers need to be adjusted to serialize/deserialize the new \gls{CSBS} data structures. 61 More details on what changes are needed in these places is discussed in the following sections. 62 63 \begin{figure}[h!] 64 \begin{center} 65 \begin{tikzpicture} 66 \tikzstyle{def} = [node distance=2em and 2.5em, inner sep=1em, outer sep=.3em]; 67 \node (origin) at (0,0) {}; 68 \node [blue] (httpd) [def,above=of origin,draw]{httpd}; 69 \node (secmod-rsa) [def, draw, right=of httpd] {secmod-rsa}; 70 \node (secmod-eddsa) [def, draw, left=of httpd] {secmod-eddsa}; 71 \node [blue](postgres) [def, draw, below=of httpd]{Postgres}; 72 \node [mGreen] (secmod-cs) [def, draw, left=of postgres]{secmod-cs}; 73 \node (aggregator) [def, draw, right=of postgres]{aggregator}; 74 \node (transfer) [def, draw, below left=of postgres]{transfer}; 75 \node (wirewatch) [def, draw, below right=of postgres]{wirewatch}; 76 \node (nexus) [def, draw, below=of postgres]{Nexus}; 77 78 \tikzstyle{C} = [color=black, line width=1pt] 79 80 \draw [<->, C] (httpd) -- (postgres) node [midway, above, sloped] (TextNode) {}; 81 \draw [<->, C] (httpd) -- (secmod-rsa) node [midway, above, sloped] (TextNode) {}; 82 \draw [<->, C] (httpd) -- (secmod-eddsa) node [midway, above, sloped] (TextNode) {}; 83 \draw [<->, C] (httpd) -- (secmod-cs) node [midway, above, sloped] (TextNode) {}; 84 \draw [<->, C] (aggregator) -- (postgres) node [midway, above, sloped] (TextNode) {}; 85 \draw [<->, C] (wirewatch) -- (postgres) node [midway, above, sloped] (TextNode) {}; 86 \draw [<->, C] (transfer) -- (postgres) node [midway, above, sloped] (TextNode) {}; 87 \draw [->, C] (transfer) -- (nexus) node [midway, above, sloped] (TextNode) {}; 88 \draw [<-, C] (wirewatch) -- (nexus) node [midway, above, sloped] (TextNode) {}; 89 \end{tikzpicture} 90 \end{center} 91 \caption{Taler exchange architecture (source: \cite{taler-presentation})} 92 \label{fig:taler:exchange-architecture} 93 \end{figure} 94 95 \subsection{Wallet} 96 The architecture of the wallet implementation (as seen in figure \ref{fig:taler:wallet-architecture}) is quite straightforward. 97 To add support for \gls{CSBS} in the wallet, the cryptographic routines need to be reimplemented in Typescript. 98 Taler uses tweetnacl \cite{bern:tweetnacl} which provides functionality for the group operations. 99 There are existing \gls{hkdf} and \gls{fdh} implementations, that can be reused.\\ 100 Furthermore, the Taler protocols need to be adjusted to support \gls{CSBS} in the wallet-core. 101 102 \begin{figure}[h!] 103 \begin{center} 104 \begin{tikzpicture} 105 \tikzstyle{def} = [node distance= 5em and 4.5em, inner sep=1em, outer sep=.3em]; 106 \node (origin) at (0,0) {}; 107 \node (gui) [def,above=of origin,draw]{wallet-gui}; 108 \node [blue](core) [def,below=of gui,draw]{wallet-core}; 109 \node (sync) [def, draw, below left=of core] {Sync}; 110 \node (taler) [def, draw, below right=of core] {Taler}; 111 \node (anastasis) [def, draw, below=of core] {Anastasis}; 112 113 \tikzstyle{C} = [color=black, line width=1pt] 114 \draw [<->, C] (gui) -- (core) node [midway, above, sloped] (TextNode) {}; 115 \draw [<->, C] (core) -- (sync) node [midway, above, sloped] (TextNode) {Backup}; 116 \draw [<->, C] (core) -- (taler) node [midway, above, sloped] (TextNode) {Payment}; 117 \draw [<->, C] (core) -- (anastasis) node [midway, above, sloped] (TextNode) {Key Escrow}; 118 \end{tikzpicture} 119 \end{center} 120 \caption{Taler wallet architecture (source: \cite{taler-presentation})} 121 \label{fig:taler:wallet-architecture} 122 \end{figure} 123 124 \section{Persistence} 125 The Clause Blind Schnorr Signature scheme is quite different to \gls{RSABS}. 126 Despite the differences, the database model does not need to be changed. 127 The only change needed an additional type field, specifying whether RSA or CS is used as signature algorithm. 128 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. 129 130 \section{Testing} 131 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. 132 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. 133 134 Test cases can be used to verify different aspects of a functionality. 135 These are the ones we will focus on. 136 \begin{itemize} 137 \item \textbf{Known good}: 138 Known good cases test whether a functionality works as expected. 139 They are the most useful during development, because they indicate whether the code is working as expected. 140 \item \textbf{Known Bad}: 141 Known bad cases test whether functionality that is known not to work behaves as expected. 142 \item \textbf{Determinism}: 143 This case type checks whether the same input leads to the same output. 144 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. 145 \item \textbf{Performance testing}: 146 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. 147 We will restrict performance testing to the comparison of the Blind RSA Signature Scheme and the Clause Blind Schnorr Signature Scheme. 148 \end{itemize} 149 150 151 \section{Signature Scheme Operations in GNUnet} 152 \label{sec:specification-signature-scheme} 153 154 The signature scheme operations implemented are needed in all other parts of the implementation. 155 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. 156 It is important to provide a clear API for the cryptographic routines and to test them thoroughly. 157 Libsodium will be used for finite field arithmetic (\cite{libsodium:finite-field-arithmetic}) and for other functionality when available (e.g. for key generation). 158 Thus, a widely used and well tested cryptographic library is used for group operations. 159 160 For \acl{FDH} and \gls{hkdf} existing implementations provided by GNUnet are used. 161 The \gls{hkdf} is used with SHA-512 for the extraction phase and SHA-256 for the expansion phase. 162 163 \subsection{Data Structures} 164 Libsodium represents Ed25519 points and scalars as 32-byte char arrays. 165 To provide a more user-friendly \ac{API}, structs were created to represent each type. 166 For example \texttt{struct GNUNET\_CRYPTO\_CsPrivateKey} or \texttt{struct GNUNET\_CRYPTO\_RSecret} 167 The main reason is to increase readability and to prevent misusage of the \ac{API}. 168 Unlike RSA, our \gls{CSBS} on Ed25519 data structures have a fixed sizes. 169 The different data structures can be found in table \ref{tab:datastruct-crypto}. 170 171 \begin{table}[ht] 172 \centering 173 \resizebox{0.95\textwidth}{!}{\begin{minipage}{\textwidth} 174 \colorlet{BFH-table}{BFH-MediumBlue!10} 175 \colorlet{BFH-tablehead}{BFH-MediumBlue!50} 176 \setupBfhTabular 177 \begin{tabular}{lll} 178 \rowcolor{BFH-tablehead} 179 \textbf{Values} & \textbf{Data Structure} & \textbf{Data Type} \\\hline 180 Curve25519 Scalar & {\small GNUNET\_CRYPTO\_Cs25519Scalar} & 32 byte char array\\\hline 181 Curve25519 Point & {\small GNUNET\_CRYPTO\_Cs25519Point} & 32 byte char array\\\hline 182 Private Key & {\small GNUNET\_CRYPTO\_CsPrivateKey} & {\small GNUNET\_CRYPTO\_Cs25519Scalar}\\\hline 183 Public Key & {\small GNUNET\_CRYPTO\_CsPublicKey} & {\small GNUNET\_CRYPTO\_Cs25519Point}\\\hline 184 $\alpha, \beta$ & {\small GNUNET\_CRYPTO\_CsBlindingSecret} & {\footnotesize 2x GNUNET\_CRYPTO\_Cs25519Scalar}\\\hline 185 $r$ & {\small GNUNET\_CRYPTO\_CsRSecret} & {\small GNUNET\_CRYPTO\_Cs25519Scalar}\\\hline 186 $R$ & {\small GNUNET\_CRYPTO\_CsRPublic} & {\small GNUNET\_CRYPTO\_Cs25519Point}\\\hline 187 $c$ & {\small GNUNET\_CRYPTO\_CsC} & {\small GNUNET\_CRYPTO\_Cs25519Scalar}\\\hline 188 $s$ & {\small GNUNET\_CRYPTO\_CsBlindS} & {\small GNUNET\_CRYPTO\_Cs25519Scalar}\\\hline 189 $s'$ & {\small GNUNET\_CRYPTO\_CsS} & {\small GNUNET\_CRYPTO\_Cs25519Scalar}\\\hline 190 $\sigma := \langle s',R' \rangle$ & {\small GNUNET\_CRYPTO\_CsSignature} & {\small GNUNET\_CRYPTO\_Cs25519Scalar}\\ 191 & & {\small GNUNET\_CRYPTO\_Cs25519Point}\\\hline 192 Nonce & {\small GNUNET\_CRYPTO\_CsNonce} & 32 byte char array\\\hline 193 \end{tabular} 194 \caption{Data structures for cryptographic routines} 195 \label{tab:datastruct-crypto} 196 \end{minipage}} 197 \end{table} 198 199 200 201 \subsection{Library API} 202 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}. 203 It was developed in multiple iterations based on feedback from Christian Grothoff. 204 The complete C header \ac{API} can be found in the repository. 205 This section provides an overview of the implemented crypto API. 206 207 Some design decisions need to be explained further: 208 \begin{itemize} 209 \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. 210 Internally most variables are either scalars or curve points (except for nonces, secrets and messages). 211 \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. 212 Instead, the API returns an array of two instead of a single value.\\ 213 For these functions, we also optimized the \gls{hkdf} (as proposed by Christian Grothoff). 214 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. 215 \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}). 216 \end{itemize} 217 218 The following API examples should provide an overview on how the API works and how to use it. 219 220 First of all the API must provide functionality to create a \gls{25519} keypair as in listing \ref{lst:crypto-keypair-api} 221 222 \begin{lstlisting}[style=bfh-c,language=C, caption={GNUnet create keypair API}, label={lst:crypto-keypair-api}] 223 /** 224 * Create a new random private key. 225 * 226 * @param[out] priv where to write the fresh private key 227 */ 228 void 229 GNUNET_CRYPTO_cs_private_key_generate ( 230 struct GNUNET_CRYPTO_CsPrivateKey *priv); 231 232 233 /** 234 * Extract the public key of the given private key. 235 * 236 * @param priv the private key 237 * @param[out] pub where to write the public key 238 */ 239 void 240 GNUNET_CRYPTO_cs_private_key_get_public ( 241 const struct GNUNET_CRYPTO_CsPrivateKey *priv, 242 struct GNUNET_CRYPTO_CsPublicKey *pub); 243 \end{lstlisting} 244 245 The signer needs an API to generate his secret $r$ and calculate his public point $R$. 246 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. 247 The r\_derive API derives such a secret $r$ from a nonce and a long-term secret with \gls{hkdf}. 248 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}. 249 250 251 \begin{lstlisting}[style=bfh-c,language=C, caption={GNUnet r derive API}, label={lst:crypto-rderive-api}] 252 /** 253 * Derive a new secret r pair r0 and r1. 254 * In original papers r is generated randomly 255 * To provide abort-idempotency, r needs to be derived but still needs to be UNPREDICTABLE 256 * To ensure unpredictability a new nonce should be used when a new r needs to be derived. 257 * Uses HKDF internally. 258 * Comment: Can be done in one HKDF shot and split output. 259 * 260 * @param nonce is a random nonce 261 * @param lts is a long-term-secret in form of a private key 262 * @param[out] r array containing derived secrets r0 and r1 263 */ 264 void 265 GNUNET_CRYPTO_cs_r_derive (const struct GNUNET_CRYPTO_CsNonce *nonce, 266 const struct GNUNET_CRYPTO_CsPrivateKey *lts, 267 struct GNUNET_CRYPTO_CsRSecret r[2]); 268 269 270 /** 271 * Extract the public R of the given secret r. 272 * 273 * @param r_priv the private key 274 * @param[out] r_pub where to write the public key 275 */ 276 void 277 GNUNET_CRYPTO_cs_r_get_public (const struct GNUNET_CRYPTO_CsRSecret *r_priv, 278 struct GNUNET_CRYPTO_CsRPublic *r_pub); 279 \end{lstlisting} 280 281 282 Same as the r\_derive, the blinding secrets are also derived and not generated randomly. 283 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}. 284 285 \begin{lstlisting}[style=bfh-c,language=C, caption={GNUnet blinding secrets derive API}, label={lst:crypto-blinding-secrets-api}] 286 /** 287 * Derives new random blinding factors. 288 * In original papers blinding factors are generated randomly 289 * To provide abort-idempotency, blinding factors need to be derived but still need to be UNPREDICTABLE 290 * To ensure unpredictability a new nonce has to be used. 291 * Uses HKDF internally 292 * 293 * @param secret is secret to derive blinding factors 294 * @param secret_len secret length 295 * @param[out] bs array containing the two derivedGNUNET_CRYPTO_CsBlindingSecret 296 */ 297 void 298 GNUNET_CRYPTO_cs_blinding_secrets_derive ( 299 const struct GNUNET_CRYPTO_CsNonce *blind_seed, 300 struct GNUNET_CRYPTO_CsBlindingSecret bs[2]); 301 \end{lstlisting} 302 303 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}. 304 305 \begin{lstlisting}[style=bfh-c,language=C, caption={GNUnet calculate blinded c API}, label={lst:crypto-calc-c-api}] 306 /** 307 * Calculate two blinded c's 308 * Comment: One would be insecure due to Wagner's algorithm solving ROS 309 * 310 * @param bs array of the two blinding factor structs each containing alpha and beta 311 * @param r_pub array of the two signer's nonce R 312 * @param pub the public key of the signer 313 * @param msg the message to blind in preparation for signing 314 * @param msg_len length of message msg 315 * @param[out] blinded_c array of the two blinded c's 316 */ 317 void 318 GNUNET_CRYPTO_cs_calc_blinded_c ( 319 const struct GNUNET_CRYPTO_CsBlindingSecret bs[2], 320 const struct GNUNET_CRYPTO_CsRPublic r_pub[2], 321 const struct GNUNET_CRYPTO_CsPublicKey *pub, 322 const void *msg, 323 size_t msg_len, 324 struct GNUNET_CRYPTO_CsC blinded_c[2]); 325 \end{lstlisting} 326 327 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$. 328 See listing \ref{lst:crypto-sign-api}. 329 330 \begin{lstlisting}[style=bfh-c,language=C, caption={GNUnet sign API}, label={lst:crypto-sign-api}] 331 /** 332 * Sign a blinded c 333 * This function derives b from a nonce and a longterm secret 334 * In original papers b is generated randomly 335 * To provide abort-idempotency, b needs to be derived but still need to be UNPREDICTABLE. 336 * To ensure unpredictability a new nonce has to be used for every signature 337 * HKDF is used internally for derivation 338 * r0 and r1 can be derived prior by using GNUNET_CRYPTO_cs_r_derive 339 * 340 * @param priv private key to use for the signing and as LTS in HKDF 341 * @param r array of the two secret nonce from the signer 342 * @param c array of the two blinded c to sign c_b 343 * @param nonce is a random nonce 344 * @param[out] blinded_signature_scalar where to write the signature 345 * @return 0 or 1 for b (see Clause Blind Signature Scheme) 346 */ 347 int 348 GNUNET_CRYPTO_cs_sign_derive( 349 const struct GNUNET_CRYPTO_CsPrivateKey *priv, 350 const struct GNUNET_CRYPTO_CsRSecret r[2], 351 const struct GNUNET_CRYPTO_CsC c[2], 352 const struct GNUNET_CRYPTO_CsNonce *nonce, 353 struct GNUNET_CRYPTO_CsBlindS *blinded_signature_scalar); 354 \end{lstlisting} 355 356 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}. 357 358 \begin{lstlisting}[style=bfh-c,language=C, caption={GNUnet unblind API}, label={lst:crypto-unblind-api}] 359 /** 360 * Unblind a blind-signed signature using a c that was blinded 361 * 362 * @param blinded_signature_scalar the signature made on the blinded c 363 * @param bs the blinding factors used in the blinding 364 * @param[out] signature_scalar where to write the unblinded signature 365 */ 366 void 367 GNUNET_CRYPTO_cs_unblind ( 368 const struct GNUNET_CRYPTO_CsBlindS *blinded_signature_scalar, 369 const struct GNUNET_CRYPTO_CsBlindingSecret *bs, 370 struct GNUNET_CRYPTO_CsS *signature_scalar); 371 \end{lstlisting} 372 373 The verify API takes the message and its signature with the public key and returns GNUNET\_OK for a valid signature and GNUNET\_SYSERR otherwise. 374 See listing \ref{lst:crypto-verify-api}. 375 376 \begin{lstlisting}[style=bfh-c,language=C,, caption={GNUnet verify API}, label={lst:crypto-verify-api}] 377 /** 378 * Verify whether the given message corresponds to the given signature and the 379 * signature is valid with respect to the given public key. 380 * 381 * @param sig signature that is being validated 382 * @param pub public key of the signer 383 * @param msg is the message that should be signed by @a sig (message is used to calculate c) 384 * @param msg_len is the message length 385 * @returns #GNUNET_YES on success, #GNUNET_SYSERR if signature invalid 386 */ 387 enum GNUNET_GenericReturnValue 388 GNUNET_CRYPTO_cs_verify (const struct GNUNET_CRYPTO_CsSignature *sig, 389 const struct GNUNET_CRYPTO_CsPublicKey *pub, 390 const void *msg, 391 size_t msg_len); 392 \end{lstlisting} 393 394 \subsection{Testing} 395 For digital signature schemes, the most important test case is the \textit{known good} case where a signature is created and successfully validated. 396 This test case already tests very much in a digital signature scheme. 397 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. 398 399 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. 400 401 Since libsodium is used for the finite field arithmetic operations and is a well tested library, many cryptographic tests are already done in libsodium. 402 403 The performance is measured in a benchmark to see how performant \gls{CSBS} are in comparison to the RSA Blind Signature Scheme. 404 405 \section{Taler Cryptographic Utilities} 406 Taler provides utility functions to support cryptographic operations.\\ 407 This chapter provides an overview of these utility functions and about the functionality they provide. 408 409 \subsection{Planchet Creation} 410 In crypto.c many utility functions are provided to create planchets (for planchet details see \ref{fig:coin:states}), blinding secrets and much more. 411 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. 412 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. 413 414 A planchet in the Clause Blind Schnorr Signature Scheme can be created as followed (implementation details omitted). 415 416 \begin{enumerate} 417 \item Create planchet with new \ac{EdDSA} private key 418 \item Derive withdraw nonce 419 \item Request public $R_0, R_1$ from signer 420 \item Derive blinding seed 421 \item Prepare (blind) the planchet 422 \end{enumerate} 423 424 After the planchet is created, it is sent to the exchange to be signed. 425 426 \subsection{Taler CS Security Module} 427 The exchange segregates access to the private keys with separate security module processes. 428 The security module has sole access to the private keys of the online signing keys and thus, only a security module can create signatures. 429 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}. 430 431 Now a new \textit{taler-exchange-secmod-cs} needs to be created for managing the \gls{CSBS} denomination keys. 432 These security modules run on the same machine as the httpd process and they use UNIX Domain Sockets as method for \acl{IPC}. 433 A short introduction about UNIX Domain Sockets can be found in the blog post \cite{matt:unix-domain-sockets}. 434 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. 435 This abstraction makes it harder for an attacker who has already compromised the http daemon to gain access to the private keys. 436 However, such an attacker would still be able to sign arbitrary messages (see \cite{taler-documentation:exchange-operator-manual}). 437 A crypto helper exists for each security module, these functions can be called inside the exchange for operations requiring the private online signing keys. 438 The new Clause Schnorr security module and corresponding crypto helper provides the following functionality: 439 \begin{itemize} 440 \item Private Key Management and creation 441 \item Request public $R_0, R_1$ 442 \item Request a signature of a $c_0,c_1$ pair 443 \item Revoke an online signing key 444 \end{itemize} 445 446 \subsection{Testing} 447 All of the operations have tests and are included in unit tests. 448 As a template for testing, the existing RSA tests were used and adjusted for \gls{CSBS}. 449 450 451 \section{Denomination Key Management} 452 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}. 453 454 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}. \\\\ 455 \framebox[1.1\width]{\color{blue}\texttt{GET /management/keys}} 456 \begin{table}[ht] 457 \centering 458 \resizebox{0.9\textwidth}{!}{\begin{minipage}{\textwidth} 459 \colorlet{BFH-table}{BFH-MediumBlue!10} 460 \colorlet{BFH-tablehead}{BFH-MediumBlue!50} 461 \setupBfhTabular 462 \begin{tabular}{ll} 463 \rowcolor{BFH-tablehead} 464 \textbf{Field} & \textbf{Value} \\ 465 future\_denoms & Information about denomination keys \\ 466 future\_signkeys & Information about exchange online signing keys \\ 467 master\_pub & Exchange's master public key \\ 468 denom\_secmod\_public\_key & RSA security module public key \\ 469 denom\_secmod\_cs\_public\_key & \gls{CSBS} security module public key \\ 470 signkey\_secmod\_public\_key & Online signing security module public key \\ 471 \end{tabular} 472 \caption{GET \url{/management/keys} response data} 473 \label{tab:management-keys-get} 474 \end{minipage}} 475 \end{table} 476 477 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}. \\\\ 478 \framebox[1.1\width]{\color{blue}\texttt{POST /management/keys}} 479 \begin{table}[ht] 480 \centering 481 \colorlet{BFH-table}{BFH-MediumBlue!10} 482 \colorlet{BFH-tablehead}{BFH-MediumBlue!50} 483 \setupBfhTabular 484 \begin{tabular}{ll} 485 \rowcolor{BFH-tablehead} 486 \textbf{Field} & \textbf{Value} \\ 487 denom\_sigs & Denomination key signatures \\ 488 signkey\_sigs & Online signing key signatures \\ 489 \end{tabular} 490 \caption{POST \url{/management/keys} response data} 491 \label{tab:management-keys-post} 492 \end{table} 493 494 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}. \\\\ 495 \framebox[1.1\width]{\color{blue}\texttt{GET /keys}} 496 \begin{table}[ht] 497 \centering 498 \colorlet{BFH-table}{BFH-MediumBlue!10} 499 \colorlet{BFH-tablehead}{BFH-MediumBlue!50} 500 \setupBfhTabular 501 \begin{tabular}{ll} 502 \rowcolor{BFH-tablehead} 503 \textbf{Field} & \textbf{Value} \\ 504 version & Exchange's protocol version \\ 505 currency & Currency \\ 506 master\_public\_key & Exchange's master public key \\ 507 reserve\_closing\_delay & Delay before reserves are closed \\ 508 signkeys & Exchange's online signing public keys \\ 509 recoup & Revoked keys \\ 510 denoms & List of denominations \\ 511 auditors & Auditors for this exchange \\ 512 list\_issue\_date & Timestamp \\ 513 eddsa\_pub & Exchange's online signing public key \\ 514 eddsa\_sig & Signature (use "eddsa\_pub" for verification) \\ 515 \end{tabular} 516 \caption{GET \url{/keys} response data} 517 \label{tab:keys-get} 518 \end{table} 519 520 521 \section{New Endpoint for $R$} 522 The withdraw and refresh protocols using the Claude Blind Schnorr Signature Scheme introduce an additional round trip. 523 In this round trip, the customer requests two $ R $ from the exchange. 524 The exchange uses a secret $ r $ to calculate $ R := rG $. 525 \\ 526 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). 527 This still ensures that the private $ r $ can't be anticipated, but has multiple advantages regarding \gls{abort-idempotency}. 528 \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. 529 The challenge for $ r, R $ regarding \gls{abort-idempotency} is to ensure that the same $ r $ is used during the complete signature creation process. 530 531 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. 532 This is done during signature creation and will be described in the withdraw protocol section \ref{sec:specification-withdraw}. 533 534 535 \subsection{Public APIs and Data Structures} 536 This is a new functionality, meaning a new endpoint accessible to customers has to be introduced. 537 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}). 538 \begin{table}[ht] 539 \centering 540 \resizebox{0.9\textwidth}{!}{\begin{minipage}{\textwidth} 541 \colorlet{BFH-table}{BFH-MediumBlue!10} 542 \colorlet{BFH-tablehead}{BFH-MediumBlue!50} 543 \setupBfhTabular 544 \begin{tabular}{lll} 545 \rowcolor{BFH-tablehead} 546 \textbf{Field} & \textbf{Type} & \textbf{Value} \\ 547 nonce & String & 32 Bytes encoded in Crockford base32 Hex \\ 548 denom\_pub\_hash & String & Denomination Public Key encoded in Crockford base32 Hex \\ 549 \end{tabular} 550 \caption{POST \url{/csr} request data} 551 \label{tab:csr-request-data} 552 \end{minipage}} 553 \end{table} 554 555 The exchange will then check the denomination and return one of these HTTP status codes: 556 \begin{itemize} 557 \item \textbf{200 (HTTP\_OK)}: Request Successful 558 \item \textbf{400 (BAD\_REQUEST)}: Invalid input parameters 559 \item \textbf{404 (NOT\_FOUND)}: Denomination unknown or not Clause Schnorr 560 \item \textbf{410 (GONE)}: Denomination revoked/expired 561 \item \textbf{412 (PRECONDITION\_FAILED)}: Denomination not yet valid 562 \end{itemize} 563 564 When the request was successful, the exchange returns the data described in table \ref{tab:csr-response-data} (as \ac{JSON}). 565 \begin{table}[ht] 566 \centering 567 \colorlet{BFH-table}{BFH-MediumBlue!10} 568 \colorlet{BFH-tablehead}{BFH-MediumBlue!50} 569 \setupBfhTabular 570 \begin{tabular}{lll} 571 \rowcolor{BFH-tablehead} 572 \textbf{Field} & \textbf{Type} & \textbf{Value} \\ 573 r\_pub\_0 & String & 32 Bytes encoded in Crockford base32 Hex \\ 574 r\_pub\_1 & String & 32 Bytes encoded in Crockford base32 Hex \\ 575 \end{tabular} 576 \caption{POST \url{/csr} response data} 577 \label{tab:csr-response-data} 578 \end{table} 579 580 581 \subsection{Persistence} 582 This API does not persist anything. 583 This is because the resulting $R_0, R_1$ are derived and can be derived in a later step. 584 585 586 \section{Withdraw Protocol} 587 \label{sec:specification-withdraw} 588 The withdraw protocol has been introduced in section \ref{sec:withdrawal}. 589 For the \acl{CS} necessary adjustments are described in section \ref{sec:withdraw-protocol-schnorr}. 590 591 592 \subsection{Public APIs and Data Structures} 593 \label{sec:specification-withdraw-public-api} 594 The existing endpoint is available under \texttt{POST /reserves/[reserve]/withdraw} where "reserve" is the reserve public key encoded as Crockford base32. 595 It takes the following input parameters described in table \ref{tab:withdraw-request-data} as JSON.\\\\ 596 \framebox[1.1\width]{\color{blue}\texttt{POST /reserves/[reserve]/withdraw}} 597 \begin{table}[ht] 598 \centering 599 \colorlet{BFH-table}{BFH-MediumBlue!10} 600 \colorlet{BFH-tablehead}{BFH-MediumBlue!50} 601 \setupBfhTabular 602 \begin{tabular}{ll} 603 \rowcolor{BFH-tablehead} 604 \textbf{Field} & \textbf{Value} \\ 605 denom\_pub\_hash & Denomination Public Key \\ 606 coin\_ev & RSA blinded coin public key \\ 607 reserve\_sig & Signature over the request using the reserve's private key \\ 608 \end{tabular} 609 \caption{Withdraw request data} 610 \label{tab:withdraw-request-data} 611 \end{table} 612 613 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}). 614 \begin{table}[ht] 615 \centering 616 \colorlet{BFH-table}{BFH-MediumBlue!10} 617 \colorlet{BFH-tablehead}{BFH-MediumBlue!50} 618 \setupBfhTabular 619 \begin{tabular}{lll} 620 \rowcolor{BFH-tablehead} 621 \textbf{Field} & \textbf{Type} & \textbf{Value} \\ 622 cipher & Integer & Denomination cipher: 1 stands for RSA \\ 623 rsa\_blinded\_planchet & String & RSA blinded coin public key \\ 624 \end{tabular} 625 \caption{Withdraw "coin\_ev" field (RSA)} 626 \label{tab:withdraw-coin-ev-rsa} 627 \end{table} 628 629 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}. 630 \begin{table}[ht] 631 \centering 632 \resizebox{0.85\textwidth}{!}{\begin{minipage}{\textwidth} 633 \colorlet{BFH-table}{BFH-MediumBlue!10} 634 \colorlet{BFH-tablehead}{BFH-MediumBlue!50} 635 \setupBfhTabular 636 \begin{tabular}{lll} 637 \rowcolor{BFH-tablehead} 638 \textbf{Field} & \textbf{Type} & \textbf{Value} \\ 639 cipher & Integer & Denomination cipher: 2 stands for \gls{CSBS} \\ 640 cs\_nonce & String & 32 Bytes encoded in Crockford base32 Hex \\ 641 cs\_blinded\_c0 & String & 32 Bytes encoded in Crockford base32 Hex \\ 642 cs\_blinded\_c1 & String & 32 Bytes encoded in Crockford base32 Hex \\ 643 \end{tabular} 644 \caption{Withdraw "coin\_ev" field (\gls{CSBS})} 645 \label{tab:withdraw-coin-ev-cs} 646 \end{minipage}} 647 \end{table} 648 649 The exchange will then process the withdraw request and return one of these HTTP status codes: 650 \begin{itemize} 651 \item \textbf{200 (HTTP\_OK)}: Request Successful 652 \item \textbf{400 (BAD\_REQUEST)}: Invalid input parameters (can also happen if denomination cipher doesn't match with cipher in "coin\_ev") 653 \item \textbf{403 (FORBIDDEN)}: Signature contained in "reserve\_sig" invalid 654 \item \textbf{404 (NOT\_FOUND)}: Denomination unknown 655 \item \textbf{410 (GONE)}: Denomination revoked/expired 656 \item \textbf{412 (PRECONDITION\_FAILED)}: Denomination not yet valid 657 \end{itemize} 658 659 When the request was successful, the exchange returns the RSA signature as JSON (described in table \ref{tab:withdraw-response-rsa}). 660 \begin{table}[ht] 661 \centering 662 \colorlet{BFH-table}{BFH-MediumBlue!10} 663 \colorlet{BFH-tablehead}{BFH-MediumBlue!50} 664 \setupBfhTabular 665 \begin{tabular}{lll} 666 \rowcolor{BFH-tablehead} 667 \textbf{Field} & \textbf{Type} & \textbf{Value} \\ 668 cipher & Integer & Denomination cipher: 1 stands for RSA \\ 669 blinded\_rsa\_signature & String & RSA signature \\ 670 \end{tabular} 671 \caption{Withdraw response (RSA)} 672 \label{tab:withdraw-response-rsa} 673 \end{table} 674 675 Table \ref{tab:withdraw-response-cs} describes the response for \gls{CSBS}. 676 \begin{table}[ht] 677 \centering 678 \resizebox{0.85\textwidth}{!}{\begin{minipage}{\textwidth} 679 \colorlet{BFH-table}{BFH-MediumBlue!10} 680 \colorlet{BFH-tablehead}{BFH-MediumBlue!50} 681 \setupBfhTabular 682 \begin{tabular}{lll} 683 \rowcolor{BFH-tablehead} 684 \textbf{Field} & \textbf{Type} & \textbf{Value} \\ 685 cipher & Integer & Denomination cipher: 2 stands for \gls{CSBS} \\ 686 b & Integer & \gls{CSBS} signature session identifier (either 0 or 1) \\ 687 s & String & signature scalar (32 Bytes encoded in Crockford base32 Hex) \\ 688 \end{tabular} 689 \caption{Withdraw response (\gls{CSBS})} 690 \label{tab:withdraw-response-cs} 691 \end{minipage}} 692 \end{table} 693 694 695 \subsection{Persistence} 696 Persistence for withdrawing is implemented in the function \texttt{postgres\_do\_withdraw} in \texttt{src/exchangedb/plugin\_exchangedb\_postgres.c} 697 For \gls{CSBS}, persisting the blinded signature must be implemented. 698 699 700 \section{Deposit Protocol} 701 For the deposit protocol (described in section \ref{sec:deposit-protocol}) only the handling and verification of \gls{CSBS} signatures has to be added. 702 703 \subsection{Public APIs and Data Structures} 704 Deposit is an existing endpoint available under \texttt{POST /coins/[coin public key]/deposit} where "coin public key" is encoded as Crockford base32. 705 Additional parameters are passed as JSON (as described in table \ref{tab:spend-request}).\\\\ 706 \framebox[1.1\width]{\color{blue}\texttt{POST /coins/[coin public key]/deposit}} 707 \begin{table}[ht] 708 \centering 709 \colorlet{BFH-table}{BFH-MediumBlue!10} 710 \colorlet{BFH-tablehead}{BFH-MediumBlue!50} 711 \setupBfhTabular 712 \begin{tabular}{ll} 713 \rowcolor{BFH-tablehead} 714 \textbf{Field} & \textbf{Value} \\ 715 % cipher & Denomination cipher: 2 stands for \gls{CSBS} \\ 716 % b & \gls{CSBS} signature session identifier (either 0 or 1) \\ 717 % s & signature scalar (32 Bytes encoded in Crockford base32 Hex) \\ 718 merchant\_payto\_uri & Account that is credited \\ 719 wire\_salt & Salt used by the merchant \\ 720 contribution & Amount to use for payment (for one specific coin) \\ 721 denom\_pub\_hash & Denomination public key hash \\ 722 ub\_sig & (unblinded) denomination signature of coin \\ 723 merchant\_pub & Merchant public key \\ 724 h\_contract\_terms & Contract terms hash \\ 725 coin\_sig & Deposit permission signature \\ 726 timestamp & Timestamp of generation \\ 727 refund\_deadline (optional) & Refund deadline \\ 728 wire\_transfer\_deadline (optional) & Wire transfer deadline \\ 729 \end{tabular} 730 \caption{Spend request} 731 \label{tab:spend-request} 732 \end{table} 733 734 Relevant field for the \gls{CSBS} implementation is the field "ub\_sig" containing the unblinded denomination signature of the coin. 735 For RSA, the (nested) \ac{JSON} is described in table \ref{tab:spend-request-ubsig-rsa}. 736 \begin{table}[ht] 737 \centering 738 \colorlet{BFH-table}{BFH-MediumBlue!10} 739 \colorlet{BFH-tablehead}{BFH-MediumBlue!50} 740 \setupBfhTabular 741 \begin{tabular}{lll} 742 \rowcolor{BFH-tablehead} 743 \textbf{Field} & \textbf{Type} & \textbf{Value} \\ 744 cipher & Integer & Denomination cipher: 1 stands for RSA \\ 745 rsa\_signature & String & Unblinded RSA signature \\ 746 \end{tabular} 747 \caption{ub\_sig (RSA)} 748 \label{tab:spend-request-ubsig-rsa} 749 \end{table} 750 751 Table \ref{tab:spend-request-ubsig-cs} describes the values in "ub\_sig" required for \gls{CSBS}. 752 \begin{table}[ht] 753 \centering 754 \resizebox{0.85\textwidth}{!}{\begin{minipage}{\textwidth} 755 \colorlet{BFH-table}{BFH-MediumBlue!10} 756 \colorlet{BFH-tablehead}{BFH-MediumBlue!50} 757 \setupBfhTabular 758 \begin{tabular}{lll} 759 \rowcolor{BFH-tablehead} 760 \textbf{Field} & \textbf{Type} & \textbf{Value} \\ 761 cipher & Integer & Denomination cipher: 2 stands for \gls{CSBS} \\ 762 cs\_signature\_r & String & Curve point $ R' $ (32 Bytes encoded in Crockford base32 Hex) \\ 763 cs\_signature\_s & String & Signature scalar (32 Bytes encoded in Crockford base32 Hex) \\ 764 \end{tabular} 765 \caption{ub\_sig (\gls{CSBS})} 766 \label{tab:spend-request-ubsig-cs} 767 \end{minipage}} 768 \end{table} 769 770 771 \subsection{Persistence} 772 Persistence is handled in the functions \texttt{postgres\_insert\_deposit} and\\ \texttt{postgres\_have\_deposit} located in \url{src/exchangedb/plugin_exchangedb_postgres.c}. 773 However, these functions are not containing \gls{CSBS}-specific persistence. 774 \\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}). 775 776 777 % \section{Tipping} 778 % \subsection{Public APIs and Data Structures} 779 % \subsection{Code Location} 780 % \subsection{Persistence} 781 % \subsection{Used Libraries} 782 783 % \section{Payback Protocol} 784 % \subsection{Public APIs and Data Structures} 785 % \subsection{Code Location} 786 % \subsection{Persistence} 787 % \subsection{Used Libraries} 788 789 790 % sollte ein Product Backlog das Ziel dieser Phase sein?