로컬 관리자 보안: 사용자 가이드

로컬 관리자 보안 모듈은 펌웨어 i.91.065.3 이상에서 사용할 수 있습니다.

목적

로컬 관리자 보안 모듈은 장치의 로컬 Web UI와 민감한 로컬 API를 무단 접근으로부터 보호합니다.

이 기능이 활성화되면 다음 작업에 관리자 사용자 이름과 비밀번호가 필요합니다:

WEM API 테스트 페이지에서 사용할 수 있는 모든 Set API;
민감한 구성 데이터를 반환하거나 민감한 작업을 수행하는 GET API;
로컬 OTA 펌웨어 업로드 및 업그레이드 작업.

여기에는 네트워크 또는 업로드 설정 변경, 펌웨어 업데이트, 장치 다시 시작, 공장 설정 복원 및 기타 민감한 구성 매개변수 수정과 같은 작업이 포함됩니다.

이 모듈은 다음을 제공합니다:

구성 가능한 관리자 자격 증명;
보호된 로컬 API에 대한 HTTP Basic Authentication;
Web UI 또는 API를 통한 자격 증명 변경;
관리자 비밀번호를 분실한 경우 Ed25519 서명 기반 복구 프로세스.

이 기능은 이전 펌웨어와의 호환성을 위해 기본적으로 비활성화되어 있습니다. 보호된 접근이 적용되기 전에 활성화하고 구성해야 합니다.

현재 로컬 Web UI는 HTTP를 사용합니다. HTTP Basic Authentication은 자격 증명을 인코딩하지만 암호화하지는 않습니다. 추가적인 보안 전송 메커니즘을 통해 장치에 접근하지 않는 경우 신뢰할 수 있는 로컬 네트워크에서 이 기능을 사용하십시오.

Web UI에서 관리자 보안 구성하기

브라우저에서 장치 IP 주소를 엽니다.
Security 탭을 선택합니다.
관리자 사용자 이름을 입력합니다.
관리자 비밀번호를 입력하고 확인합니다.
Enable Admin Security를 선택합니다.

사용자 이름과 비밀번호는 다음 규칙을 충족해야 합니다:

