Session Keys

Previous versions supported private key wallets to prevent cumbersome signing and improve the user experience. Unfortunately private key support presents both a real and perceived security issue. For Kuma , a session key (SK) design replaces private key support. Session keys provide a similar UX as private keys but feature additional safety.

In the session key model:

1. The client generates a new standard Ethereum key pair.

2. The user signs the new session public key with their custody wallet when signing in to Kuma.

3. The client posts the session public key along with the signature to the server.

4. The server verifies the signature and subsequently allows actions on behalf of the user to be signed by the session key.

By associating a new key pair with a wallet, the user delegates trade authorization and eliminates the need to manually sign subsequent order placements and cancellations. The resulting UX is similar to a centralized exchange without putting the user’s custody wallet at risk.

Permissions

Session keys open the possibility of fine-grained controls on assigned permissions. Currently SKs only include the capability to place and cancel orders. Deposits and withdrawals require a custody wallet signature.

Expiration

In addition to permissions, session keys expire 30 days after creation. SKs’ UUID v1 nonce embeds a creation timestamp; additionally there is a SK expiration period configured as a single parameter across the system, contracts included. No user controls are provided for SK expiration dates.

Invalidation

Kuma includes a more robust mechanism for invalidating SKs. As noted in Contracts, invalidating a custody wallet’s nonce also precludes any further order authorizations from existing SKs. The off-chain components automatically cancel all open orders and revoke all associated SKs on receiving a nonce invalidation event.

1. Invalidation requests are authorized by custody wallet signature only and may be made for any active or expired associated SK.

2. The server validates the invalidation requests and cancels all open orders authorized by the target SKs.

3. The server updates the SK database row as revoked but does not clear the authorization signature. The authorization signature may be necessary for rebroadcasts and other operational concerns, and is ultimately public, as it is included in any prior settlement transactions for the SK.

Importantly, an order authorized by an expired but not invalidated SK is valid.