H200 Enable Enterprise Local Management (EELM) Server with enhanced security

Introduction

The H200 Enable Digital Signage Media-Player/Set Top Box, has a configurable Management service (EELM) which supports a small set of operations accessible via a REST API.

This REST API provides similar functionality to the Aminet STBremoteconf tool which was available with the legacy Aminet (x4x/x5x) STBs as well as some H200-specific operations. For security reasons, the EELM interface can be limited to people with special access only, and it is protected by HTTPS connection with client authentication.

Prerequisites

Minimum Firmware Version: 23.5.2022.9R

Note: Please make sure that your Linux machine has Openssl installed.

Generating Self-signing certificate

To use EELM external API with your own certificate, first you have to create your own CA cert and CA key in pem format as described below:

1. Create the CA Key in pem format with 2048 bit

openssl genrsa -out rootCAKey.pem 2048

2. Create the CA cert in pem format (you can adjust the "-days" option for your own needs)

openssl req -x509 -sha256 -new -nodes -key rootCAKey.pem -days 3650 -out rootCACert.pem

You may be prompted for extra information as shown below but these parameters do not affect the self-signing progress

Country Name (2 letter code) [AU]:
State or Province Name (full name) [Some-State]:
Locality Name (eg, city) []:
Organization Name (eg, company) [Internet Widgits Pty Ltd]:
Organizational Unit Name (eg, section) []:
Common Name (e.g. server FQDN or YOUR name) []:
Email Address []:

After that, run the following command to generate the self-signed key and self-signed cert:

3. First generate a self-signed key using "genrsa"

openssl genrsa -out selfsigned.key 2048

4. Second, use the self-signed key to generate a Certificate Signing Request "selfsigned.csr"

openssl req -new -key selfsigned.key -out selfsigned.csr

5. At last, using the signing Request "selfsigned.csr", the CA keys "rootCAKey.pem" and "rootCACert.pem" generate your self-signed cert "selfsigned.crt"

openssl x509 -req -in selfsigned.csr -CA rootCACert.pem -CAkey rootCAKey.pem -set_serial 100 -days 365 -outform PEM -out selfsigned.crt

Now you have a key: "selfsigned.key" and cert: "selfsigned.crt".

STB ini option setting

1. If you want the H200 EELM feature to be active you must enable it by setting the following ini option

eelm.enable

There are 4 option for using EELM

(for only allowing the API call with certificate, please use option 3)

The available options for enabling EELM are:

    0: Disable (Default). Only allow connection from localhost

    1: Allow both HTTP and HTTPS connection without client authentication.

    2: Allow HTTPS connection without client authentication.

    3: Allow HTTPS connection with client authentication.

2. Then, you have to specify the certificate that will be used by the STB with the following parameter:

eelm.trust_store

Then use a converted PEM string (without new line) to specify the certificate to be used for client authentication.

The selfsigned.crt needs to be in single line string form.

To convert the content of "selfsigned.crt" into single line string, you can use the following command

awk 'NF {sub(/\r/, ""); printf "%s",$0;}' selfsigned.crt

Verifying the STB setting

You can verify the setting, cert and key by curl. Assume your STB IP is 10.0.35.167:

Please run the following command

curl -k https://10.0.35.167:10444/

As this command did not involve the cert and key you signed before an error is expected:

curl: (35) error:14094410:SSL routines:SSL3_READ_BYTES:sslv3 alert handshake failure

Now, please add --cert and --key as below and curl again.

curl -k https://10.0.35.167:10444/ --cert selfsigned.crt --key selfsigned.key

If your ini setting, self-signed key and cert are correct and the STB EELM is running as expected the response below result is expected.

STB Management is running.

Example API Call

There are many EELM APIs to use, below are 2 examples

1. Getting API document in yaml format

Command:

curl -k https://10.0.35.167:10444/api/v2/openapi.yaml  --cert selfsigned.crt --key selfsigned.key

Result should look like:

openapi: 3.0.0
info:
title: Enable Enterprise Local Management Server
description: |
This REST API provide several remote control and management
operations on the H200 Enable Enterprise Media Player
version: 2.1.0
........
Applications:
type: array
items:
$ref: "#/components/schemas/Application"

2. Retrieves serial number in the format of {product number}-{device serial}

Command:

curl -k https://10.0.35.167:10444/api/v2/device/serialNumber --cert selfsigned.crt --key selfsigned.key

Result:

{"serialNumber":"107-10877528"}