Introduction

The H200 Enable Digital Signage Media-Player/Set Top Box, has a configurable Management service (EELM) which supports a powerful set of operations accessible via a REST API.  The API's enable programmatic control of the target devices with functions ranging from upgrading firmware, to controlling the volume, power state, and even send commands to connected Televisions to change source inputs and much more.  Please see the References section for links to the published APIs.

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 H-series-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

The instructions below assume that you are using a Linux PC with OpenSSL installed. If you do not have access to a separate Linux PC, installing a Linux distribution in Windows using Microsoft’s Windows Subsystem for Linux (WSL2) is a good option.  (instructions on installing Linux on Windows is outside the scope of this article)

The following INI parameters must be configured: 

eelm.enable

This parameter has 4 options

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.

eelm.trust_store

eelm.trust_store must also be configured if eelm.enable=3, enabling client authentication. This allows you to specify the certificate that will be used by the STB in the authentication process. Details of how to generate the certificate and to set the eelm.trust_store option are given below.

 

Summary

This article shows how to configure and use the EELM API on Amino H-Series media players. The focus of the article has been on getting started and correctly configuring a device and the EELM API contains many more feature and is being continuously extended. The full range of APIs can be seen in the openapi.yaml file and viewed in Swagger and is also published in our developer documentation linked from the References section below.

 

Generating a Certificate and Configuring it for EELM

The steps in this section are only required if you are using HTTP connection with client authentication, eelm.enable=3. If you have selected any other options you should skip to the section ‘API Usage and Examples’.

First you must 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

Note: - the user may be prompted for ‘extra’ attributes including a ‘challenge password’. This is intended to be used by Certificate Authorities to authenticate the certificate own but as this is a self-signed certificate it does not have any function and can safely be left blank.

5. 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

Please ensure that this configuration is appropriate for your use case. Particularly note that the example will generate a certificate which will expire after 365 days after which authentication will fail. 

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

 

Specifying the Certificate to use with the trust_store INI parameter

We are almost ready to configure the API to use our certificate but our selfsigned.crt file must first be converted into a single line PEM string. This is achieved with the following command: -

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

The output of this will be a string (without new line characters) delimited by -----BEGINE CERTIFICATE----- and -----END CERTIFICATE-----. This is the value which should be used for the trust_store parameter eelm.trust_store

For example

eelm.trust_store= -----BEGIN CERTIFICATE-----MIIC/DCCAeQCAWQwDQYJKoZIhvcNAQELBQAwRDELMAkGA1UEBhMCVUsxEzARBgNVBAgMClNvbWUtU3RhdGUxEDAOBgNVBAcMB0JlbGZhc3QxDjAMBgNVBAoMBUFtaW5vMB4XDTIzMTIxOTEwMDUyNVoXDTI0MTIxODEwMDUyNVowRDELMAkGA1UEBhMCVUsxEzARBgNVBGBdIU0NkXtr16xxETYCWklU0Vqy8tsup9SV85b1YKjdH92GIZdl9KCCUwK6PQV4+zHHMAClFx4dsXMjhEjFwRHli7q6njwUUI93qUMXYIQgvo9rMoKCiH4PxED0nlzeN75cz16/yDVrj2Bm8yoVE21rJJlxg9sn1bdPIRBWFyXx/vEsmAgGPM3SW3VQKgK3N7udMiIyTQaYJexosAaX1VKPhBtUM/MajUoduE4cSlrZFtpBcCH5LtSXDC6FPvMomH9KUKj5DLdDcynb2BRJr0/TMwrwVO3BPq4do+xQoLpAbIB/iX8/CCECDeUoXDQIDAQABMA0GCSqGSIb3DQEBCwUAA4IBAQBnHYI2n9Kd0mchKTXGq7+x0o4+waiuQp2gkVgiaLt2ooxaE+8vmHSZOtS7kgJg2pVm/OTAB4hvaGZ/Ax3Grm78k1Lsab/4EkF62NGWiKE7pIsYXMZJUiAqGofsgkBRRvW1l214eHtqZENnMMTAoy2j1PnokpN8cqf3NXKObmVM9RFrGR2hPl4lr5nAXOGZMVm/c3UZYvWOpPpVTzblweq7GjchAIG51fkELEnwiSEkpO05FaXfx8ko/CsltPPNkeHr61F9Udv172UgeWFxvYoKmkKD0KsT80ws/co9mzOIgOjNQUIisWnFunqgiFpvKhAlFCFarb/+Q7F4dttxoctf-----END CERTIFICATE-----

