LocalThings

Step 1: Onboarding QR code

Every SmartThings-compatible device should have an onboarding QR code sticker somewhere, whose contents are actually well documented.

The QR code contains a URL with the following pattern: https://qr.samsungiots.com/?m={Your mnId}&s={Device onboardingId}&r={Device serialNumber}. It also seems to be completely redundant, as the app offers to search for devices even without scanning a QR code.

Step 2: WiFi access point

After the user presses a certain button on the SmartThings-device, that device will create a WiFi access point (AP). Its SSID exposes almost the same information as the QR code and its password is fixed to 1111122222 (five times 1, five times 2) for every device.

Dishwasher_E40AwG0006WljY0009
           ++ fixed: E4
             ++++ mnid: 0AwG
                 +++ onboardingId: 000
                    + setup type: 6 (fixed)
                     ++++ first 4 digits of hashed serial number: WljY
                         ++++ last 4 digits of serial number: 0009

Step 3: Cloud-assisted Diffie-Hellmann

After connecting to the WiFi AP and with known mnid, onboardingId/setupId and serial number (or parts of it) we can continue with the Diffie-Hellman key exchange. Normally we would generate a private/public key pair, send our public key to the device, somehow retrieve it’s public key and then compute a shared secret. However, there is no way to retrieve a device’s unique[1] public key, because Samsung decided to use “cloud assisted Diffie-Hellmann”. For that we generate a random, 32 byte hex- and then urlsafe-base64-encoded nonce (rand) and send it along with the parts of the serial number we know to their server. For the type hybrid_sn that is the first four characters of the SHA256-hashed and urlsafe-base64-encoded serial number plus the last four digits of the plaintext serial number.

POST https://client.smartthings.com/identity/easysetup/blob HTTP/1.1
accept: application/vnd.smartthings+json;v=2
content-type: application/json
authorization: Bearer XXXXXXXXXXXXXXXXXXXXXXXXX

{
  "keyid": {
    "type": "hybrid_sn",
    "value": "WljY0009"
  },
  "mnId": "0AwG",
  "rand": "ZWU3MDkwMzU5YzkzZjRjNjViY2U4ZTAzNTk2ODRkNWY5ZTE2OTRjM2YzMGEyYjE5M2UyZWEzZWE1ZTg4YWY2Ng==",
  "setupId": "000"
}

The server then generates a private/public key pair for us, but sends us only the public part (cloudPubKey) and the pre-computed Diffie-Hellmann shared key (blob).

{
  "code": 2000000,
  "message": "SUCCESS",
  "data": [
    {
      "type": "ECDH_ED25519",
      "blob": "gRt305a1hhWinTIPeDrUA02uoVpYYxoxkhS-Y4CCNiA=",
      "cloudPubKey": "i7nZKUV5AnqLWn_IuT9XGfHB8DdG-yAlpvPzC7aZ1wY=",
      "sn": "WljY0TvvL3dhelS4CmieyED_ULB49S5pf2gPid8Bt9c=",
      "meta": {
        "mfgr": "Midea",
        "mnId": "0AwG",
        "onboardingId": "000",
        "modelName": "Dishwasher",
        "sku": [
          "DW60A8040",
          "DW60A8050",
          "DW60A8060",
          "DW60A8070"
        ],
        "partner": "Midea"
      }
    }
  ]
}

Step 4: Connecting to a wireless network

With that information we can start talking to the device. Its HTTP server listens on the default gateway’s address (usually 192.168.4.1) on port 8888. First, we retrieve an initialization vector (IV) for AES.

GET http://192.168.4.1/deviceinfo HTTP/1.1

It will answer with a random IV (iv) and its SHA256-hashed serial number (hashedSn).

{
  "protocolVersion": "1.0.0",
  "firmwareVersion": "20010101",
  "hashedSn": "WljY0TvvL3dhelS4CmieyED_ULB49S5pf2gPid8Bt9c=",
  "wifiSupportFrequency": 0,
  "iv": "L0k3NxzQwmQdYcurvAXH3A=="
}

We then share our public Diffie-Hellmann key (spub) and the random nonce we generated and sent to the cloud server (rand):

POST http://192.168.4.1/keyinfo HTTP/1.1
content-type: application/json

