Security details

We take security seriously. Therefore, we have implemented different security measures to protect our system as well as the integrators’ ones.
This topic explains them briefly.

ekey bionyx cloud (ekey bionyx REST-API server)

The ekey bionyx cloud itself is the third-party integration API server and implements different measures to ensure a sufficient security level.

ekey bionyx cloud API authentication

This API uses OAuth 2.0 to authenticate the logged-in user and only allows TLS-secured HTTPS connections.
The integrator’s client can therefore use an industry standard protocol to authenticate against ekey bionyx.

ekey bionyx cloud API credential protection

Your system has to authenticate the API requests we are sending to it.
For this you have to include some kind of authentication in it, e.g. an access token. For further details, check the following link.

Of course, anyone knowing this access token could trigger functions in the integrator’s system.
Therefore, all that is necessary to prevent this should be undertaken.

Firstly, we recommend that integrators only issue and forward tokens to our system with the minimum necessary permissions.
This implementation of the least privilege principle could limit the damage - even if the tokens are leaked.

Secondly, we do not store the tokens unencrypted in the cloud.
Instead of that, we use our end-to-end encryption (between embedded device and mobile app with key exchange via BLE at onboarding) and asymmetric cryptography to lock the cloud out (in addition to our default storage encryption).

Even if we had some kind of data breach in the cloud, the data would be encrypted by a key that only the customers’ systems have. A nice side effect of this is that ekey is not only organizationally (access restrictions) but also technically hindered from accessing the user’s access tokens.

As soons as the smart home integration is activated, the app generates an asymmetric key pair, encrypts the private key with the end-to-end key or sys-key and stores the public and the encrypted private key in the cloud. After that the integrator could add API requests with sensitive information. The cloud encrypts those with the public key at the moment they arrive - and before they are stored to permanent storage. If the calls are assigned later, the mobile app downloads the encrypted API requests as well as the encrypted private key in order to decrypt the API request. After that it builds the rule logic and sends it to the affected ekey bionyx embedded devices using an end-to-end encrypted channel so that the cloud cannot read or change it.

This is also one of the reasons why you cannot get the complete HTTP request definition via our API - the ekey bionyx cloud cannot access it.

ekey bionyx embedded device (API client)

The ekey bionyx embedded devices have to operate autonomously and therefore implement cloud-independent security measures to protect themselves and the integrators’ systems.

Integrator API transport security levels

You can configure our devices to enforce different security levels when accessing the Integrator API.
If not configured properly, attackers could carry out a man-in-the-middle attack in order to access the authorization secret.
This would allow them to use the Integrator API in the same way the ekey bionyx system does.

Check if certificate is signed by a trusted Certificate Authority (CA)

The standard and the recommended option for cloud APIs is TlsWithCACheck. This means that the ekey bionyx devices check if the certificate presented by the Integrator API is signed by an official certificate authority. Therefore, an attacker would have to compromise an authority or get access to the URL configured in the HTTP request to get credentials (which is usually very hard to do).

Pin a certificate

To protect your API request credentials (like access tokens) from man-in-the-middle attacks, we support pinning the server certificate by using the option TlsPinnedCertificate.
You can add a signing certificate our device shall pin to the API request description. The device will then only accept APIs that can prove the possession of the private key for a certificate that is signed with this signing certificate.
We also allow pinning the leaf certificate. This allows a device to generate its own self signed certificate and register a webhook - including this certificate - to itsef via the API. Be aware that in this case, our system has to be notified if you change the certificate.
In general, we validate all certificates beginning from the one that is pinned. This includes pinned certificates that are themselves signed by another certificate, which we can’t validate.
Here are some examples for the accepted and rejected chains:

In all cases, set the securityLevel and pinnedCertificate fields.
This is the recommended option for local network APIs.

Allow self signed certificates (not recommended)

A supported but not recommended option is TlsAllowSelfSigned.
The option will use TLS for the connection, but the ekey bionyx device will accept any certificate.
With this option, man-in-the-middle attacks can easily be carried out if the attackers have access to the network.
Therefore, this must only be done in secured local networks, meaning that the network is hardened against unwanted access.

Allow HTTP (not recommended)

The least secure, and therefore also not recommended, option is AllowHttp.
With this enabled, the ekey bionyx device will even allow unencrypted connections without TLS.
This means that attacks on the connection could be passive (sniffing) or via man-in-the-middle.
As above, this must only be done in secured local networks, meaning that the network is hardened against unwanted access.

Authenticating against the Integrator API

The ekey bionyx device has different means of authenticating against the Integrator API.

OAuth 2.0 support

The ekey bionyx devices have limited support to authenticate against OAuth 2.0 secured APIs.
There are 2 options:

Option OAuth 2.0 access token
If you set the authorization to this, you can add an access token of any kind:
The embedded device will use whatever is in this field and add an authorization header to the request before sending it like this: “Authorization”: “Bearer ”

Option OAuth 2.0 refresh token
This option is helpful if the access tokens of an API have a restricted validity.
Refresh tokens are usually more long-living than access tokens. You can get them via any flow (e.g. auth code flow ).
If you set the refresh token to the authentication field, the embedded device will get an access token from the configured token URL (the identity provider) itself, before adding it to the authorization header as above.

Proprietary header, body, etc.

Option NoAuth
The API request definition of the HTTP requests is fully configurable - so you could just add a token or any other secret at any place of a request and use it to authenticate our system against yours.