Note: the above text is given as an example and IS NOT a valid certificate. It cannot be used to shortcut the above previous steps.

 

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 use the cert and key you signed before an error is expected:

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

Next add --cert and --key as below and use curl once 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 API has been setup to use Client Authentication the response below will be given.

STB Management is running.

 

Configuring your browser to enable you to use Swagger Client Authentication

To use browser based tools such as Swagger (described in the next section) to test the API when Client Authentication has been configured it is necessary to install a keystore file in your browser so that the communication is trusted.

The first step is to generate a keystore file from the self-signed key and certificate which you created previously. To do this you should run the following command.

openssl pkcs12 -export -in selfsigned.crt -inkey selfsigned.key -name 'MyMediaPlayerKeyStore' -out keystore.p12

You will be prompted to choose a password which you will need in the next step of the process.

In the browser which you intend to use to test the API you must install the keystore you just created. How you do this in each browser will be different, the example given below is for Chrome.

Click the three vertical dots at the top right of the browser window to show the main menu and select Settings. Navigate to ‘Privacy and Security’ then ‘Security’ and select ‘Manage Certificates’ under the ‘Advanced’ section. The following dialog box will be displayed.

Click the Import button and select the keystore.p12 file which you created previously. The browser will take you through a number of steps to import the file including prompting you for the password you used when creating the .p12 file.

 

API Usage and Examples

Amino uses openapi to define all http and https APIs. This means that you can use freely available tools such as swagger.io to try the API and learn how it works before you begin to integrate with other systems. 

This section demonstrates how to get started using Swagger.io but for users who wish to use ‘curl’, Swagger also generates the sample curl commands so we recommend you follow these instructions to get started. A few examples are given, using curl, at the end of the section.

 

Prerequisites

To execute API calls directly from the Swagger UI in your browser the Media Player IP address must be reachable from the PC running the browser.

If this is not possible, Swagger is still a useful tool as it shows the correctly formatted ‘curl’ commands which can then be used from another device that has connectivity.

 

Steps

First you must get the apenapi.yaml file for your device. This file uses the openapi specification to define the API and so can be read by other systems. The best way to do this is to download this file directly from your device as it guarantees you have the correct version of the file for the build you are using. The following command will download the file to your browser Downloads folder: -

1. Open this URL with your web browser: 

http://<IP_OF_H200>:8090/openapi.yaml

Or, if you are using Client Authentication the URL will be:

https://<IP_OF_H200:10444/openapi.yaml

Note that your browser may display a warning to say that your connection is not private. Select the Advanced option and Proceed to the address which will be shown as unsafe. You will be prompted to select the certificate to use.

2. Next, again in your browser, go to https://editor.swagger.io/

3. Copy and paste the content of the openapi.yaml to the left panel and you will see the following screen

4. Select either the http link from the servers drop down if you are not using Client Authentication or the https link if you are using Client Authentication

5. Input the IP of your STB in the host field

6. Scroll down the right panel and choose the API which you would like to try

7. Click the API and it will expand to show the API details. A sample request body is shown and if you click ‘Try it Out’ you can edit the parameters of the API call before Executing.

8. Having clicked Execute, Swagger will also show the equivalent ‘curl’ command which can be pasted into a terminal window or used in other tools.

 

API Examples using Curl

If you have followed the steps above you will have seen that Swagger also generates a correctly formatted ‘curl’ command line which can be simply pasted into a linux terminal to execute the same API.

For example

Choose an API to test, we’ll use /device/serialNumber to retrieve the serial number from the media player

1. Click the "Try it out" button for the selected API

2. Click the "Execute", and it will generate a sample curl command as shown below

3. Copy the full text of the curl command box into a terminal and execute the comment. Not that Swagger will replace the IP address in the curl command with the IP address you entered previously in the ‘host’ text box.

This will return the serial number of the device in a JSON string.

{"serialNumber":"107-10877528"}

Note that this example assumes that Client Authentication is not enabled. If you have followed the above steps to configure client Authentication then you must specify the certificate and key in the curl command as shown below

curl -key --cert selfsigned.crt --key selfsigned.key \ 
-X 'GET' https://10.0.7.215:10444/api/v2/device/serialNumber -H 'accept: application/json'

 

References

Enable Enterprise Local Management (EELM) APIs Home