• https://github.com/cnecrea/hidroelectrica

I'd still like to describe how to locate the endpoints and the login process, so here we go...

This is the second post about #SEW SCM API – Smart Customer Mobile API by Smart Energy Water, this time we will learn about different APIs using real world utility websites.

It appears that there are at least two different API “flavors”. The one that uses ModuleName.svc/MethodNameMob naming convention and usually resides under PortalService endpoint, and the newer one, which lives under /API/.

So e.g. Nebraska Public Power District has endpoints at https://onlineaccount.nppd.com/PortalService/, e.g. https://onlineaccount.nppd.com/PortalService/UserLogin.svc/help. Rochester Public Utilities runs a different set of endpoints, with the root at https://connectwith.rpu.com/api.

The endpoints for the latter API can also be browsed at https://scmcx.smartcmobile.com/API/Help/.

Different utilities pay for different set of modules, and here's some of the modules I have discovered so far:

• AdminBilling
• CompareSpending
• ConnectMe
• EnergyEfficiency
• Generation
• Notifications
• Outage
• PaymentGateway
• Usage
• UserAccount
• UserLogin

For /PortalService/ endpoints you can visit BASE_URL + /PortalService/ + ModuleName + .svc + /help to get the list of RPC calls you can issue. In order to find out what to send in the requests, you need to look into the calls within the apps for your utility. Note that some utilities opted out of the AES/CBC/PKCS5Padding PasswordPassword encryption, so let's hope this will be a trend forward. Currently SEW web portals talk to a completely different set of APIs to populate the interface, even though they are querying the same thing.

So to start, here's how to login to your favorite utility:

from typing import Mapping, Any

import base64
import json
import hashlib
import requests
import urllib.parse

from Crypto.Cipher import AES

BASE_URL = "https://example.com/PortalService"


def _encrypt_query(
    params: Mapping[str, str], encryption_key: str = "PasswordPassword"
) -> str:
    """Encrypt with AES/CBC/PKCS5Padding."""
    cipher = AES.new(encryption_key, AES.MODE_CBC, IV=encryption_key)

    cleartext = urllib.parse.urlencode(params).encode()

    # PKCS5 Padding - https://www.rfc-editor.org/rfc/rfc8018#appendix-B.2.5
    padding_length = 16 - len(cleartext) % 16
    cleartext += padding_length * chr(padding_length).encode()

    return base64.b64encode(cipher.encrypt(cleartext)).decode("ascii")


def request(module: str, method: str, data: Mapping[str, Any]) -> Mapping[str, str]:
    enc_query = _encrypt_query(data)
    # Or module + '.svc/'
    url = BASE_URL + "/" + module + "/" + method

    resp = requests.post(url, json={"EncType": "A", "EncQuery": enc_query})
    if not resp.ok:
        raise Exception(resp.status_code)
    return resp.json()


password_digest = hashlib.sha256("PASSWORD".encode()).hexdigest()
# Or ValidateUserLoginMob
response = request(
    "UserLogin",
    "ValidateUserLogin",
    {"UserId": "USERNAME", "Password": password_digest},
)
print(response)

response will contain some object, you will need LoginToken and AccountNumber to proceed with most of the other calls.

It's a bit awkward that different utilities have different endpoints, which makes creating a universal client challenging, so for now I am researching the ways to get info from the Usage module. The parameters are weird (“type”: “MI”, or “HourlyType”: “H”), but we will get there.

Smart Energy Water, or #SEW is a SaaS provider, and they ship the whole thing – the backend, frontend, and the phone apps, the latter under the name SCM, which means Smart Customer Mobile.

So I embarked on a journey to figure out how these phone apps worked and, if successful, get my data out and into homeassistant.

APK

I pulled an APK of my utility from Google Play Store and found that something secret is hidden in a libnative-lib.so binary, under com.sew.scm.gcm.SecureConstant, under a few methods returning String, and some methods that decrypt these strings using a heavily obfuscated set of routines, which essentially XOR'd (in case of Android APK) the values of gcm_default_sender_id + google_app_id + Android_App_RatingConstant_File, all the values from the strings.xml within the app resources.

One of the decoded tokens contains a key for request encryption. It was ...

PasswordPassword

SCM apps use private APIs. In order to remain private and hard to use the requests are encrypted.

You urlencode the parameters into key=value&key1=value1... form, then encrypt the resulting string using AES-CBC with PKCS5 Padding (16 bytes variant) using PasswordPassword as both the key and IV.

Then you send {"EncType": "A", "EncQuery": "base64-encoded-encrypted-string"}, and receive response from one of the .../API/Module/MethodName endpoints. The response will be JSON with no extra encryption, so it is definitely a deterrent against making requests, not a security feature.

Login

Armed with that knowledge, and some help from exposed API listing on one of the utility websites I found that I need to use ValidateUserLoginMob call expecting userid and password.

However, password had to be base64-encoded result of applying a secret scheme from that SecurityConstant module above. It is always SHA256.

So my first https://utility.example.net/API/UserLogin/ValidateUserLogin was a success, I got LoginToken and AccountNumber, which was all we needed to start poking APIs.

Tada!

If your utility uses SEW SCM, i.e. one of these at https://play.google.com/store/apps/developer?id=Smart+Energy+Water, you should be able to get API listing by visiting the web interface, and appending /API/Help. Or, if your utility runs an older version of SCM, replace /portal/ with /portalservice/UserLogin.svc/help or /portalservice/Usage.svc/help. You may get the .NET API definitions.