{
  "spub": "i7nZKUV5AnqLWn_IuT9XGfHB8DdG-yAlpvPzC7aZ1wY=",
  "rand": "ZWU3MDkwMzU5YzkzZjRjNjViY2U4ZTAzNTk2ODRkNWY5ZTE2OTRjM2YzMGEyYjE5M2UyZWEzZWE1ZTg4YWY2Ng==",
  "datetime": "MjAwMS0wMS0wMVQwMC4wMC4wMCBVVEM=",
  "regionaldatetime": "MjAwMS0wMS0wMVQwMC4wMC4wMCBHTVQ=",
  "timezoneid": "RXVyb3BlL0Jlcmxpbg=="
}

While the code snippets following will show plaint-text only, from now on requests and responses are encrypted with the shared secret we retrieved from the cloud service. We use AES in CBC mode with 16 bytes PKCS7 padding and initialized the cipher with the IV retrieved from the device above. JSON responses are encryted, then encoded with urlsafe base64 and stored in another layer of JSON like so:

{"message": "<payload>"}

Decrypted the answer contains the ownership validation methods the device supports. In this case the “just works” method, which requires a dummy verification.

{"otmSupportFeatures": [0]}

Now we can confirm to the device that we are indeed its owner.

POST http://192.168.4.1/confirminfo HTTP/1.1
content-type: application/json

{"otmSupportFeature": 0}

Which it confirms with an empty response.

{}

Afterwards we can scan for available WiFi networks.

GET http://192.168.4.1/wifiscaninfo HTTP/1.1

Besides the WiFi name the returned list also contains an authType, which has the value 3 for the most common WPA2-PSK-based network.

{
  "wifiScanInfo": [
    {
      "bssid": "a1:b2:c3:d4:e5:f6",
      "ssid": "<ssid name>",
      "rssi": -123,
      "frequency": 0,
      "authType": 3
    }
  ]
}

With that information we can now send the credentials for one of these wireless networks. The bssid from above can be filled in as macAddress. authType should match what was returned during the scan. brokerUrl must point to an MQTT broker. Password and SSID are not base64-encoded.

POST http://192.168.4.1/wifiprovisioninginfo HTTP/1.1
content-type: application/json

{
  "wifiCredential": {
    "ssid": "<ssid name>",
    "password": "<password>",
    "macAddress": "a1:b2:c3:d4:e5:f6",
    "authType": 3
  },
  "brokerUrl": "ssl://mqtt-regional-euwest1.api.smartthings.com:8883",
  "deviceName": "myFancyDeviceName"
}

The device responds with a lookupId, which it also sends to the broker later, and in case of “just works” authentication, with its serial number.

{"lookupId": "e64a8186-9d50-41e1-b8e8-883f7e80f85b", "sn": "11812652000009"}

In a final step we confirm the setup is complete and correct.

POST http://192.168.4.1/setupcomplete HTTP/1.1
content-type: application/json

{}

An empty JSON object is returned.

{}

Step 5: Registering with MQTT server

Each device has a TLS root certificate burnt in, which is validated when contacting the broker given above. It will therefore not talk to any MQTT server with a self-signed certificate. However this root certificate is DigiCert Global Root G2[2], which also signs several sub-CA’s, which in turn sign ordinary domain-validated TLS-certificates. Therefore the brokerUrl must host an MQTT broker serving requests signed by this exact root certificate.

If all is well, the device will connect to the broker with its serial number as username and a JWT as password. Since the JWT is signed with the device’s private key and we don’t have access to its public key we cannot verify its authenticity. Then the device subscribes to /v1/registrations/notification/<serialnumber> and waits for this event:

{"event": "connect.success"}

After receiving it, it sends a register event like the following to /v1/registrations:

{
  "label": "myFancyDeviceName",
  "mnId": "0AwG",
  "vid": "DA-WM-DW-31001",
  "deviceTypeId": "Dishwasher",
  "lookupId": "e64a8186-9d50-41e1-b8e8-883f7e80f85b",
  "serialHash": "WljY0TvvL3dhelS4CmieyED_ULB49S5pf2gPid8Bt9c=",
  "provisioningTs": 1729243966,
  "firmwareVersion": "20200818",
  "osType": "TizenRT",
  "osVersion": "2.0",
  "stdkVersion": "1.7.4",
  "deviceIntegrationProfileKey": {
    "id": "bc5ecba8-f445-4c94-b8da-38b2998bd2ea",
    "majorVersion": 2,
    "minorVersion": 0
  }
}

It then waits for a response, assigning it its deviceId and disconnects again:

{"deviceId": "46f92efd-918a-457e-9d04-c587a53db41e"}