Applied Zcash

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 login sequence 1: The user gives the app an address. 2: The app shows a login link. 3: The user pays the worker, and the payment has the login memo. 4: The worker sends a memo with a 6-digit code to the address. 5: The user types the code in the app. 6: The app calculates the code and compares the two codes. user app worker 1 address 2 login link 3 payment with the login memo 4 memo: 6-digit code 5 types the code 6 compares codes
Each arrow is one message. The steps are in sequence from top to bottom.
  1. The user types their unified address in the app. This address is the return address.
  2. The app makes a session ID. It writes the login memo from the session ID and the return address.
  3. 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.
  4. The user pays the link from a wallet. The funds can come from any wallet.
  5. The worker finds the payment in the mempool. It decrypts the payment with its viewing key and reads the memo.
  6. The worker calculates the code from the code key, the session ID and the return address.
  7. The worker sends a shielded payment to the return address. The memo of this payment contains the code.
  8. The user reads the code in the wallet and types it in the app.
  9. 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

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.

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:

Demo parameters
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:

Test vector
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.

Demo

Wait

Reply

Code check

Change this page on GitHub