Cara Mengatur Verifikasi Sertifikat MQTTS dan HTTPS pada Meter Energi IAMMETER

Meter energi IAMMETER dengan firmware i.91.065.9 atau lebih baru dapat memverifikasi sertifikat server saat mengunggah data melalui MQTTS atau HTTPS. Ini menambahkan verifikasi rantai sertifikat dan nama host server pada koneksi keluar yang aman.

Artikel ini berfokus pada konfigurasi kepercayaan TLS. Artikel ini tidak mengatur topik MQTT, payload JSON, atau discovery Home Assistant. Untuk alur publikasi MQTT, lihat Meter Energi MQTT: Publikasikan Data IAMMETER ke Broker MQTT Anda.

Di halaman ini

• Pilih mode verifikasi sertifikat
• Persyaratan dan batasan penting
• Periksa mode TLS saat ini
• Pilih verifikasi builtin
• Pilih none untuk diagnosis sementara
• Unggah dan pilih CA Kustom
• Hapus CA Kustom
• Gunakan IAMMETER Swagger UI
• Pecahkan masalah verifikasi sertifikat

Pilih mode verifikasi sertifikat

Klien MQTTS dan HTTPS IAMMETER mendukung tiga mode verifikasi sertifikat server:

Pengaturan ini berlaku saat perangkat IAMMETER bertindak sebagai klien TLS dan mengunggah data ke broker MQTTS atau server HTTPS. Pengaturan ini tidak mengaktifkan HTTPS pada server Web lokal perangkat.

builtin

builtin adalah mode bawaan. Mode ini digunakan ketika belum ada pengaturan verifikasi TLS yang disimpan, dan dipulihkan setelah konfigurasi TLS CA dihapus atau perangkat direset ke setelan pabrik.

Firmware berisi Root CA berikut:

• DigiCert Global Root G2
• ISRG Root X1

Perangkat memverifikasi rantai sertifikat dan nama host server. Broker MQTTS atau server HTTPS harus menyajikan sertifikat yang rantainya menuju salah satu root ini, dan Subject Alternative Name (SAN) harus cocok dengan alamat server yang dikonfigurasi.

Jika alamat unggah memakai IP, sertifikat harus memuat IP yang persis sama dalam SAN. Nama DNS tidak cocok dengan alamat IP, sekalipun keduanya menunjuk server yang sama.

custom

custom melakukan validasi rantai dan nama host yang sama seperti builtin, tetapi mempercayai sertifikat PEM CA yang diunggah administrator. Gunakan ketika:

• sertifikat server diterbitkan CA privat;
• penerapan memakai sertifikat server yang ditandatangani sendiri; atau
• Root CA publik yang diperlukan belum disertakan dalam firmware.

Untuk PKI privat, unggah sertifikat Root CA-nya. Server TLS tetap harus mengirim sertifikat perantara yang diperlukan saat handshake. Sertifikat server yang ditandatangani sendiri dapat diunggah sebagai jangkar kepercayaan, tetapi SAN-nya tetap harus cocok dengan nama host atau IP yang dikonfigurasi.

none

none tetap membuat koneksi TLS terenkripsi, tetapi tidak memverifikasi rantai sertifikat atau nama host. Ini mirip perilaku TLS lama tanpa autentikasi server.

Mode ini rentan terhadap serangan man-in-the-middle. Gunakan hanya sementara untuk kompatibilitas atau diagnosis. Utamakan builtin atau custom dalam produksi.

Persyaratan dan batasan penting

API konfigurasi TLS CA memerlukan Local Admin Security yang aktif. Setiap permintaan harus menyertakan nama pengguna serta kata sandi administrator yang dikonfigurasi melalui HTTP Basic Authentication.

Komputer yang menjalankan curl atau Swagger UI harus dapat menjangkau IP lokal perangkat. Klien MQTTS dan HTTPS berbagi satu mode verifikasi dan satu CA Kustom, sehingga perubahan berlaku pada mode unggah aman yang digunakan perangkat.

Mulai ulang perangkat setelah mengubah konfigurasi TLS agar klien keluar dibuat ulang dengan pengaturan baru.

Contoh menggunakan placeholder berikut:

DEVICE_IP="192.168.1.80"
ADMIN_USER="admin"
ADMIN_PASSWORD="ExamplePassword1"

Ganti dengan alamat perangkat sebenarnya dan kredensial administrator.

Periksa mode TLS saat ini

API:

GET /api/tls/ca/status

Contoh:

curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
  "http://$DEVICE_IP/api/tls/ca/status"

Contoh respons:

{
  "successful": 1,
  "mode": "builtin",
  "customCaValid": 0,
  "customCaLength": 0,
  "customCaSha256": "",
  "restartRequiredAfterChange": 1
}

Respons melaporkan mode terpilih dan, jika ada, panjang serta ringkasan SHA-256 CA Kustom yang disimpan.

Pilih verifikasi builtin

API:

POST /api/tls/ca/select

Contoh:

curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
  -X POST "http://$DEVICE_IP/api/tls/ca/select" \
  -H "Content-Type: application/json" \
  -d '{"mode":"builtin"}'

Mulai ulang perangkat setelah respons berhasil.

Pilih none untuk diagnosis sementara

API:

POST /api/tls/ca/select

Contoh:

curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
  -X POST "http://$DEVICE_IP/api/tls/ca/select" \
  -H "Content-Type: application/json" \
  -d '{"mode":"none"}'

Respons memperingatkan bahwa verifikasi sertifikat server dinonaktifkan. Mulai ulang setelah mengubah mode, lalu kembali ke builtin atau custom setelah diagnosis.

Unggah dan pilih CA Kustom

Mengunggah CA dan memilih custom merupakan operasi terpisah. Mengunggah CA tidak otomatis mengubah mode aktif.

Persyaratan file CA Kustom

File unggahan harus memenuhi semua persyaratan berikut:

• format sertifikat PEM;
• isi permintaan mentah, bukan JSON atau multipart/form-data;
• Content-Type: application/x-pem-file;
• panjang 1 hingga 3072 byte, termasuk header PEM, akhir baris, dan spasi;
• memuat -----BEGIN CERTIFICATE----- dan -----END CERTIFICATE-----;
• tidak memuat kunci privat.

Batas 3072 byte berlaku untuk seluruh isi permintaan HTTP. File PEM 3072 byte diterima, file 3073 byte ditolak.

Periksa ukuran file sebelum mengunggah:

wc -c root-ca.pem

Langkah 1: Unggah CA

API:

POST /api/tls/ca/upload

Contoh:

curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
  -X POST "http://$DEVICE_IP/api/tls/ca/upload" \
  -H "Content-Type: application/x-pem-file" \
  --data-binary @root-ca.pem

Contoh respons berhasil:

{
  "successful": 1,
  "length": 1939,
  "sha256": "64-character SHA-256 digest",
  "message": "CA uploaded; select custom mode and restart"
}

Perangkat menyimpan CA dalam beberapa blok KV dan memverifikasi panjang tersimpan serta ringkasan SHA-256 sebelum menandainya aktif. Penulisan yang terputus tidak menggantikan CA valid sebelumnya.

Langkah 2: Pilih custom

curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
  -X POST "http://$DEVICE_IP/api/tls/ca/select" \
  -H "Content-Type: application/json" \
  -d '{"mode":"custom"}'

Perangkat menolak permintaan jika belum ada CA Kustom valid yang disimpan. Perangkat tidak diam-diam beralih ke none.

Langkah 3: Mulai ulang dan verifikasi

Mulai ulang dari Web UI lokal atau gunakan API restart yang terlindungi:

curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
  "http://$DEVICE_IP/api/restart?reset=false"

Setelah perangkat terhubung kembali, periksa status lagi:

curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
  "http://$DEVICE_IP/api/tls/ca/status"

Pastikan mode adalah custom, customCaValid adalah 1, serta panjang dan ringkasan SHA-256 yang dilaporkan cocok dengan sertifikat unggahan.

Hapus CA Kustom

API:

POST /api/tls/ca/delete

Contoh:

curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
  -X POST "http://$DEVICE_IP/api/tls/ca/delete"

Menghapus CA Kustom juga mengembalikan mode ke builtin. Mulai ulang perangkat setelah penghapusan.

Gunakan IAMMETER Swagger UI

API yang sama dapat diuji tanpa menulis perintah curl secara manual:

IAMMETER WEM API Test - TLS CA

1. Buka WEM API Test pada komputer yang dapat menjangkau IP lokal perangkat.
2. Masukkan alamat perangkat, misalnya 192.168.1.80, lalu pilih Apply.
3. Pilih Authorize dan masukkan nama pengguna serta kata sandi administrator.
4. Buka grup TLS CA - Authenticated.
5. Gunakan GET /api/tls/ca/status untuk memeriksa konfigurasi saat ini.
6. Gunakan operasi unggah, pilih, atau hapus sesuai kebutuhan.
7. Mulai ulang setelah mengubah mode atau sertifikat.

Halaman Swagger berjalan di browser dan mengirim permintaan langsung dari komputer ke perangkat IAMMETER. Halaman ini tidak menggunakan proxy IAMMETER Cloud, sehingga browser harus memiliki konektivitas jaringan langsung ke IP perangkat.

Pecahkan masalah verifikasi sertifikat

admin security required

Aktifkan Local Admin Security sebelum memakai API TLS CA. Pengaturan ini tidak dapat diubah secara anonim.

custom CA is missing or invalid

Unggah PEM CA valid dengan berhasil sebelum memilih custom. Periksa /api/tls/ca/status dan pastikan customCaValid adalah 1.

Koneksi TLS gagal dalam builtin atau custom

Periksa semua hal berikut:

• nama host atau IP yang dikonfigurasi cocok dengan SAN sertifikat;
• sertifikat masih berlaku dan waktu perangkat benar;
• server mengirim sertifikat perantara yang diperlukan;
• Root CA terpilih menerbitkan atau melalui rantai mempercayai sertifikat server;
• perangkat sudah dimulai ulang setelah perubahan TLS.

TLS bekerja dalam none tetapi gagal dalam mode terverifikasi

Ini biasanya menunjukkan masalah rantai sertifikat, nama host, masa berlaku, atau jam perangkat. Membiarkan none aktif menyembunyikan kegagalan autentikasi, bukan menyelesaikannya. Perbaiki penerapan sertifikat atau unggah Root CA yang sesuai dan gunakan custom.