길이: 1~32자;
표시 가능한 ASCII 문자만 사용 가능;
콜론(:), 큰따옴표(") 또는 백슬래시(\)는 허용되지 않습니다.

Admin Security가 활성화되면 보호된 페이지나 API에 접근할 때 브라우저에 인증 프롬프트가 표시됩니다. 구성된 관리자 사용자 이름과 비밀번호를 입력합니다.

Security 탭은 다음 용도로도 사용할 수 있습니다:

관리자 사용자 이름 및 비밀번호 변경;
관리자 인증이 활성화되었는지 확인;
포트 502에서 Modbus/TCP 서비스 활성화 또는 비활성화;
SSDP 검색 활성화 또는 비활성화;
현재 자격 증명으로 인증한 후 Admin Security 비활성화.

관리자 자격 증명 컨트롤, Modbus TCP 및 SSDP 서비스 스위치를 보여주는 IAMMETER 로컬 Web UI Security 탭

Modbus/TCP 또는 SSDP 서비스 상태 변경은 장치 다시 시작이 필요합니다. 이전 펌웨어에서 이러한 설정이 저장된 적이 없는 경우, 두 서비스 모두 이전 버전과의 호환성을 위해 기본적으로 활성화됩니다.

브라우저는 장치 주소에 대한 Basic Authentication 자격 증명을 캐시할 수 있습니다. 비밀번호를 변경한 후 브라우저가 먼저 이전 자격 증명을 재시도한 다음 새 인증 프롬프트를 표시할 수 있습니다. 모든 브라우저 창을 닫거나 시크릿 브라우징 창을 사용하여 새 로그인을 강제할 수도 있습니다.

Basic Authentication이 필요하지 않은 API

Web UI가 기본 장치 정보를 로드하고 서명된 복구 프로세스가 작동할 수 있도록 다음 엔드포인트는 Basic Authentication 헤더 없이도 사용할 수 있습니다:

메서드	엔드포인트	목적
GET	`/api/admin/status`	Admin Security가 활성화되었는지와 서명된 복구가 지원되는지 여부를 반환합니다.
GET	`/api/admin/recovery_challenge`	장치별 일회성 복구 페이로드를 생성합니다.
GET	`/api/getbrand`	로컬 Web UI 브랜딩 구성을 반환합니다.
GET	`/api/monitor`	로컬 Web UI에서 사용하는 현재 장치 및 미터 모니터링 데이터를 반환합니다.
GET	`/api/monitorjson`	`/api` 호환성 경로를 통해 레거시 모니터링 응답을 반환합니다.
GET	`/monitorjson`	레거시 모니터링 응답을 반환합니다.
GET	`/api/sntpstatus`	현재 SNTP 상태를 반환합니다.
GET	`/info.xml`	UPnP 스타일 장치 정보를 반환합니다.
POST	`/api/admin/recovery`	IAMMETER 복구 서명을 확인하고 분실된 관리자 자격 증명을 지웁니다.

POST /api/admin/enable은 Admin Security가 현재 비활성화된 경우 Basic Authentication 없이도 호출할 수 있습니다. 이는 초기 설정에 사용되는 엔드포인트이기 때문입니다. Admin Security가 이미 활성화된 경우, 이 엔드포인트가 보안 구성을 변경하거나 비활성화하려면 현재 유효한 관리자 자격 증명이 필요합니다.

정적 Web UI 파일 및 기타 /api/가 아닌 GET 리소스는 API 엔드포인트가 아니며 공개적으로 읽을 수 있습니다. Admin Security가 활성화되면 모든 Set API, 민감한 GET API 및 OTA 펌웨어 작업을 포함한 다른 모든 로컬 API 엔드포인트가 보호된 것으로 처리됩니다.

API 참조

GET `/api/admin/status`

현재 Admin Security 상태를 반환합니다. 인증이 필요하지 않습니다.

응답 예시:

{
  "enabled": 1,
  "hasPassword": 1,
  "recoverySupported": 1,
  "modbusTcpEnabled": 1,
  "ssdpEnabled": 1
}

필드:

enabled: Admin Security가 활성화된 경우 1, 그렇지 않으면 0.
hasPassword: 관리자 자격 증명이 구성된 경우 1.
recoverySupported: 펌웨어에서 서명된 관리자 복구가 지원되는 경우 1.
modbusTcpEnabled: 포트 502에서 Modbus/TCP 서비스가 활성화된 경우 1.
ssdpEnabled: SSDP 검색이 활성화된 경우 1.

POST `/api/admin/enable`

Admin Security를 활성화 또는 비활성화합니다.

Admin Security 활성화:

POST /api/admin/enable
Content-Type: application/json

{
  "enable": 1,
  "username": "admin",
  "password": "ExamplePassword"
}

curl 사용 예시:

curl -X POST "http://<device-ip>/api/admin/enable" \
  -H "Content-Type: application/json" \
  -d '{"enable":1,"username":"admin","password":"ExamplePassword"}'

Admin Security 비활성화:

POST /api/admin/enable
Authorization: Basic <base64...자격증명>
Content-Type: application/json

{
  "enable": 0
}

Admin Security가 이미 활성화된 경우, 이 API를 호출하려면 현재 유효한 Basic Authentication 자격 증명이 필요합니다.

예시:

curl -X POST "http://<device-ip>/api/admin/enable" \
  -u admin:ExamplePassword \
  -H "Content-Type: application/json" \
  -d '{"enable":0}'

POST `/api/admin/password`

관리자 사용자 이름과 비밀번호를 변경합니다. 이 API는 Admin Security가 활성화된 후 보호됩니다.

POST /api/admin/password
Authorization: Basic <현재...자격증명>
Content-Type: application/json

{
  "username": "newadmin",
  "password": "NewExamplePassword"
}

예시:

curl -X POST "http://<device-ip>/api/admin/password" \
  -u admin:ExamplePassword \
  -H "Content-Type: application/json" \
  -d '{"username":"newadmin","password":"NewExamplePassword"}'

요청이 성공한 후, 이후 보호된 요청에는 새 자격 증명을 사용합니다.

GET `/api/admin/check`

제공된 Basic Authentication 자격 증명이 유효한지 확인합니다.

curl -u admin:ExamplePassword \
  "http://<device-ip>/api/admin/check"

성공 응답:

{
  "successful": 1
}

자격 증명이 없거나 유효하지 않은 경우 HTTP 401 Unauthorized가 반환됩니다.

GET `/api/admin/recovery_challenge`

장치별 일회성 복구 페이로드를 생성합니다. 이 엔드포인트는 자체적으로 자격 증명을 재설정하지 않으므로 인증이 필요하지 않습니다.

응답 예시:

{
  "successful": 1,
  "alg": "ed25519",
  "payload": "reset_admin|DEVICE_SN|DEVICE_MAC|ONE_TIME_NONCE"
}

반환된 payload는 관리자 복구가 필요할 때 IAMMETER로 전송되어야 합니다.

새 챌린지를 요청하면 이전 챌린지가 무효화됩니다. 챌린지는 성공적인 복구 또는 장치 다시 시작 후에도 무효화됩니다.

POST `/api/admin/recovery`

복구 페이로드와 IAMMETER에서 제공한 Ed25519 서명을 제출합니다.

POST /api/admin/recovery
Content-Type: application/json

{
  "payload": "reset_admin|DEVICE_SN|DEVICE_MAC|ONE_TIME_NONCE",
  "signature": "128-hex-character-ed25519-signature"
}

예시:

curl -X POST "http://<device-ip>/api/admin/recovery" \
  -H "Content-Type: application/json" \
  -d '{"payload":"reset_admin|DEVICE_SN|DEVICE_MAC|ONE_TIME_NONCE","signature":"<signature-from-IAMMETER>"}'

서명 확인이 성공하면 장치는 로컬 관리자 자격 증명을 지우고 Admin Security를 비활성화합니다. 그런 다음 새 관리자 사용자 이름과 비밀번호를 구성할 수 있습니다.

장치에 서명 확인을 실행할 충분한 여유 메모리가 없는 경우, API는 다음과 유사한 응답을 반환합니다:

{
  "successful": 0,
  "message": "low memory, please change to standalone mode",
  "freeMemory": 18000,
  "minFreeRequired": 28000
}

이 경우 메모리 사용량을 줄이고 재시도하기 전에 새 복구 챌린지를 요청하십시오. 비밀번호를 사용할 수 없고 작동 모드를 변경할 수 없는 경우, MQTTS 또는 HTTPS 연결이 추가 메모리를 소비하기 전에 장치를 다시 시작하고 복구를 수행하십시오.

비밀번호 복구 작동 방식

복구 설계는 관리자 보호를 우회할 수 있는 인증되지 않은 공장 초기화 명령을 추가하지 않습니다.

이 프로세스는 Ed25519 공개/개인 키 쌍을 사용합니다:

장치 펌웨어에는 IAMMETER 복구 공개 키만 포함됩니다;
해당 개인 키는 IAMMETER가 보유하며 장치에 저장되지 않습니다;
장치는 요청된 작업, 장치 SN, 장치 MAC 및 일회성 논스를 포함하는 페이로드를 생성합니다;
IAMMETER는 복구 개인 키로 해당 정확한 페이로드에 서명합니다;
장치는 내장된 공개 키로 서명을 확인합니다;
현재 장치 및 현재 논스에 대한 유효한 서명만 관리자 구성을 지울 수 있습니다.

논스는 RAM에만 저장됩니다. 장치가 다시 시작되거나, 다른 챌린지가 요청되거나, 한 번의 성공적인 복구 후에 무효화됩니다. 따라서 이전 페이로드와 서명을 이후 복구 세션에 재사용할 수 없습니다.

사용 시나리오

시나리오 1: 관리자 사용자 이름 및 비밀번호 설정

가장 간단한 방법은 Web UI입니다:

http://<device-ip>/를 엽니다.
Security 탭을 엽니다.
새 관리자 사용자 이름과 비밀번호를 입력합니다.
비밀번호를 확인합니다.
Admin Security를 활성화합니다.

동일한 작업을 POST /api/admin/enable을 통해 수행할 수 있습니다:

curl -X POST "http://<device-ip>/api/admin/enable" \
  -H "Content-Type: application/json" \
  -d '{"enable":1,"username":"admin","password":"ExamplePassword"}'

결과 확인:

curl "http://<device-ip>/api/admin/status"

시나리오 2: Basic Authentication으로 보호된 API 접근

이후의 모든 보호된 요청에 대해 HTTP Basic Authentication 헤더에 관리자 사용자 이름과 비밀번호를 전송합니다.

헤더 값은 다음과 같이 구성됩니다:

Authorization: Basic Base64...인코딩된자격증명

예를 들어, 자격 증명 admin:ExamplePassword는 먼저 결합된 다음 Base64로 인코딩됩니다. 대부분의 HTTP 클라이언트는 이를 자동으로 수행합니다.

curl 사용:

curl -u admin:ExamplePassword \
  "http://<device-ip>/api/getadv"

명시적 헤더 사용:

TOKEN=$(printf '%s' 'admin:ExamplePassword' | base64)

curl "http://<device-ip>/api/getadv" \
  -H "Authorization: Basic ***"

JSON POST 요청의 경우:

curl -X POST "http://<device-ip>/api/setadv" \
  -u admin:ExamplePassword \
  -H "Content-Type: application/json" \
  -d '<setadv-json-body>'

관리자가 Basic Authentication 프롬프트에 자격 증명을 입력하면 브라우저가 이 헤더를 자동으로 처리합니다.

현재 Web UI는 펌웨어를 POST /api/ota_successful.html로 업로드합니다. 레거시 POST /ota_successful.html 엔드포인트는 이전 Web UI 버전 및 외부 도구에서 계속 사용할 수 있습니다. 두 엔드포인트 모두 Admin Security가 활성화된 경우 Basic Authentication이 필요합니다.

인증 프롬프트가 닫힐 때 Web UI 탭의 동작은 다음과 같습니다:

Settings 및 Wi-Fi는 보호된 구성 API를 로드할 수 없으며 관리자 인증 메시지를 표시합니다.
System은 공개 /api/monitor 엔드포인트에서 얻은 값이므로 SN, MAC 및 펌웨어 버전을 계속 표시할 수 있습니다. OTA 업로드는 보호된 상태로 유지됩니다.
Security는 /api/admin/status가 공개이므로 기본 상태를 계속 표시할 수 있습니다. 자격 증명 변경 및 서비스 스위치 변경은 보호된 상태로 유지됩니다.

시나리오 3: 비밀번호를 분실한 후 접근 복구

장치에는 하드웨어 재설정 버튼이 없습니다. Admin Security를 우회할 수 있는 인증되지 않은 재설정 기능을 추가하지 않기 위해, 장치는 위에서 설명한 서명된 복구 메커니즘을 사용합니다.

이 절차는 관리자 사용자 이름과 비밀번호를 모두 분실한 경우에만 사용하기 위한 것입니다. 구성된 자격 증명을 안전한 장소에 보관하고 일상적인 자격 증명 변경을 위해 복구 프로세스에 의존하지 마십시오. 현재 자격 증명을 아직 사용할 수 있는 경우 Security 탭에서 직접 또는 POST /api/admin/password를 통해 변경하십시오.

장치에서 새 복구 챌린지를 요청합니다:

curl "http://<device-ip>/api/admin/recovery_challenge"

응답에서 전체 payload 값을 복사합니다. SN, MAC, 논스, 구분 기호 또는 대소문자를 편집하지 마십시오.
support@devicebit.com으로 IAMMETER 지원팀에 연락하여 전체 페이로드를 제출합니다.
소유권 또는 서비스 권한이 확인된 후, IAMMETER가 페이로드에 서명하고 Ed25519 서명을 반환합니다.

원본 페이로드와 반환된 서명을 장치에 제출합니다:

curl -X POST "http://<device-ip>/api/admin/recovery" \
  -H "Content-Type: application/json" \
  -d '{"payload":"<original-payload>","signature":"<signature-from-IAMMETER>"}'

성공적인 응답 후, Admin Security가 비활성화되고 이전 관리자 자격 증명이 지워집니다. Security 탭을 열거나 POST /api/admin/enable을 호출하여 새 자격 증명을 설정합니다.

서명을 기다리는 동안 장치를 다시 시작하거나 다른 챌린지를 요청하지 마십시오. 두 작업 모두 제출된 페이로드를 무효화하며, 복구 프로세스를 새 챌린지로 다시 시작해야 합니다.

로컬 관리자 보안: 사용자 가이드

로컬 관리자 보안: 사용자 가이드

목적

Web UI에서 관리자 보안 구성하기

Basic Authentication이 필요하지 않은 API

API 참조

GET /api/admin/status

POST /api/admin/enable

POST /api/admin/password

GET /api/admin/check

GET /api/admin/recovery_challenge

POST /api/admin/recovery

비밀번호 복구 작동 방식

사용 시나리오

시나리오 1: 관리자 사용자 이름 및 비밀번호 설정

시나리오 2: Basic Authentication으로 보호된 API 접근

시나리오 3: 비밀번호를 분실한 후 접근 복구

Wi-Fi 에너지 미터

GET `/api/admin/status`

POST `/api/admin/enable`

POST `/api/admin/password`

GET `/api/admin/check`

GET `/api/admin/recovery_challenge`

POST `/api/admin/recovery`