User Stories

High level diagrams

Manufacturing process

Detailed flow

Details of logging in with JWT

Sequence overview

1. Client calls the Entone API to get a JWT used for logging in
2. Client sends login JWT token to Middleware
3. Middleware responds with two tokens that can be used to authenticate future requests

This is diagrammed in the section "user login" above.

Entone API

The View team will add a new function to the API with the following signature:

String ENTONE.stb.createJWT(algorithm, claim) 

Where claim is a object containing the payload of the JWT, algorithm is the mechanism to sign the signature.

The returned string is a JWT which is based64 encoded string. 

Parameters to pass to Entone API

The algorithm must be one of the values supported as the "alg" parameter in the JWT spec (here).  The only algorithm supported is RSA with sha-256 and so the algorithm parameter value should always be "RS256".

The client MUST use this format for the claim object:

$claim = [
    "iss"                => "EntoneAPI",
    "iat"                => time(),
    "exp"                => time() + TEN_MINUTES,
    "aud"                => "www.aminocom.com",
    "sn"                 => "Serial number 25-1234567",
    "cdsn"               => "Client Device-allocated Serial Number 48318382081",
    'certificate'        => "String containing the STB public key"
    'batchCACertificate' => "String containing the STB batch CA certificate",
];

It will receive a JWT from EntoneAPI and must then call the MoveAPI endpoint as below.

Example of generating a JWT

let passwordlessLoginHandle = null;
export const passwordlessLogin = async () => {
  if (!ENTONE) {
    return Promise.reject();
  }

  // Combine concurrent login requests
  if (passwordlessLoginHandle) {
    return passwordlessLoginHandle;
  }

  const now = sdk.time.get();
  const claim = {
    iss: "EntoneAPI",
    iat: now,
    exp: now + 60 * 10,
    aud: "www.aminocom.com",
    sn: ENTONE.stb.getFullSerialNumber(),
    cdsn: ENTONE.system.getIrdetoCDSN() || "",
    certificate: ENTONE.stb.getPublicKey(),
    batchCACertificate: ENTONE.stb.getBatchCACertificate()
  };
  const token = ENTONE.stb.createJWT(ENTONE.stb.ALG_RS256, claim);

  passwordlessLoginHandle = sdk.user.stbLogin(token);

  try {
    const user = await passwordlessLoginHandle;
    setUserCallback && setUserCallback(user);
    passwordlessLoginHandle = null;
  } catch (error) {
    passwordlessLoginHandle = null;
    throw error;
  }
};

window.passwordlessLogin = passwordlessLogin;

What is the STB serial number?

Amino STBs with Irdeto Chipset contain several identifiers, two of them are:

1. SN - basic serial number (printed on the STB) (73-2345532)
2. CDSN - secure SN, which is stored on the device. STB UI gets it via Entone JS API, sends it to Amino backend. Entitlements with Irdeto are based on this identifier (6454386863). This is device id.

The basic STB serial number is composed of two parts: the hw model prefix and the ESN. e.g. 87(hw model)-6593553 (ESN). and the mac address is derived from the ESN of the STB.

MoveAPI

Endpoint

https://domain.tld/api/stb/auth

Validation rules

The MoveAPI must validate the JWT as follows:

1. Decode the JWT
2. Retrieve the supplied public key from the "certificate" claim
3. Retrieve the suppled CA certificate from the "batchCACertificate" claim
   1. If it is omitted then read the CA certificate for batch 0133 from disk
4. Verify that:
   1. The issuer is EntoneAPI
   2. The audience is www.aminocom.com
   3. The token has not expired
   4. The token was issued in the past, or otherwise within a tolerable window to allow for server time drift
   5. JWT was signed with the key you obtained in step 2
5. Verify that the CA certificate is signed by the Entone CA certificate
6. Obtain the "sn" claim
7. Find the user associated with the STB serial code indicated in the "sn" claim

It is important that the JWT is signed with the supplied key AND that the key was generated from the Entone root CA

Response

The Move Middleware will respond with two JWT tokens that can be used for authentication in future requests.

{
 "jwt": "jp0cnVlLCJjb21wYW55IjoiVG9wdGFsIiw...",
 "jwt_expiry": "Fri, 04 Dec 2015 16:01:07 +0000",
 "refresh_token": "WkiUzKELZ49eM7oWxAQK_ZX...",
 "refresh_token_expiry": "Fri, 04 Jan 2016 16:01:07 +0000",
 "client_keystore": "MIIKwIBAzCCoYCSqGSIb3...",
 "serial_no": "615500266162",
 "chipset_id": "8c10d4de5760",
 "mac": "8C10D4DE5761",
 "user_id": "email@example.com"
}

Refreshing the access token

The JWT is valid for an hour, configurable at deployment time. The client should use the refresh token to obtain a new access token when access token is expired or about to expire.

This can be done by calling

POST https://boox.fi/api/stb/auth/refresh_token?refresh_token=123abc...

The refresh token should be supplied as a query string parameter.

The API will respond with a new access token and refresh token

Logout STB

API to handle logout request of STB

Request

POST

https://customer.domain/api/stb/logout

POST Body

Please note that M is for Mandatory and O is for Optional. 

service_token

Headers

Please note that M is for Mandatory and O is for Optional.

Authorization: Bearer

Response

Link STB to a User

After user bought a STB this API need to be called. This API link or grant ownership of a STB to a user.

Request

POST

https://boox.fi/api/management/stb/link_user

POST Data Parameters

Please note that M is for Mandatory and O is for Optional.

serial_no

email

public_keys

Response

	"id": "123",
	"serial_no": "STB0001",
	"user": {
		"id": "10001",
		"email": "stb_user@example.com"
	}
}

{
  "error" {
    "code": 9,
    "text": "Access to this resource is locked to IP addresses"
  }
}

Error Codes

Unlink STB from User

This API remove ownership of a STB from an user. Use cases: when user sells his/her device, when a device got stolen. 

Request

POST

https://customer.domain/api/management/stb/unlink_user

POST Data Parameters

Please note that M is for Mandatory and O is for Optional.

serial_no

email

Response

{
  "error" {
    "code": 9,
    "text": "Access to this resource is locked to IP addresses"
  }
}

Error Codes