​

Client Handshake Flow Specification

​

Overview

​

Client Responsibilities

1. Manage its own DID identity and public/private key pairs
2. Store and manage user authorization credentials
3. Initiate handshake requests and complete mutual identity verification
4. Negotiate access permissions and obtain access tokens
5. Maintain encrypted communication sessions with the server

​

Complete Handshake Flow (Client Perspective)

​

Prerequisite: Obtain User Pre-Authorization

1. Request authorization from the user, specifying the scope of resources to be accessed
2. The user signs an authorization credential containing the authorization scope, validity period, and other information
3. The client securely stores the user authorization credential

​

Step 1: Initiate Handshake Request

{
  "type": "handshake_request",
  "client_did": "did:ath:client_xxxxxx",
  "client_pubkey": "-----BEGIN PUBLIC KEY-----...",
  "versions": ["0.1", "0.2"],
  "capabilities": ["ES256", "EdDSA", "TLS1.3"],
  "nonce": "random_string_a",
  "timestamp": 1234567890
}

​

Step 2: Process Server Handshake Response

1. Verifies the validity of the server DID and public key
2. Verifies the server’s signature of nonce A is correct
3. Negotiates and determines the protocol version and encryption algorithm
4. Saves the server public key and metadata

​

Step 3: Send Identity Proof

{
  "type": "identity_proof",
  "signature": "signature_of_nonce_b",
  "credentials": [/* optional identity credentials */],
  "timestamp": 1234567892
}

​

Step 4: Process Identity Verification Result

1. Checks whether identity verification passed
2. Reads the list of supported scopes and configuration information from the server
3. If verification fails, terminates the handshake flow

​

Step 5: Send Permission Request

{
  "type": "scope_request",
  "scopes": ["user:read", "data:write"],
  "ttl": 1800,
  "user_authorization": {
    "credential": "jwt_token_signed_by_user",
    "signature": "signature_by_client"
  },
  "context": "For generating user monthly reports",
  "timestamp": 1234567894
}

​

Steps 6-7: Wait for User Authorization Confirmation

​

Step 8: Process Permission Approval Result

1. Checks whether the granted permission scope meets its requirements
2. Records access restrictions and validity period
3. If permissions are denied, terminates the handshake flow

​

Step 9: Complete Handshake, Establish Session

1. Generates key exchange parameters and sends them to the server
2. Receives the server’s key exchange parameters and generates a shared session key
3. Verifies the validity of the access token issued by the server
4. Encrypts all subsequent business requests using the session key

​

Error Handling

​

Security Requirements

• User authorization credentials must be stored encrypted to prevent leakage
• Private keys must be stored securely and must not be transmitted in plaintext
• Session keys must be rotated periodically, with a validity period not exceeding 24 hours