Communication between applications and the Actcast Agent

Communication between applications and the Actcast Agent #

An application and the Actcast agent communicate via UNIX domain sockets. There are two types of communication: command and service.

Commands are communications that the Actcast agent sends requests and application returns responses. The path of the socket is designated by an environment variable ACTCAST_COMMAND_SOCK on the app’s startup.

Services are communications that application sends requests and the Actcast agent returns responses. The path of the socket is designated by an environment variable ACTCAST_SERVICE_SOCK on the app’s startup.

Protocols #

Commands and services both use a same protocol.

Connection is established on each request. The connecting peer closes the connection soon after response has receieved.

Request-response style protocol is used. This uses the simple dedicated text protocol.

Request - <Request ID> <command number or service number> <len> <data>
Response - <Request ID> <status> <len> <data>

where <len> is the byte size of <data>.

Status #

OK is for the success case and the others are for error cases.

Status	Number	Description
OK	0	Return successful value
Busy	1	Resources are busy and cannot respond soon
Unimplemented	2	The application doesn’t support the command
DeviceError	3	A device returned an error status / No device is found
AppError	4	Application specific error
GeneralError	5	Errors other than above

Command #

Command Number #

Correspondance of each command number and command is as the following:

Command	Number	Payload	Response
Take Photo	0	-	image data

Take Photo #

Take photo command is sent to the application when the user pushes [Take Photo] button in Web UI. The application must take photo with current settings then return that data. The response data must be in the format of data URL.

Example #

<- 1 0 0
-> 1 0 386 data:image/gif;base64,R0lGODdhMAAwAPAAAAAAAP///ywAAAAAMAAwAAAC8IyPqcvt3wCcDkiLc7C0qwyGHhSWpjQu5yqmCYsapyuvUUlvONmOZtfzgFzByTB10QgxOR0TqBQejhRNzOfkVJ+5YiUqrXF5Y5lKh/DeuNcP5yLWGsEbtLiOSpa/TPg7JpJHxyendzWTBfX0cxOnKPjgBzi4diinWGdkF8kjdfnycQZXZeYGejmJlZeGl9i2icVqaNVailT6F5iJ90m6mvuTS4OK05M0vDk0Q4XUtwvKOzrcd3iq9uisF81M1OIcR7lEewwcLp7tuNNkM3uNna3F2JQFo97Vriy/Xl4/f1cf5VWzXyym7PHhhx4dbgYKAAA7

Service #

Service Number #

Correspondance of each service number and service is as the following:

Service	Number	Payload	Response
RS256	0	Message	Signature

RS256 #

Signs the request message using RSA-SHA256 with the private key of the device and returns the generated sign. The payload and the responce are both base64url-encoded byte sequences. To verify the signature, you need to obtain the device certificate using Actcast API.

In actsim, it uses a randomely generated private key for each app’s launch instead of a private key of device.

Example of `RS256` and verification #

Consider the case that we produce a signature of the byte sequence Hello, Actcast!.

<- 1 0 20 SGVsbG8sIEFjdGNhc3Qh
-> 1 0 342 F9UfGKDAk0Xp7vPX029hJ4TGyXSkPX4LGFT4cKETUPH_nHrHWIzPvUtNDpgm52X_Ya9wb4mAa0eLV5QpjFq4wS0gIyToSJ6Ov-H8-CcxJHr_-caRLGj8ooRRBF6EbSiCCXj-rCyUme8uBybM5UAo235DUL2bvwf3U1LagLtGounK4chv1aEAFnjSfuhevyBCLegavSAKOMsL_7MCqVvI7XgB2vYJF-c5o2bP9Nt530AoYUAmIvdOxkiMzjaDlat0SNpE59gyu03JX7QQxQphs1TW0qMB42Rvm9Cia5wDsllLt3glwHiJI6xNsJQR_3lxyXzicl1CAl3EyGg51Gz1Hg

Here, the private key of the device is:

In this situation, we can get the following public key using Actcast API:

For example, we can verify the result of above RS256 as follows:

Get original data.

$ printf 'Hello, Actcast!' > test.txt

Get the public key.

$ cat <<EOF > public-key.pem
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAyOhtBJ2x7PJw59W1eY63
i4jab1N+tBO9q7Wmoq0AB0+914I9jJ/MNEpFpieOQGy+wi5OjNFzj5RZIHICWDkR
Bhsc0l18i+z3jcCoQq8JfFiy7EJVN/iNttE4Y1aRoARJlPM7DKNOydhphd5nU2RC
EFKcnPNFyjkB4S7a7QtVlqQuIQijSUG00HatGfSD3DKW7mgWrRqQY9mNUjqs2HaD
G9muoHJ8hpHN34QKfISusAmRuun92XGybus+mG1Tcj9vKVvpb8a381wxcCDTZOiA
HlCmNwnX/5sbLm8HNFmaBSZ3K0udAQTHXxnYBH5m6ksGuNiicxg0RzikHRBN0IYN
IQIDAQAB
-----END PUBLIC KEY-----
EOF

Get a sign from the return value of RS256. We modify the encoded data with oneliner. Note that padding depends on data.

$ echo F9UfGKDAk0Xp7vPX029hJ4TGyXSkPX4LGFT4cKETUPH_nHrHWIzPvUtNDpgm52X_Ya9wb4mAa0eLV5QpjFq4wS0gIyToSJ6Ov-H8-CcxJHr_-caRLGj8ooRRBF6EbSiCCXj-rCyUme8uBybM5UAo235DUL2bvwf3U1LagLtGounK4chv1aEAFnjSfuhevyBCLegavSAKOMsL_7MCqVvI7XgB2vYJF-c5o2bP9Nt530AoYUAmIvdOxkiMzjaDlat0SNpE59gyu03JX7QQxQphs1TW0qMB42Rvm9Cia5wDsllLt3glwHiJI6xNsJQR_3lxyXzicl1CAl3EyGg51Gz1Hg | tr -- -_ +/ | sed 's/$/==/' | base64 -d > signature.dat

Verify with OpenSSL.

$ openssl dgst -sha256 -verify public-key.pem -signature signature.dat test.txt
Verified OK

Target use case #

Consider the following case: We have an Actcast application and an API that the app depends on. Let us call it Web API. We want to send/receive data between Act and Web API. Moreover, we want to allow communications with “right” devices. For example, there are some use cases: to obtain confidential information like session token of AWS and to send data that an model in app like Act Log.

In these situation, Act should get an access token from Web API using RS256 and use it for the following requests. Web API should manage access tokens appropriately, e.g. using databasae. It is one of the best practice setting a short expiration time for access tokens. Act must not use the result of RS256 twice and must issue RS256 for each request because the device certificate can be revised without notice.

agent
 |   act
 |    | web-api
 |    |    | actcast-api
 |    |    |    |
 |<---x    |    | request an signature
 x--->|    |    | return an signature
 |    x--->|    | request access token using the signature
 |    |    x--->| request the public key of the device
 |    |    |<---x return the public key of the device
 |    |    x    | verify the signature
 |    |<---x    | issue an access token (with expire date, e.g. 4 hours)
 |    |    |    |
 |    x--->|    | send something using access token (use lightweight signature, e.g. hs256)
 |    |    |    |