097-challenge-confirmations.rst (8938B)
1 .. _dd-97: 2 3 DD 97: Challenge-Signature Payment Confirmations 4 ################################################ 5 6 Summary 7 ======= 8 9 This document proposes challenge-signature payment confirmations for 10 unattended devices that cannot contact the merchant backend themselves. 11 The device generates a fresh challenge, the merchant backend signs it after 12 payment, and the device verifies the signature before performing its local 13 action. 14 15 .. note:: 16 17 This design document proposes an extension for discussion. The protocol 18 version name ``vChallengeConfirmation`` is a placeholder. 19 20 Motivation 21 ========== 22 23 Some unattended devices must verify that a Taler payment succeeded without 24 being online themselves. Existing point-of-sale confirmations use a 25 time-based one-time password (TOTP). A TOTP proves knowledge of a shared 26 secret, but it does not bind the confirmation to a challenge freshly chosen 27 by the device. 28 29 Two examples motivate a challenge-bound confirmation: 30 31 * A coffee machine generates a fresh challenge and displays or transmits it 32 to the customer's wallet. After payment, the machine dispenses the 33 selected product only if it receives a valid signature for that challenge. 34 35 * An electronic farmer tag attached to an unattended farm stand or collection 36 point generates a fresh challenge before a local action. It can verify the 37 payment confirmation even when the tag itself has no network connection. 38 39 The merchant backend remains online and processes the payment normally. The 40 offline device only needs a public key and a source of unpredictable 41 challenges. 42 43 Requirements 44 ============ 45 46 * The confirmation must be bound to a fresh challenge generated by the 47 offline device. 48 49 * The merchant backend must generate and retain the signing private key. 50 51 * The offline device must only require the corresponding public key. 52 53 * The wallet must be able to transport the challenge and confirmation without 54 interpreting device-specific behavior. 55 56 * Replaying an accepted confirmation must not authorize another local action. 57 58 * Existing TOTP confirmation algorithms must remain unchanged. 59 60 Proposed Solution 61 ================= 62 63 The merchant backend's OTP algorithm enumeration is extended with two 64 challenge-signature algorithms: 65 66 * ``ECDSA_CHALLENGE`` (numeric value 3) uses ECDSA with NIST P-256. 67 68 * ``EDDSA_CHALLENGE`` (numeric value 4) uses EdDSA with Ed25519. 69 70 When a challenge-signature OTP device is created, the merchant backend 71 generates the signing key pair. It stores the private key and returns the 72 public key to the merchant application. The public key is then configured 73 in the offline verifier. The private key is never exposed through the API. 74 75 For these algorithms, the client supplies a fresh 32-byte challenge while 76 instantiating a template. The challenge is encoded using Crockford Base32 77 and becomes part of the order. After successful payment, the backend signs 78 the challenge with the key associated with the template's OTP device. The 79 signature is returned in ``PaymentResponse.pos_confirmation``. 80 81 The wallet only transports the challenge to the merchant and the resulting 82 signature back to the device. It does not possess the signing key and does 83 not decide whether the local action is allowed. 84 85 Payment Flow 86 ============ 87 88 1. The offline device generates a cryptographically unpredictable challenge. 89 90 2. The wallet obtains the challenge from the device and includes it as 91 ``challenge`` when instantiating the merchant template. 92 93 3. The merchant backend creates the order and the wallet pays it using the 94 normal Taler payment protocol. 95 96 4. After accepting the payment, the backend signs the order's challenge and 97 returns the encoded signature as ``pos_confirmation``. 98 99 5. The wallet relays the confirmation to the device. 100 101 6. The device verifies the signature using its configured public key and 102 performs the local action only after successful verification. 103 104 The device must reject a challenge after it has accepted a confirmation for 105 that challenge. This prevents replaying a previous payment confirmation to 106 obtain another product or action. 107 108 Protocol Changes 109 ================ 110 111 OTP Device Creation 112 ------------------- 113 114 The existing :ref:`merchant OTP device API <merchant-otp-device-api>` accepts 115 values 3 and 4 for ``OtpDeviceAddDetails.otp_algorithm`` when creating a 116 device. For these values, ``OtpDeviceAddDetails.otp_key`` must be omitted 117 because the backend generates the key pair. 118 119 Successful creation returns: 120 121 .. ts:def:: OtpDeviceCreateResponse 122 123 interface OtpDeviceCreateResponse { 124 // Public key generated for the challenge-signature device. 125 // For ECDSA this is a compressed NIST P-256 point. 126 // For EdDSA this is an Ed25519 public key. 127 // Crockford Base32 encoded. 128 otp_device_pub: string; 129 } 130 131 The response for reading an OTP device exposes the same public key as the 132 optional ``OtpDeviceDetails.otp_device_pub`` field. 133 134 Template Instantiation 135 ---------------------- 136 137 The common template request gains: 138 139 .. ts:def:: UsingTemplateCommonRequestChallenge 140 141 interface UsingTemplateCommonRequestChallenge { 142 // Fresh challenge generated by the offline verifier. 143 // Exactly 32 bytes, Crockford Base32 encoded. 144 challenge?: string; 145 } 146 147 The field is required when the template references an OTP device using 148 ``ECDSA_CHALLENGE`` or ``EDDSA_CHALLENGE`` and must otherwise be rejected. 149 150 Payment Response 151 ---------------- 152 153 For a challenge-signature OTP device, the existing 154 ``PaymentResponse.pos_confirmation`` field contains the Crockford Base32 155 encoded signature over the order's challenge. 156 157 Error Handling 158 ============== 159 160 Template instantiation fails if: 161 162 * the challenge is absent for a challenge-signature OTP device; 163 164 * the challenge is present for an OTP algorithm that does not use it; 165 166 * the challenge is not valid Crockford Base32; or 167 168 * the decoded challenge does not have the required length. 169 170 Payment processing fails closed if the backend cannot load the device's 171 private key or cannot produce the signature. It must not return a successful 172 confirmation with an empty or malformed ``pos_confirmation``. 173 174 Security Considerations 175 ======================= 176 177 Challenges must be generated with a cryptographically secure random number 178 generator. Predictable challenges would permit an attacker to prepare a 179 confirmation before the device requests it. 180 181 An offline verifier must remember challenges that have already been accepted, 182 at least for as long as replaying them could cause a second local action. A 183 device with volatile state should generate challenges from a sufficiently 184 large random space and invalidate the current challenge immediately after 185 successful verification. 186 187 The verifier's configured public key is security-sensitive configuration. 188 Replacing it changes which merchant backend can authorize the device. 189 190 The signature construction must use domain separation defined by the merchant 191 protocol. It should bind the signature to the challenge and the relevant 192 device or order context so that signatures cannot be reused across protocol 193 purposes. 194 195 Privacy Considerations 196 ====================== 197 198 The challenge is random and carries no customer identity. The offline device 199 does not learn the customer's Taler payment credentials. The wallet learns 200 that the payment is associated with a local challenge, which is inherent in 201 relaying the confirmation. 202 203 Drawbacks 204 ========= 205 206 The device must implement public-key signature verification and secure replay 207 handling, which is more demanding than displaying or checking a short TOTP. 208 209 If the payment succeeds but the wallet cannot relay the confirmation, the 210 merchant has received the payment while the local action has not happened. 211 Applications need a recovery or refund procedure appropriate to the product. 212 213 Test Plan 214 ========= 215 216 * Test OTP device creation for both challenge-signature algorithms and verify 217 that the private key is never returned. 218 219 * Test rejection of supplied ``otp_key`` values for challenge-signature 220 devices. 221 222 * Test template instantiation with missing, malformed, short and unexpected 223 challenges. 224 225 * Test that a successful payment returns a signature accepted by the 226 corresponding public key and rejected by another key. 227 228 * Test that modifying the challenge invalidates the confirmation. 229 230 * Test coffee-machine and farmer-tag integrations with repeated and replayed 231 challenges. 232 233 Definition of Done 234 ================== 235 236 * The merchant backend supports OTP algorithms 3 and 4, generates their key 237 pairs and exposes only their public keys. 238 239 * Template instantiation validates and stores a 32-byte challenge for these 240 algorithms. 241 242 * Successful payment returns a challenge-bound signature in 243 ``pos_confirmation``. 244 245 * Wallet Core can transport the challenge and relay the confirmation without 246 interpreting device-specific behavior. 247 248 * At least one offline verifier implementation validates confirmations and 249 rejects replayed challenges.