Pairing nodes

The process of establishing a federated network between two nodes with intent of securely sharing data. The process consists of two steps:

Node identification: The step identifies the two nodes so they know where to access the information.
Node handshake: The step exchanges the authentication tokens so the two nodes can access protected resources from each other.

Outline of the entire node pairing process.

@startuml
skinparam responseMessageBelowArrow true

actor "Administrator A" as AdministratorA
participant "Node A" as NodeA
participant "Node B" as NodeB
actor "Administrator B" as AdministratorB

== Node identification ==
AdministratorA->NodeA: Register federated node B
note right of AdministratorA
Administrator A sends the node URI
to administrator B via a secure channel.
end note
AdministratorA-->AdministratorB: Send node URI
...
note left of AdministratorB
Administrator B registers node A
using the node URI.
end note
AdministratorB->NodeB: Register federated node A

== Node handshake ==
AdministratorB->NodeB: Initialize the handshake
note over NodeB #FFAAAA
Prepare the node's state for a
federated network.
end note

NodeB->NodeA: Request handshake
NodeA-->AdministratorA: Notify administrator A
note right of AdministratorA #ffffff
Administrator A should manually
approve the handshake.
end note
...
AdministratorA->NodeA: Approve handshake request
note over NodeA #FFAAAA
Prepare the node's state for a
federated network.
end note
NodeA->NodeB: Complete handshake
@enduml

Node identification

Outline of the node identification step of the node pairing process.

@startuml
skinparam responseMessageBelowArrow true

actor "Administrator A" as AdministratorA
participant "Node A" as NodeA
participant "Node B" as NodeB
actor "Administrator B" as AdministratorB

AdministratorA->NodeA: Register federated node B
note right of AdministratorA
Administrator A sends the node URI
to administrator B via a secure channel.
end note
AdministratorA-->AdministratorB: Send node URI
...
note left of AdministratorB
Administrator B registers node A
using the node URI.
end note
AdministratorB->NodeB: Register federated node A
@enduml

No authentication tokens are exchanged in during the identification step.

Node A administrator registers node B and generates it’s node URI: This step lets node A know about node B. The generated node URI identifies node A and is in the form of corteza://$NODE_ID_A:$OTT@$DOMAIN_A?name=$NAME.

$OTT is a generated OTT token that allows us to perform some authentication when performing the handshake.

Used variables

# Base URL of node A api
$API_A_BASE

# Main administrator JWT for node A
$MAIN_JWT_A

# Node A domain
$DOMAIN_A

# Node B domain
$DOMAIN_B

# Node name
$NODE_NAME

# Node A nodeID
$NODE_ID_A

# Node B nodeID
$NODE_ID_B

# Node URI
$NODE_URI

Example request

curl -X POST "$API_A_BASE/federation/nodes" \
  -H "authorization: Bearer $MAIN_JWT_A" \
  --header "Content-Type: application/json" \
  --data "{
    \"myDomain\": \"$DOMAIN_A\",
    \"domain\": \"$DOMAIN_B\",
    \"name\": \"$NODE_NAME\"
  }";

Example response

{
  "response": {
    "nodeID": "$NODE_ID_A",
    "sharedNodeID": "$NODE_ID_B",
    "name": "\"$NODE_NAME\"",
    "domain": "\"$DOMAIN_B\"",
    "status": "\"pending\"",
    "nodeURI": "\"$NODE_URI\""
  }
}

Node A administrator sends the node URI to the node B administrator: This step transports the node URI to the node that we wish to pair with.

This step is performed manually by the node A administrator. The two administrators should use a secure channel in order to exchange this information.

Node B administrator registers node A using the node URI: This step lets node B know about node A. Both nodes A and B are now identified and prepared to perform the Node handshake.

Used variables

# Base URL of node B api
$API_B_BASE

# Main administrator JWT for node B
$MAIN_JWT_B

# Node B domain
$DOMAIN_B

# Node A domain
$DOMAIN_A

# Node name
$NODE_NAME

# Node B nodeID
$NODE_ID_B

# Node A nodeID
$NODE_ID_A

