Public Key Authentication

Public Key Authentication in Nabto Edge is inspired by SSH’s similar concept. This authentication model uses cryptographic keys to identify and authenticate peers instead of e.g. username and passwords. Using cryptographic keys for authentication has the advantage that they are practically impossible to bruteforce crack (corresponds to a very long, random password securely exchanged) and without the need for the user to remember anything.

The cryptographic keys in Nabto Edge are additionally used to ensure end-to-end confidentiality and integrity of the communication between two peers.

The device has a white list of public keys that are allowed to access the device - only clients with a matching private key are allowed access to the device. And vice versa: The client has a list of known devices and their public keys. In practice, in both device and client instead of a list of public keys, a secure hash (checksum) of the public key is used, denoted the public key’s fingerprint (simpler to manage).

The Nabto Edge client application and the Nabto Edge embedded device application each needs their own unique key pair. Our APIs provide functions to create such key pairs or they can be created using standard tools, such as the OpenSSL cli tools.

Nabto Edge uses elliptic curve cryptography as it provides strong security with resource requirements that are suitable for the IoT domain.

In practice, only the private key from the keypair is stored (locally in the respective device) and the public key is derived at runtime from it. Exchanging public key (fingerprints) for the white lists is denoted pairing and is described in the Pairing guide.

Once two peers are paired (ie, either peer knows the public key of the other peer), a secure Nabto Edge Direct connection between the two can be established with mutual authentication. This is implemented as a standard DTLS handshake with the initiator being the Nabto Edge Client application and the server being the Nabto Edge Embedded device application. Once the DTLS handshake is complete, each peer possesses the other peer’s public key and can then validate that it matches the white list of paired public keys.

The Nabto Edge basestation servers facilitates the exchange of information during the DTLS handshake between the two peers if they are not on the same network. If they can communicate directly, e.g. after a BonJour discovery, they perform the handshake directly instead of through the basestation servers.

The Nabto Edge Embedded SDK per default uses Mbed TLS. From SDK version 5.11, the WolfSSL suite is also supported. Both are proven 3rd party DTLS implementation suitable for embedded devices.

Device Authentication towards the Basestation

The same fingerprint mechanism is used between the device and the Nabto Edge Basestation. To be reachable remotely, a device must first attach to the Basestation: It establishes a DTLS connection to <product-id>.devices.nabto.net and reports the product ID and device ID it is configured with.

In the DTLS handshake the device presents a self signed certificate holding its public key. The Basestation does not validate that certificate against a certificate authority. Instead it computes the fingerprint of the public key in it, a SHA-256 hash written as 64 hex characters, and looks the fingerprint up in the Nabto cloud. The device is only allowed to attach if that fingerprint is registered for exactly the product ID and device ID the device claims. This is why registering the fingerprint is what turns a device license into a device that can come online, as described in Provisioning Devices.

Since the private key never leaves the device and a fingerprint cannot be turned back into a public key, the registered fingerprint is not a secret. It only identifies which key the Basestation should accept for that device.

If the fingerprint is unknown or if it is registered for a different product ID or device ID, the Basestation rejects the attach attempt. The device stays offline and reports the reason as a device event, such as NABTO_DEVICE_EVENT_UNKNOWN_FINGERPRINT, then retries. Clients trying to reach the device through the Basestation are told that the device is not attached. This is the error to look for when a device that works on the local network cannot be reached remotely.

Authentication in the other direction uses ordinary PKI: The Basestation presents a certificate chain issued by the Nabto certificate authority. The device validates that chain against a root certificate built into the Embedded SDK. A device whose clock is wrong can therefore fail to attach, since the certificate then appears expired or not yet valid.

The Basestation is not a party to the client-to-device authentication described above. It relays that DTLS session without being able to read it. The two peers still authenticate each other by fingerprint. Client access to the Basestation is controlled separately, see Server Side Connect Filtering.

Summary of Developer Tasks

Create Private Key in Client

Typically the client private key is created the first time the app is used - see API functions for creating private keys (iOS and Android shortcuts). The key is stored on the client device in any location the application developer prefers. Best practice is to store the key in a protected key store such as those available on both iOS and Android.

Or you can use standard tools, e.g. OpenSSL to generate the keypair:

openssl ecparam -genkey -name prime256v1 -out key.pem

Provide the Client Private Key to Nabto Edge Client SDK

After the key is created or loaded, it must be provided to the Nabto Edge Client SDK - see API functions for setting private keys (iOS and Android shortcuts).

Create and Load Private Key on the Embedded Device

On the device, creation of the private key depends on the vendors’ provisioning process. Typically the private key is installed at the factory - that is, created outside the device and installed in the manufacturing process.

The vendor then uploads each derived public key’s fingerprint to the Nabto Edge server infrastructure - to allow the device to come online later for remote access. Each purchased device license correponds to such registered public key. The Edge Provisioning guide describes how to create devices and register fingerprints in bulk through the Nabto Cloud Console.

Alternatively, the private key on the device is created directly on the device - either on the factory or at the user when starting the device for the first time. When doing this, the Nabto Edge Embedded SDK provides an API function to create the key. It is up to the vendor to store the key in an appropriate location.

Regardless of how the key is created and stored, it is subsequently read by the vendor’s application and provided to the Nabto Edge SDK prior to the device coming online.

Configure and use access control

The IAM guide lists the developer tasks necessary to configure and use access control - ie to perform pairing of clients and device and authorize requests on the device.

Examples

Full examples that show all necessary implementation and API interaction are available: The CoAP thermostat demo and the TCP tunnel apps.