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.

Figure 1. Outline of the entire node pairing process.

Node identification

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

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

Figure 3. Outline of the node handshake step.

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

{}