DO-IRP Mechanics and Interaction Workflows

1.1 Service Discovery and Server Selection

Before resolving an identifier such as 86.1000/123, the client must locate the responsible server. This is a two-level lookup: first use the prefix to locate a service site, then use a hash algorithm to select a specific server.

Mechanism Reference Table

Step	Structure / Field	Purpose
1. Obtain prefix information	`Identifier`	Extract the prefix, such as `86.1000`, and query `0.NA/86.1000` through the root service or a local cache.
2. Resolve site information	`HS_SITE`	The `HS_SITE` Element returned by the prefix record contains the service configuration.
3. Select a site	`HS_SITE.PrimaryMask`	A read operation may use any site; a write operation must select a primary site with `PrimarySite=1`.
4. Locate a server	`HS_SITE.HashOption`	Select the hashing algorithm: `0x00` for Prefix, `0x01` for Suffix, or `0x02` for ID.
5. Compute the target	`HS_SITE.NumOfServer`	Compute `abs(Hash(ID)) % NumOfServer`; the result indexes `ServerRecordList`.

Interaction Diagram

sequenceDiagram
    participant C as Client
    participant R as Global Registry (0.NA)
    participant S as Target Server (Service Site)

    Note over C: Resolve target: "86.1000/DOC"
    C->>C: Extract prefix "86.1000"

    C->>R: Resolve prefix record (0.NA/86.1000)
    R-->>C: Return HS_SITE Element list

    Note over C: Process HS_SITE:<br>1. Select site (Primary/Mirror)<br>2. Hash ID using HashOption<br>3. Modulo NumOfServer to select Server IP

    C->>S: Send resolution request (OpCode=1, Identifier="86.1000/DOC")
    S-->>C: Return Identifier Record (ElementList)

1.2 Identifier Resolution

Resolution is the fundamental operation. It supports filtering by Index or Type and enforces access control.

Mechanism Reference Table

Mechanism	Message Field	Logic
Issue query	`Header.OpCode`	Set to `1` (OC_RESOLUTION).
Filter content	`Body.IndexList` `Body.TypeList`	Specify the Elements to retrieve. If both lists are empty and `PO=1`, return all public Elements.
Enforce permissions	`Header.OpFlag.PO`	Public Only flag. - `PO=1`: return only `PUBLIC_READ` Elements. - `PO=0`: attempt to read non-public Elements; without permission the server returns `RC_AUTHEN_NEEDED`.
Service referral	`Header.ResponseCode`	If the server is not responsible for the ID, it may return `302` (RC_SERVICE_REFERRAL) with the target service’s `HS_SITE` in the Body.

Interaction Diagram

sequenceDiagram
    participant Client
    participant Server_A as Server A (Old/Wrong)
    participant Server_B as Server B (Correct)

    Note right of Client: Query request (PO=1, Public Only)
    Client->>Server_A: Request: OC_RESOLUTION<br>ID: "86.1000/DOC"

    alt ID is managed by another service
        Server_A-->>Client: Response: RC_SERVICE_REFERRAL (302)<br>Body: Target HS_SITE (Server B)
        Note right of Client: Receive referral and update target address
        Client->>Server_B: Request: OC_RESOLUTION<br>ID: "86.1000/DOC"
        Server_B-->>Client: Response: RC_SUCCESS (1)<br>Body: ElementList
    else ID does not exist
        Server_A-->>Client: Response: RC_ID_NOT_FOUND (100)
    end

1.3 Client Authentication

A client must authenticate when performing administrative operations such as add, delete, or modify, or when reading restricted data. DO-IRP uses a Challenge-Response mechanism.

Mechanism Reference Table

Step	Message Field	Logic
1. Trigger authentication	`Header.ResponseCode`	The client sends a request; when the server detects insufficient permission, it returns `402` (RC_AUTHEN_NEEDED).
2. Obtain challenge	`Body.Nonce`	The server generates a random `Nonce` and sends it to the client.
3. Compute signature	`Body.ChallengeResponse`	The client signs `Nonce + RequestDigest` with its private key, or computes a MAC.
4. Send credentials	`Body.KeyIdentifier` `Body.KeyIndex`	The client identifies the location of the public key or secret key used to verify the signature: the Identifier and Element index.
5. Verify result	`Header.ResponseCode`	The server verifies the signature. On success, it executes the original request and returns `RC_SUCCESS`; on failure, it returns `403` (RC_AUTHEN_FAILED).

