IAMMETER 전력량계의 MQTTS 및 HTTPS 인증서 검증 설정 방법
펌웨어 i.91.065.9 이상을 사용하는 IAMMETER 전력량계는 MQTTS 또는 HTTPS로 데이터를 업로드할 때 서버 인증서를 검증할 수 있습니다. 안전한 아웃바운드 연결에 인증서 체인과 서버 호스트 이름 검증을 추가합니다.
이 글은 TLS 신뢰 설정을 다룹니다. MQTT 토픽, JSON payload, Home Assistant 검색은 설정하지 않습니다. MQTT 발행 절차는 MQTT 전력량계: IAMMETER 데이터를 MQTT 브로커에 발행을 참조하세요.
이 페이지의 내용
- 인증서 검증 모드 선택
- 요구사항과 중요한 적용 범위
- 현재 TLS 모드 확인
- builtin 검증 선택
- 임시 진단용 none 선택
- 사용자 CA 업로드 및 선택
- 사용자 CA 삭제
- IAMMETER Swagger UI 사용
- 인증서 검증 문제 해결
인증서 검증 모드 선택
IAMMETER의 MQTTS 및 HTTPS 클라이언트는 세 가지 서버 인증서 검증 모드를 지원합니다.
| 모드 | 인증서 체인 | 서버 호스트 이름 | 용도 |
|---|---|---|---|
builtin |
펌웨어 내장 루트 CA로 검증 | 검증 | 지원되는 인증서 체인을 사용하는 공개 서비스에 권장 |
custom |
사용자가 제공한 PEM 루트 CA로 검증 | 검증 | 사설 PKI, 자체 서명 배포 또는 펌웨어에 없는 공개 루트 |
none |
검증하지 않음 | 검증하지 않음 | 임시 호환성 확인 또는 진단 전용 |
이 설정은 IAMMETER 기기가 TLS 클라이언트로 동작하여 MQTTS 브로커나 HTTPS 서버에 데이터를 업로드할 때 적용됩니다. 기기의 로컬 웹 서버에 HTTPS를 활성화하지는 않습니다.
builtin
builtin은 기본 모드입니다. 이전에 TLS 검증 설정을 저장하지 않았을 때 사용되며, TLS CA 구성을 삭제하거나 기기를 공장 초기화하면 복원됩니다.
펌웨어에는 다음 루트 CA가 포함됩니다.
- DigiCert Global Root G2
- ISRG Root X1
기기는 인증서 체인과 서버 호스트 이름을 모두 검증합니다. MQTTS 브로커 또는 HTTPS 서버는 이 루트 중 하나로 연결되는 인증서를 제시해야 하며, SAN(Subject Alternative Name)이 설정한 서버 주소와 일치해야 합니다.
업로드 주소가 IP 주소라면 인증서 SAN에 정확히 그 IP 주소가 포함되어야 합니다. DNS 이름과 IP 주소가 같은 서버를 가리키더라도 서로 일치하는 것으로 간주되지 않습니다.
custom
custom은 builtin과 같은 체인 및 호스트 이름 검증을 수행하지만 관리자가 업로드한 PEM CA 인증서를 신뢰합니다. 다음 경우에 사용하세요.
- 서버 인증서를 사설 CA가 발급한 경우;
- 자체 서명 서버 인증서를 사용하는 경우;
- 필요한 공개 루트 CA가 펌웨어에 없는 경우.
사설 PKI에서는 해당 루트 CA 인증서를 업로드하세요. TLS 서버는 핸드셰이크 중 필요한 중간 인증서도 보내야 합니다. 자체 서명 서버 인증서는 그 인증서를 신뢰 앵커로 업로드할 수 있지만 SAN은 여전히 설정된 호스트 이름이나 IP 주소와 일치해야 합니다.
none
none도 암호화된 TLS 연결을 만들지만 인증서 체인이나 호스트 이름은 검증하지 않습니다. 서버 인증이 없는 기존 TLS 동작과 비슷합니다.
이 모드는 중간자 공격에 취약합니다. 호환성 확인이나 진단을 위해 일시적으로만 사용하세요. 운영 환경에서는 builtin 또는 custom을 우선 사용하세요.
요구사항과 중요한 적용 범위
TLS CA 설정 API는 로컬 Admin Security가 활성화되어 있어야 합니다. 모든 요청은 설정된 관리자 사용자 이름과 비밀번호를 HTTP Basic Authentication으로 포함해야 합니다.
curl이나 Swagger UI를 실행하는 컴퓨터는 기기의 로컬 IP 주소에 접근할 수 있어야 합니다. MQTTS와 HTTPS 클라이언트는 하나의 검증 모드와 하나의 사용자 CA를 공유하므로 변경은 기기가 사용하는 보안 업로드 모드에 적용됩니다.
TLS 설정을 변경한 뒤 기기를 재시작하여 새 설정으로 아웃바운드 클라이언트가 다시 생성되도록 하세요.
예제에서는 다음 자리표시자를 사용합니다.
DEVICE_IP="192.168.1.80"
ADMIN_USER="admin"
ADMIN_PASSWORD="ExamplePassword1"
실제 기기 주소와 관리자 자격 증명으로 바꾸세요.
현재 TLS 모드 확인
API:
GET /api/tls/ca/status
예:
curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
"http://$DEVICE_IP/api/tls/ca/status"
응답 예:
{
"successful": 1,
"mode": "builtin",
"customCaValid": 0,
"customCaLength": 0,
"customCaSha256": "",
"restartRequiredAfterChange": 1
}
응답에는 선택된 모드가 표시되며, 사용자 CA가 저장되어 있으면 길이와 SHA-256 해시도 표시됩니다.
builtin 검증 선택
API:
POST /api/tls/ca/select
예:
curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
-X POST "http://$DEVICE_IP/api/tls/ca/select" \
-H "Content-Type: application/json" \
-d '{"mode":"builtin"}'
성공 응답을 받은 뒤 기기를 재시작하세요.
임시 진단용 none 선택
API:
POST /api/tls/ca/select
예:
curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
-X POST "http://$DEVICE_IP/api/tls/ca/select" \
-H "Content-Type: application/json" \
-d '{"mode":"none"}'
응답에는 서버 인증서 검증이 비활성화되었다는 경고가 포함됩니다. 모드를 변경한 뒤 재시작하고 진단 후 builtin 또는 custom으로 되돌리세요.
사용자 CA 업로드 및 선택
CA 업로드와 custom 선택은 별도 작업입니다. CA를 업로드해도 활성 모드가 자동으로 바뀌지 않습니다.
사용자 CA 파일 요구사항
업로드 파일은 다음 조건을 모두 충족해야 합니다.
- PEM 인증서 형식;
- JSON이나
multipart/form-data가 아닌 원시 요청 본문; Content-Type: application/x-pem-file;- PEM 헤더, 줄바꿈, 공백을 포함해 1~3072바이트 길이;
-----BEGIN CERTIFICATE-----와-----END CERTIFICATE-----포함;- 개인 키를 포함하지 않음.
3072바이트 제한은 전체 HTTP 요청 본문에 적용됩니다. 3072바이트 PEM 파일은 허용되며 3073바이트 파일은 거부됩니다.
업로드 전에 파일 크기를 확인하세요.
wc -c root-ca.pem
1단계: CA 업로드
API:
POST /api/tls/ca/upload
예:
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
성공 응답 예:
{
"successful": 1,
"length": 1939,
"sha256": "64-character SHA-256 digest",
"message": "CA uploaded; select custom mode and restart"
}
기기는 CA를 여러 KV 블록에 저장하고 활성 상태로 표시하기 전에 저장된 길이와 SHA-256 해시를 확인합니다. 쓰기가 중단되어도 이전의 유효한 CA를 대체하지 않습니다.
2단계: custom 선택
curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
-X POST "http://$DEVICE_IP/api/tls/ca/select" \
-H "Content-Type: application/json" \
-d '{"mode":"custom"}'
유효한 사용자 CA가 저장되지 않았다면 기기는 이 요청을 거부합니다. 알림 없이 none으로 전환하지 않습니다.
3단계: 재시작 및 확인
로컬 Web UI에서 기기를 재시작하거나 보호된 재시작 API를 사용하세요.
curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
"http://$DEVICE_IP/api/restart?reset=false"
기기가 다시 연결되면 상태를 다시 조회하세요.
curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
"http://$DEVICE_IP/api/tls/ca/status"
mode가 custom, customCaValid가 1인지, 보고된 길이와 SHA-256 해시가 업로드한 인증서와 일치하는지 확인하세요.
사용자 CA 삭제
API:
POST /api/tls/ca/delete
예:
curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
-X POST "http://$DEVICE_IP/api/tls/ca/delete"
사용자 CA를 삭제하면 모드도 builtin으로 복원됩니다. 삭제 후 기기를 재시작하세요.
IAMMETER Swagger UI 사용
curl 명령을 직접 작성하지 않고도 같은 API를 테스트할 수 있습니다.
IAMMETER WEM API Test - TLS CA
- 기기의 로컬 IP에 접근할 수 있는 컴퓨터에서 WEM API Test 페이지를 여세요.
192.168.1.80같은 기기 주소를 입력하고 Apply를 선택하세요.- Authorize를 선택해 관리자 사용자 이름과 비밀번호를 입력하세요.
- TLS CA - Authenticated 그룹을 여세요.
GET /api/tls/ca/status로 현재 설정을 확인하세요.- 필요에 따라 업로드, 선택 또는 삭제 작업을 사용하세요.
- 모드나 인증서를 변경한 뒤 기기를 재시작하세요.
Swagger 페이지는 브라우저에서 실행되며 해당 컴퓨터에서 IAMMETER 기기로 직접 요청을 보냅니다. IAMMETER Cloud를 경유하지 않으므로 브라우저는 기기 IP에 직접 네트워크 연결할 수 있어야 합니다.
인증서 검증 문제 해결
admin security required
TLS CA API를 사용하기 전에 Local Admin Security를 활성화하세요. 이 설정은 익명으로 변경할 수 없습니다.
custom CA is missing or invalid
custom을 선택하기 전에 유효한 PEM CA를 성공적으로 업로드하세요. /api/tls/ca/status를 조회해 customCaValid가 1인지 확인하세요.
builtin 또는 custom에서 TLS 연결 실패
다음을 모두 확인하세요.
- 설정된 호스트 이름이나 IP가 인증서 SAN과 일치하는지;
- 인증서가 현재 유효하고 기기 시간이 올바른지;
- 서버가 필요한 중간 인증서를 보내는지;
- 선택한 루트 CA가 서버 인증서를 발급했거나 최종적으로 신뢰하는지;
- TLS 설정 변경 후 기기를 재시작했는지.
none에서는 TLS가 작동하지만 검증 모드에서는 실패
이는 보통 인증서 체인, 호스트 이름, 유효기간 또는 기기 시계 문제를 의미합니다. none을 계속 사용하면 인증 실패를 숨길 뿐 해결하지 못합니다. 인증서 배포를 수정하거나 적절한 루트 CA를 업로드하고 custom을 사용하세요.
