User Stories

High level diagrams

Manufacturing process

Detailed flow

Details of logging in with JWT

Sequence overview

1. STB client Client calls the Entone API to get a signed JWT token
2. STB client calls the Move STB Authentication endpoint with the token and the public key

3. Move API verifies the supplied public key by checking against a stored (trusted) version of the Entone  public key

4. Move API verifies the JWT with the public key
5. Move API matches the supplied STB serial number to the user
6. Move API logs in the userJWT used for logging in
7. Client sends login JWT token to Middleware
8. 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://domain.tld/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://booxcustomer.fidomain/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": "DNA-STB0001",
	"user": {
		"id": "10001",
		"email": "stb_user@dnastbuser@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://booxcustomer.fidomain/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

Add New User Account

This API is used to add a new user account. Following rules apply:

• Email address or customer-id should not belong to any customer that is not in DELETED state; otherwise API will return an error.
• If the user with that email exists in DELETED state and his grace period is not expired, his previous registration state is restored.
• A new user is created in UNREGISTERED state.

Design Points (to be considered for future):

1. The main problem with making the two pin params as mandatory is that this feature is very specific to DNA requirements, while other frontends don't expect them. Therefore, we need a way so that both parties remain happy by giving a better design
2. For that we should make it configurable whether the two params are mandatory. So for DNA we will configure them as mandatory, so that if they are not provided by Visio when creating a new user API will return an error to provide the mandatory input param. While for others e.g. Delta we will configure them as optional so that if they don't provide the params, API will successfully create a user and set the pins in DB as NULL (empty). Also until DNA is not ready for the params to be mandatory we can keep it configured as optional for them
3. It is easy to implement from effort point of view and much flexible and reliable

Request

Query Strings

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

Error Codes

Edit Existing User Account

This API is used to suspend or activate a user account. It can also be used to change the email or customer-id of an existing account. Following rules apply:

• A user in DELETED state is not updated.
• "email" and "cid" parameters should not belong to any existing user, even if the user in in DELETED state
• If a user is suspended, his state is changed to DISABLED
• If a DISABLED user is activated and grace period has not expired, then previous registration state is restored, otherwise his state is changed to UNREGISTERED
• In other cases, if a user is activated, his state changed to REGISTERED.

Request

Querystrings

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

Number with the length of 4.
e.g. 8798 

Error Codes