Interaction Diagram

sequenceDiagram
    participant Admin as Client (Admin)
    participant Server

    Note right of Admin: Attempt to remove Element (authentication required)
    Admin->>Server: Request: OC_REMOVE_ELEMENT<br>ID: "86.1000/DOC", Index: [2]

    Note left of Server: Check permission: ADMIN_WRITE required<br>Client is not authenticated
    Server-->>Admin: Response: RC_AUTHEN_NEEDED (402)<br>Body: Nonce (random value) + RequestDigest

    Note right of Admin: 1. Locate local private key (for 0.NA/Admin:300)<br>2. Sign data: Sign(Nonce + Digest)<br>3. Construct response
    Admin->>Server: Request: OC_CHALLENGE_RESPONSE (200)<br>Body: KeyID="0.NA/Admin", KeyIdx=300<br>Signature=...

    Note left of Server: 1. Load Index 300 (public key) from 0.NA/Admin<br>2. Verify signature<br>3. Execute removal
    alt Verification succeeds
        Server-->>Admin: Response: RC_SUCCESS (1)
    else Verification fails
        Server-->>Admin: Response: RC_AUTHEN_FAILED (403)
    end

1.4 Session Management

A client can establish a session to avoid an asymmetric signature on every request and to protect communications with encryption.

Mechanism Reference Table

Mechanism	Message Field	Logic
Establish session	`Header.OpCode`	Send a `400` (OC_SESSION_SETUP) request.
Exchange keys	`Body.PublicKey`	Exchange Diffie-Hellman public keys and derive a shared Session Key.
Identify session	`Envelope.SessionId`	After a successful handshake, the server assigns a nonzero ID. Every subsequent message must carry this ID.
Prevent replay	`Credential.SessionCounter`	Every message in the session must carry an increasing counter to prevent replay attacks.
Encrypt communication	`Envelope.Flag.EC`	`EC=1` indicates that the Body is encrypted with the Session Key.
Authenticate communication	`Credential.Type`	After session establishment, use the `"HS_MAC"` type to compute an HMAC with the Session Key, which is more efficient than RSA or DSA signatures.

Interaction Diagram

sequenceDiagram
    participant C as Client
    participant S as Server

    Note right of C: Initiate session setup (Diffie-Hellman)
    C->>S: Request: OC_SESSION_SETUP (400)<br>Body: Client_DH_PubKey

    Note left of S: Generate Server_DH_PubKey<br>Compute Shared_Secret<br>Allocate SessionID=99
    S-->>C: Response: OC_SESSION_SETUP (400)<br>Envelope: SessionID=99<br>Body: Server_DH_PubKey<br>Credential: HS_SIGNED (RSA signature)

    Note right of C: Compute Shared_Secret (Session Key)<br>Use symmetric encryption/MAC for subsequent requests

    C->>S: Request: OC_CREATE_ID (100)<br>Envelope: SessionID=99, Flag=EC(Encrypted)<br>Credential: HS_MAC (HMAC-SHA256)
    S-->>C: Response: RC_SUCCESS (1)<br>Envelope: Flag=EC

1.5 Administrative Transactions

All add, modify, remove, create, and delete operations (ADD, MODIFY, REMOVE, CREATE, DELETE) follow atomic transaction semantics.

Mechanism Reference Table

Mechanism	Message Field	Logic
Atomicity	-	A batch operation, such as adding multiple Elements, either succeeds completely or rolls back completely. If any item fails, for example because of an index conflict, no modification is applied.
Overwrite	`Header.OpFlag.OWE`	Overwrite When Exists. - `OWE=0`: if the Element exists, return `RC_ELEMENT_ALREADY_EXISTS`. - `OWE=1`: if the Element exists, overwrite it.
Automatic suffix	`Header.OpFlag.MNS`	Mint New Suffix. When set during identifier creation, the server generates a unique suffix and returns the complete ID.
Error location	`Body.IndexList` (Error)	If a batch operation fails, the Error Response Body contains the list of Element indexes that caused the error.