Pattern
Log in with Zcash
A user logs in to an app with a Zcash address. The user pays a small amount from a wallet. A server wallet then sends a one-time code in a memo to the address.
The user types the code in the app. The server wallet sends the code only to that address. Thus, the address is the account of the user.
This pattern is from ZcashMe. The use of a one-time code in a memo for login is the invention of Zechariah. The Zcash Verification Service is the reference implementation.
Problem
An app must know that a user controls an address. The sender of a shielded payment is secret, also to the receiver. Wallets sign messages with transparent keys at most. ZIP 304 is for Sapling keys only.
Each shielded wallet sends payments with memos. Each shielded wallet also shows the memos of the payments that it receives. These two functions are the base of this pattern.
Mechanism
Roles
- User
- A person with a Zcash wallet and a unified address.
- App
- The website that the user logs in to. It makes sessions and examines codes.
- Worker
- A server wallet. It receives login payments and sends codes.
- Service address
- The unified address of the worker. The app puts it in each login link.
- Session ID
- A number of 16 decimal digits. The app makes a new session ID for each login.
- Return address
- The address that the user gives to the app. The worker sends the code there.
- Code key
- A secret key of 32 bytes. The worker and the app each have a copy.
- Code
- A one-time code of 6 digits.
Sequence
- The user types their unified address in the app. This address is the return address.
- The app makes a session ID. It writes the login memo from the session ID and the return address.
- The app shows a ZIP 321 payment link as a QR code. The link has the service address, the login amount and the login memo.
- The user pays the link from a wallet. The funds can come from any wallet.
- The worker finds the payment in the mempool. It decrypts the payment with its viewing key and reads the memo.
- The worker calculates the code from the code key, the session ID and the return address.
- The worker sends a shielded payment to the return address. The memo of this payment contains the code.
- The user reads the code in the wallet and types it in the app.
- The app calculates the code and compares the two codes. If they are equal, the user is logged in.
The worker and the app calculate the code independently, from the same three values. Thus, the worker needs a connection to the Zcash network only.
Login memo
The app writes the login memo as one line of text:
memo = "DO NOT MODIFY:{zvs/" session "," address "}"
session the session ID, 16 decimal digits
address the return address, as the user typed it
The wallet shows the memo before it sends the payment. The first words are an instruction for the user. The worker accepts this format only. It refuses a memo with a different prefix, a second comma, or text after the last brace.
Code
code = HMAC-SHA256(key, session ‖ address)[0..4] mod 10⁶
The first 4 bytes of the HMAC are a big-endian number. The code is this number modulo 1,000,000, written as 6 decimal digits. The address in the calculation is the exact text of the address in the memo.
The worker puts the code in the memo of the reply. The memo contains the 6 digits only:
847291
What the code shows
The reply is a shielded payment to the return address. Outside the service, only a holder of the incoming viewing key of that address can read it. Thus, a correct code shows that the user can read the memos of that address.
The service also knows the code. The worker and the app calculate it, and the worker can read the reply that it sent. Thus, the result is correct only while the keys of the service are secret.
The login payment can come from any wallet, because its sender is secret.
Wallet-native orders has a different sign-in. There, the operator already knows the address and sends the code first.
Worker
The worker examines the return address before it sends the reply. The address must be valid for the network of the worker. The reply at ZcashMe has an amount of 0.0005 ZEC.
The worker keeps a record of each reply on disk. Thus, the worker makes one reply transaction at most for each login payment. After a failure, the worker sends the same transaction again.
OpenID Connect
ZcashMe runs this flow as an OpenID Connect provider at auth.zcash.me. An app sends the user there
with a usual OIDC library. After the login, the app receives the unified address of the user as the
sub claim.
Cost
- Each login The login amount and the network fee. The minimum login amount at ZcashMe is 0.002 ZEC. A usual shielded payment with change has two actions. The ZIP 2009 fee for two actions is 2,000 zatoshis. The user receives the reply amount.
- The service The reply amount and the network fee of each reply. At ZcashMe, the reply amount is 0.0005 ZEC and the fee is 2,000 zatoshis. The worker pays both from the login amounts.
- Wallets Each login is two transactions on the chain. See Polite actions.
- Time The worker sends the reply when the login payment is in the mempool. The wallet of the user shows the reply after its next sync.
- Wallet support ZIP 321 with memos. The wallet must send the memo bytes unchanged, and it must show the memos of received payments.
Limits
Warning
The code key is a shared secret. A person with the code key can calculate the code for each session and each address. A person with the outgoing viewing key of the worker can read each reply. Keep these keys on the servers of the app and the worker only.
- Viewing keys. A holder of the incoming viewing key of the return address can read the code. Thus, this holder can log in as the address.
- Guesses. A code has 6 digits. The app must stop a session after a small number of incorrect codes.
- Lifetime. The calculation has no time input. Thus, the code of a session stays the same. The app must give each session an expiry, and it must accept the code one time only.
- Phishing. A clone page can show the login link of a real session and then ask for the code. The user must examine the host of the page before they type a code.
- Mempool. A payment in the mempool can expire before it is in a block. Thus, the service can lose the reply amount and the reply fee, and receive no login amount.
- Privacy. Outsiders see two usual shielded transactions. The service knows the return address and the time of each login. Apps that get the same address can link the accounts of the user.
Alternative: a signature login
With a new wallet function, a wallet signs a login message with a shielded key. Thus, the login is off the chain. The worker, the code key and the fees are unnecessary. Wallets do not have this function today. The designs are on the wishlist page Signature login.
Spec
The reference for this pattern is the source of the
Zcash Verification Service, under the MIT
license. The memo format is in src/memo.rs. The code calculation and its test vector are in
src/otp.rs.
Demo: a toy login
These are the values of the toy login:
amount 0.002 ZEC
memo "DO NOT MODIFY:{zvs/" session "," address "}"
code HMAC-SHA256(key, session ‖ address)[0..4] mod 10⁶
reply code
The demo writes the login memo, makes the ZIP 321 URI and draws the QR code. It also calculates the code, as the worker and the app do. The session ID and the code key are random values from your browser.
To examine the calculation, type the test vector of the reference implementation:
key 000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f
session 1234567890123456
address u1example-return-address
code 880279
Caution
The service address is a Testnet address. Its key is in the public source of this site. A wallet on Testnet can pay the link, but the worker is only a demo.
Wait