# Node URI
$NODE_URI

Example request

curl -X POST "$API_B_BASE/federation/nodes" \
  -H "authorization: Bearer $MAIN_JWT_B" \
  --header "Content-Type: application/json" \
  --data "{
    \"myDomain\": \"$DOMAIN_B\",
    \"nodeURI\": \"$NODE_URI\"
  }";

Example response

{
  "response": {
    "nodeID": "$NODE_ID_B",
    "sharedNodeID": "$NODE_ID_A",
    "name": "\"$NODE_NAME\"",
    "domain": "\"$DOMAIN_A\"",
    "status": "\"pending\"",
    "nodeURI": "\"$NODE_URI\""
  }
}

In the above response, $NODE_URI contains the value provided by node A.

Node handshake

Outline of the node handshake step.

@startuml
skinparam responseMessageBelowArrow true

actor "Administrator A" as AdministratorA
participant "Node A" as NodeA
participant "Node B" as NodeB
actor "Administrator B" as AdministratorB

AdministratorB->NodeB: Initialize the handshake
note over NodeB #FFAAAA
Prepare the node's state for a
federated network.
end note

NodeB->NodeA: Request handshake
NodeA-->AdministratorA: Notify administrator A
note right of AdministratorA #ffffff
Administrator A should manually
approve the handshake.
end note
...
AdministratorA->NodeA: Approve handshake request
note over NodeA #FFAAAA
Prepare the node's state for a
federated network.
end note
NodeA->NodeB: Complete handshake
@enduml

Node B administrator initializes the process with node A: This configures the state on node B and generates the $TOKEN_B; so node A will be able to access protected resources on node B.

Used variables

# Base URL of node B api
$API_B_BASE

# Main administrator JWT for node B
$MAIN_JWT_B

# Node B nodeID
$NODE_ID_B

Example request

curl -X POST "$API_B_BASE/federation/nodes/$NODE_ID_B/pair" \
  -H "authorization: Bearer $MAIN_JWT_B" \
  --header "Content-Type: application/json";

Example response

{}

Node B sends a handshake request to node A: This notifies the node A administrator that node B wishes to establish a federated network. This request must be manually confirmed by the node administrator.

This request is authenticated by the before generated $OTT token, outside of the standard authentication facility.

Used variables

# Base URL of node A api
$API_A_BASE

# Node A nodeID
$NODE_ID_A

# Node URI
$NODE_URI

# Node B auth token
$TOKEN_B

# Node B nodeID
$NODE_ID_B

Example request

curl -X POST "$API_A_BASE/federation/nodes/$NODE_ID_A/handshake" \
  --header "Content-Type: application/json" \
  --data "{
    \"nodeURI\": \"$NODE_URI\",
    \"token\": \"$TOKEN_B\",
    \"nodeIDB\": \"$NODE_ID_B\"
  }";

Example response

{}

Node A administrator confirms the handshake request: This configures the state on node A and generates the $TOKEN_A; so node B will be able to access protected resources on node A.

Used variables

# Base URL of node A api
$API_A_BASE

# Node A nodeID
$NODE_ID_A

# Main administrator JWT for node A
$MAIN_JWT_A

Example request

curl -X POST "$API_A_BASE/federation/nodes/$NODE_ID_A/handshake-confirm" \
  -H "authorization: Bearer $MAIN_JWT_A" \
  --header "Content-Type: application/json";

Example response

{}

Node A completes the handshake with node B: This sends the $TOKEN_A to node B so it will be able to access protected resources on node A.

Notice how node A uses $TOKEN_B to authenticate this request.

Used variables

# Base URL of node B api
$API_B_BASE

# Node B nodeID
$NODE_ID_B

# Node B auth token
$TOKEN_B

# Node A auth token
$TOKEN_A

Example request

curl -X POST "$API_B_BASE/federation/nodes/$NODE_ID_B/handshake-complete" \
  -H "authorization: Bearer $TOKEN_B" \
  --header "Content-Type: application/json" \
  --data "{
    \"token\": \"$TOKEN_A\"
  }";

Example response

{}