Comment on page
This section describes basic and general information regards API references, access control, response and error codes.
Here are a few steps the developer should follow to achieve proper operation security of the Encedo HEM:
- First and foremost DO NOT leave your Encedo HEM unattended. We did our best to secure the device but the other side may have a multi-million dollar budget to break in. Do not make their lives easy by:
- making the Encedo PPA a personal device, attach it to the keychain or so;
- installing Encedo EPA in a professional data centre or server room with controlled and limited physical access.
- Always check the security of the TLS connection, do not ignore warnings or any other issues with TLS session security. This is critical to achieving the confidentiality of your data (e.g. during encryption/decryption) and of the JWT tokens. The consequences of leaked tokens can be tragic!
- If your application is using passphrase-based user authentication (user password) keep the runtime environment secure. Do not store passwords in the code (hardcoding)! For web apps remember that some browser plugins can record keystrokes and steal your password. Use the free Encedo Mobile AUthenticator over passwords if possible.
- Check the logs from time to time :) The logging mechanism of every security-related activity by Encedo HEM is a very powerful feature. Consider deep integration of the Encedo HEM logs with SIEM or other automated security monitoring tools.
- Temperature Operating Range: 0 - 85 'C
- Humidity: 10-90%
- Electrical Operating Range:
- Encedo PPA: USB 2.0 HighSpeed compliant 4,75V-5,25V, 100mA
- Encedo EPA: 230V/3A
Encedo HEM implements a classic CRUD (create-read-update-delete) type of API, RESTful HTTP(s) based API.
The API supports both HTTP (port 80) and HTTPS (port 443) protocols. However, some operations are limited to the HTTPS interface only. In general, all operations with access control are limited to HTTPS only.
The API parameters, send as body parameters, are represented via JSON objects with the required
Content-Typeheader send altogether. The reply (response body) is also a JSON encoded object. The missing
Content-Typeheader will fail the API call.
On factory-default (so-called 'fresh', not initialised) devices firmware and management applications can be upgraded over the HTTP interface, This is possible due to the fact the uploaded file is digitally signed and before the installation, the integrity and the signature will be validated.
The API is stateless.
All API reference endpoints refer to a domain
my.ence.do. This domain is a default domain for Encedo PPA and is used here as a reference. After personalization, the device might be available under custom domains, as regards user preferences.
Depending on the version (Encedo PPA or EPA), access to the device is slightly different. In both cases, it is the same web API (EPA do not have a few endpoints as noted in the API Reference), but the domain is different.
The Encedo PPA in the factory default state (fresh, just delivered or after wipe-out) serves API over the domain
my.ence.doresolve to the IP address
The Encedo EPA (delivered for on-premises installations) in the factory default stated is available under the technical domain presented in the Delivery Note. Assume the Delivery Note states in section Setup Details the technical domain is
*.e400123-a1.cloud.ence.dofor node A1, the Encedo HEM (chips) are accessible under domains
c10.e400123-a1.cloud.ence.do. For node B2 it will be e.g.
The Encedo EPA subscribed in a SaaS model (user can get access to just one HEM chip) will present the configuration (and domain) in the email sent to the buyer as a summary of the subscription.
After the device is initialized, it will be available under the domain selected by the user during the initilization procedure.
If you encounter any troubles using API, read the API reference carefully. The response code may say a lot :)
The second stop should test if the TLS server is working. The certificate may expire if the device is not used for longer. The renewal process is automatic. All you need is to perform a complete check-in procedure and reboot the HEM (called over HTTP protocol).
The check-in process is a simple challenge-response protocol between the Device (issuer of the challenge message) and the Backend (issuer of the response message). The idea for this process is as follows:
- the device needs a trusted source of the real-time clock (RTC) a'ka trusted source of time;
- the device stores (as trusted) the list of backend public keys so it's able to validate the response (the integrity and origin),
- the backend can send information about new firmware version availability,
- updated x509 TLS certificate can be sent over;
- it is possible to implement Remote Management;
- the process was designed with privacy-focused
For daily usage, the primary purpose of this procedure is to set up a Real-Time Clock (RTC) inside the device. The time is unknown after every power-up (or reboot) of the device but is critical for authentication. So the application should check if an RTC is set, if not - the API will return 403 on every authentication call.
The check-in process was designed with privacy in mind. The backend is unable to trace the device in any domain. Every transaction (
checked) is anonymous from the backend point of view.
The mechanism IS able to offer enterprise-level of remote management of the devices deployed in the organization. Remote management is based on uploading the
instanceidvalue uniquely identifying every instance of Encedo HEM (
instanceidis generated as a result of personalization).
checkcheck-in challenge string (after decoded):
<base64 encoded SHA256 hash>
Example checked check-in reply string:
<base64 encoded SHA256 hash>
There are three user roles, each with different access role and limitations:
Local User: A regular passphrase-based authenticated user, general usage.
Administrator: Master user, limited usage to rescue purposes.,
Remote User: A user authenticated by an external authenticator (e.g. Encedo Mobile AUthenticator available on Google Play and Apple AppStore).
Check the API Reference section for more details about when and how user roles enter the game for each and every endpoint. Rember, some endpoints are wide-open and have no useful role control or access control.
Access control is accomplished by JWT tokens sent via the Authentication header with every API endpoint call. User role is encoded in the JWT body by object sub. For Local User, it's pointing to 'U', for Administrator to 'M' and for Remote pointing to KID of registered authenticator.
The general roles are as follows:
- a few endpoints are wide-open (access control relaxed),
- most endpoints required strict access control based on access scope and user role, and finally,
- some of them have implemented weak access control, and just need a valid JWT token.
Initialization argument init is a slightly modified JWT token. The modification is as follows:
- the header has a new object
ecdhindicating the JWT hash secret is a result of the ECDH algorithm, here
- the arguments to the ECDH are in a body part, those are the
iss(issuer or sender) and the
aud(audience or receiver) objects
- the signature is indicated by the
HS256a'ka SHA256) where the secret is a result of
ECDH(iss_privatekey, aud)(issuer private is confidential, in the body public key part is sent, the
audis just a public key part - receiver can be validated, if she is a legitimated receiver
"user": "John Doe",
<base64 encoded SHA256 hash>
A few comments are needed here:
- the object inside the
cfgobject are common with the Configuration endpoint (the same names, meanings, and allowed values);
masterkeyobject, like the
userkeyobject is an Administrator public key (curve25519),
expare the same and were returned by Phase1 of the Initialization process (
issobject is a duplication of the
masterkeyobject (a requirement of the implemented modified version of JWT as commented above);
- the whole JWT token is signed (HS256) where the secret is a result of ECDH between the
aud(public key) and the
Encedo HEM has implemented an advanced logging mechanism. Every security-related event are been logged. This includes failed access control, all key management operations and all operations of keys and secrets. The log file itself has built-in security measures against tampering or integrity violation.
This is a list of all possible API response codes and their meaning:
Let's make it straight - you need working examples, right?.