TSS Node callback

​

TSS Node callback mechanism

After the successful setup of the TSS Node, it will automatically establish a connection with Cobo Portal and await tasks sent by the Cobo Portal backend. Currently, there are three task types: key generation (KeyGen), transaction signing (KeySign), and soft key recovery (KeyReshare).

In cases where the callback mechanism is not configured, the TSS Node promptly executes each task upon receipt from the Cobo Portal backend. If the callback mechanism is enabled, the TSS Node sends an approval request to the callback server upon task reception. Task execution occurs only upon approval from the callback server.

The communication between the TSS Node and the callback server utilizes the HTTP protocol, and Cobo Portal implements JSON Web Token (JWT) signed with the RS256 algorithm. For more information on JWT, please click here.

• During TSS Node initialization, both the TSS Node and the callback server generate and configure an RSA private/public key pair.
• Upon task reception, the TSS Node constructs a CallbackRequest and generates a JWT token using its RSA private key. This request is then sent to the callback server via the HTTP POST method.
• Upon receipt, the callback server validates the JWT signature using the TSS Node’s RSA public key. It constructs a CallbackRequest and signs it using its RSA private key before sending the JWT back to the TSS Node.
• Upon receiving the HTTP response, the TSS Node validates the JWT signature using the callback server’s RSA public key.
• Once validated, the TSS Node executes or rejects the task based on the response received from the callback server.

​

Callback server requirements

​

HTTP API

The callback server operates as an HTTP server with the following supported endpoints:

• Path: /v1/check
• Method: POST
• Body: Encoded with x-www-form-urlencoded

​

HTTP request parsing

The callback server will send HTTP Request in the following manner:

• Generate CallbackRequest.
• Serialize CallbackRequest to derive CallbackRequestJsonString.
• Utilize CallbackRequestJsonString as the JWT payload and sign it using its RSA private key to create a JWT.
• Submit the HTTP POST request via an HTML form with TSS_JWT_MSG as the key and JWT as the value.

The callback server will process the HTTP Request in the following manner:

• Retrieve the data in the HTTP POST request using TSS_JWT_MSG as the key and the JWT as the value.
• Use the TSS Node’s RSA public key to validate the signed JWT.
• Retrieve the payload in the JWT and deserialize it using CallbackRequest.
• Deserialize the meta field to retrieve the information in the request.

​

Risk controls

For each CallbackRequest, it is essential to conduct a risk control assessment in accordance with your organization’s security requirements. This step is crucial to ensure the validation of the request.

​

HTTP responses

The callback server will structure and send the HTTP response in the following manner:

• Generate CallbackResponse.
• Serialize CallbackResponse to derive CallbackResponseJsonString.
• Utilize CallbackResponseJsonString as the JWT payload and sign it using its RSA private key to create a JWT.
• Use the JWT as the HTTP response and return it to the TSS Node.

​

CallbackRequest descriptions

When request_type is equal to TypeKeyGen, the structure of request_detail is as follows:

The structure of extra_info is as follow:

When request_type is equal to TypeKeySign, the structure of request_detail is as follows:

The structure of extra_info is as follow:

The structure of ToAddressDetail is as follows:

The structure of extra_parameters is as follows:

The structure of input is as follows:

The structure of TransactionTypeEnum is as follows:

The structure of TransactionOperationEnum is as follows:

When request_type is equal to TypeKeyReshare, the structure of request_detail is as follows:

The structure of extra_info is as follows:

​

CallbackResponse descriptions

​

Callback server examples

Cobo Portal offers callback server examples in various programming languages. You can refer to these examples to swiftly deploy a callback server. Alternatively, JWT code libraries are available for multiple programming languages. You can refer to JWT’s official website to deploy a callback server.

​

Callback server configuration

On the server where the callback server is deployed, you’ll need to complete the following configurations.

1. Generate the callback server’s RSA private key.

openssl genrsa -out callback-server-pri.pem 4096

2. Export the callback server’s RSA public key.

openssl rsa -in callback-server-pri.pem -pubout >callback-server-pub.key

3. Copy the exported RSA’s public key (i.e. the callback-server-pub.key file) to the server where the TSS Node is deployed.

4. Copy the RSA’s public key of the TSS Node to the config files of the callback server.

   • If you are using the callback server codes provided by Cobo Portal, refer to the configuration instructions provided in the samples.

5. After successfully completing TSS Node initialization, use the following command to query the RSA’s public key of the TSS Node:

sudo ./tss-node.sh info

The output example is as follows.

INFO[2022-12-14T07:09:44Z] Callback public key:

-----BEGIN PUBLIC KEY-----

MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEA4ki4fHY4/oSJOYBxBUI1

GUdLCUF7wMFYlfkpI/bSf7fGvzaygtZdORG6OR4vAoKxvqK/ZbJITMR5rS7pNxOv

vpLbsdVfJZGQn6wW8wLEx9ZB18JXt99oTESaxzoxMteXBC6tgYqWhSS386LfjSxQ

a4EvPunTRdYrO9VmnDWHM06/c76UxcS038pJ4OByXx7sH0xzS4MZQhZWyfYkqBT2

Ym9g46VXQ+CVZyWYXKPMyGPVTR1979lfJ1bFpYADNU3YUSK1mq0xaH9lQORFBs6/

0kK8m27BGR7h59rFJGgeZ2SNGzcEmiAp7rjOtFpLj1OmNXtjGhTxpn8omBrdH86+

qZfKsIm+O84e9S7uPMnx9hIpJHTcPoseW0d+WBoNplJQg22LUswPwaVgSHMB2U1B

aFkEzMAkRmGIejlMG25uYaVlA0Mf9E+/JaZSGPVuq43lhHCE08pNxGrak6/vTPTv

jAM449yTHrjDCDrFk/LdHqk5Ipt0b9CeHbCsQSs4BxHlDp2GEBJn1OEiizDwScWb

YiFi3a6PAvqDO56KEUFMXpC8CzgJ8svmQoldIAWSKGpdnuxUMcD+glCsi7K7+FI+

HDepO/4ejCm9DzuTUHG4PE0Ymb3PV8cZbLlGSZD/yG1541/xlHmzlOpAa8OdZBfb

s8wADQvpbJTyPkkMyq/i5SkCAwEAAQ==

-----END PUBLIC KEY----- 

​

TSS Node configuration & callback server startup

​

TSS Node configuration

On the server where the callback server is deployed, you’ll need to complete the following configurations.

1. Copy the callback server’s RSA public key file to the configs directory of the TSS Node.

cobo-tss-node-generic

├── configs

│ ├── callback-server-pub.key

│ └── cobo-tss-node-config.yaml

2. Modify the cobo-tss-node-config.yaml file.

   • cb_server

     • service_address indicates the callback server address.
     • pubkey_path indicates the file path of the callback server’s RSA.

   • token_expire_minutes indicates the timeout period of the JWT (unit: minutes).

   • retry_time indicates the number of retries if the callback request fails.

   • sleep_seconds indicates the time interval between each retry (unit: minutes).

You can configure multiple callback servers. The following output uses two callback servers as an example:

callback:

cb_server:

- service_address: http://callback-server-01:8080/v1/check

pubkey_path: configs/callback-server-pub-01.key

- service_address: http://callback-server-02:8080/v1/check

pubkey_path: configs/callback-server-pub-02.key

token_expire_minutes: 2

retry_times: 60

sleep_seconds: 60

After completing the aforementioned configurations, you can initiate the startup of both the callback server and the TSS Node.