Device Security
This page describes the device security features available in akenza
Last updated
Was this helpful?
This page describes the device security features available in akenza
Last updated
Was this helpful?
Securing devices is one of the main concerns when rolling out an IoT deployment and requires careful consideration in order to minimize the attack surface.
akenza offers the following security features:
Device credentials with JWTs: Per-device public/private key authentication using JSON Web Tokens (JWTs, )
Uplink secret: A shared key per device connector that is passed via header or URL parameter for HTTP and CoAP and the password field for MQTT
This authentication method is based on public/private key authentication using JSON Web Tokens and limits the attack surface because a compromised key only affects a single device and not the whole fleet. As JWTs define an expiration, any compromised key will only be valid for a limited duration.
Currently, this authentication method is only available for MQTT devices.
The "provisioner" (typically the hardware manufacturer) is required to create a public/private key pair that is distributed to the device during the provisioning process.
Create a new key pair (public/private key)
Distribute the key to the device and securely store it
Upload the public key to akenza (see )
Authenticate with a JSON Web token that is signed by the private key, while establishing an MQTT connection
Start sending telemetry and receiving commands
Notably, the key can be stored on the device before the device has been created in akenza.
akenza provides support for both RSA and Elliptic Curve signed tokens.
The following algorithms are supported:
The RSA algorithm has a wider adoption, however keys and signatures tend to be large (~1-2 kB) and the algorithm has higher resource requirements (key length and CPU).
The Elliptic Curve algorithm is well supported but not as widely used as RSA. The generated keys and signatures are significantly smaller compared to RSA, which can be useful for devices with constrained resources.
ES256 has a preset level of 128 bits of security (the key size is fixed).
The following key formats are supported in akenza
RSA PEM: An RSA public key encoded in base64.
RSA X509 PEM: An RSA PEM key, encoded in base64, wrapped in an X.509 certificate.
ES256 PEM: A public key for the ECDSA algorithm (using P-256 and SHA-256), encoded in base64.
ES256 X509 PEM: An ES256 PEM key, encoded in base64, wrapped in a X.509 certificate.
akenza supports multiple active keys (up to 3 per device) to allow for uninterrupted rotation. If more than one key is in use, the JWT must include the fingerprint of the key used to sign the JWT (kid claim).
Required JWT contents:
kid must be the fingerprint of a public key or certificate associated with the device. The kid is optional if there’s only one public key or certificate associated with a device
alg required, contains the appropriate signing algorithm based on signature
aud required, must be in the following format: https://akenza.io/devices/{deviceId}(for enterprise deployments the base url of the deployment needs to be used instead of akenza.io)
exp required, a valid date in the future. A 10-minute clock-skew allowance applies.
iat optional, a valid date in the past. A 10-minute clock-skew allowance applies.
The expiration (exp) and issued at (iat) claims are relevant to check whether the JWT is valid during uplink processing. In no cases should the device use an (almost) never expiring JWT, as it could be used to send unauthorized data.
Other claims (standard and custom ones) can be set, but will have no impact on the uplink processing.
uplink topic: /up/device/id/{deviceId}
downlink topic: /down/device/id/{deviceId}
The MQTT authentication needs to include the following properties:
username arbitrary username (not used). depending on framework this needs to be set in order for the password to be sent as well
password must be a valid JWT signed with the private key
clientId must be the deviceId
Not supported yet.
Not supported yet.
keep the private key secret
use TLS 1.2 when communicating on ports 8883
Verify that the server certificate
Perform regular security-related firmware updates to keep server certificates up-to-date
each device should have a unique public/private key pair
This form of authentication is the easiest. It is most commonly used for HTTP-based integrations.
When a data flow is created, the device connector specifies the secret to use as password when making an uplink.
Authenticating an uplink with basic auth requires the device connector id and the uplink secret. If the device connector is assigned, via data flow, to the device and the uplink secret matches, the uplink request is authenticated.
URL: /v3/capture?deviceId={deviceId}&topic=default&...
Query Parameters:
Authentication via secret - DEPRECATED in favour of x-uplink-secret HTTP header, with value {uplinkSecret}
deviceId - DEPRECATED in favour of x-device-id with value {deviceId}
HTTP headers:
Authentication via x-uplink-secret with value {uplinkSecret}
Authentication via secret - DEPRECATED in favour of x-uplink-secret , with value {uplinkSecret} or as a url param
x-device-id - in favour of x-device-id with value {deviceId}
deviceId - DEPRECATED with value {deviceId}
NOTE: The uplink secret should, whenever possible, be sent as a header, but can also be sent as a query-param named secret. Using the HTTP header is greatly preferred, as it doesn’t expose the uplink-secret in the URL.
uplink topic: up/{uplinkSecret}/id/{deviceId}
downlink topic: /down/{uplinkSecret}/id/{deviceId}
The MQTT authentication needs to include the following properties:
username must be the device connector id
password must be the uplink secret
clientId can be anything/left blank
url: udp://{host}:{port}?deviceId={deviceId}&secret={secret}&topic={topic}&...
JWT RS256 (RSASSA-PKCS1-v1_5 using SHA-256 )
JWT ES256 (ECDSA using P-256 and SHA-256 ), defined in OpenSSL as the prime256v1 curve
A minimum of 112 bits of security is required by akenza (also refer to the , section 5.6.2, pages 55-56). This translates to a minimum 2048-bit key size for RS256.
The JWT needs to be generated with the following reserved claim fields and signed using the private key. Refer to our for practical examples on how to generate private/public keys and sign a JWT.