먼저 마스터 비밀번호로 Vault를 만들거나 잠금을 해제하세요. Settings → Security(설정 → 보안)를 열어 제공자 상태를 확인하고 생체 인증 잠금 해제를 켭니다. 등록할 때는 시스템 인증을 새로 요청합니다. 이후 로그인 화면에서는 마스터 비밀번호 양식과 함께 Touch ID, Windows Hello 또는 지문 잠금 해제가 표시됩니다. Disable and remove enrollment(사용 중지 및 등록 제거)는 이 애플리케이션이 캐시한 키만 제거하며, 운영체제에 등록된 지문은 절대 삭제하지 않습니다.
마스터 비밀번호는 반드시 보관하세요. 취소, 시간 초과, 하드웨어/키링 사용 불가, 등록 무효화 시에는 모두 비밀번호로 잠금을 해제해야 합니다. 생체 인증 등록은 이 사용자, 기기, Vault에만 적용됩니다. 복구 수단도 백업도 아닙니다. Vault를 재설정하면 기존의 SMAZAT 확인을 거친 후에만 등록이 취소되고 기존의 암호화된 프로필과 호스트 지문이 삭제됩니다.
| 플랫폼 | 인증 및 저장 | 요구 사항 및 제한 |
|---|---|---|
| macOS Apple Silicon | 네이티브 LocalAuthentication / Touch ID, biometryCurrentSet 및 WhenUnlockedThisDeviceOnly가 지정된 Security.framework 키체인(Keychain) 항목 |
등록된 Touch ID, 사용 가능한 센서, 사용 가능한 로그인 키체인이 필요합니다. 지문이 바뀌면 항목이 무효화됩니다. 프로덕션 업데이트에는 안정적인 Developer ID 서명을 사용하세요. 애드혹 Alpha 서명은 키체인 신뢰와 로컬 네트워크 권한 추적을 방해할 수 있습니다. |
| Windows x64 | 기본 HWND에 연결된 네이티브 WinRT Windows Hello 데스크톱 상호 운용, Windows 자격 증명 관리자에 저장된 현재 사용자 DPAPI 암호화 키 | 설정된 Hello 지문, 얼굴 또는 PIN이 필요합니다. 이는 편의를 위한 잠금 해제입니다. Hello 승인은 앱이 강제하지만, DPAPI 자체는 생체 인증으로 보호되지 않습니다. 같은 사용자로 실행되는 다른 코드가 자격 증명을 복호화할 수 있습니다. |
| Ubuntu x64 | fprintd D-Bus를 통한 현재 사용자의 등록된 지문, 명시적인 libsecret / Secret Service 자격 증명 저장 | 지원되는 판독기, 등록된 지문, 실행 중인 데스크톱 Secret Service와 기본 키링이 필요합니다. 편의를 위한 잠금 해제이며, 키링의 자격 증명은 지문 확인과 암호학적으로 연결되어 있지 않습니다. basic_text나 일반 텍스트 파일로의 대체는 없습니다. |
Ubuntu에서 선택적으로 사용하는 런타임 패키지는 python3-gi, gir1.2-secret-1, gnome-keyring(또는 호환되는 다른 Secret Service), fprintd입니다. 누락된 패키지는 운영체제의 일반 패키지 관리자로 설치한 다음 운영체제 설정에서 지문을 등록하세요. 인증은 현재 사용자로 이루어지며 root 권한이 필요 없고 PAM도 변경하지 않습니다. 데스크톱 키링이 없는 헤드리스 SSH 세션은 사용할 수 없다고 보고하며, 키를 몰래 다른 곳에 저장하지 않습니다.
잠금 규칙
기존 설치에서는 자동 잠금이 꺼져 있습니다. 켜면 기본값으로 15분이 선택되며, 지원되는 값은 Never, 1, 5, 10, 15, 30, 60분입니다. 애플리케이션 창에서의 키보드 및 마우스 입력은 활동으로 간주되지만, 들어오는 SSH 출력은 활동으로 간주되지 않습니다. 선택적 포커스 해제 시 잠금은 애플리케이션의 플러그인 창을 앱의 일부로 취급하며, 진행 중인 시스템 인증 요청이 끝날 수 있도록 합니다. 이 규칙을 변경하려면 마스터 비밀번호가 필요합니다.
비활성 잠금과 포커스 해제 시 잠금을 포함해 Vault가 잠길 때마다 활성 SSH 세션이 끊기고, 플러그인이 닫히며, 진단이 중지됩니다. 잠그기 전에 원격 편집 내용을 저장하세요. 이는 기존 수동 잠금의 동작을 그대로 유지한 것으로, 잠금 후에는 백그라운드 플러그인이 어떤 SSH 자격 증명도 사용할 수 없습니다.
선택적 민감 작업 정책은 프로필 삭제, 플러그인 설치/제거, 설치 프로그램 실행, 잠금 해제된 Vault의 재설정 시 시스템 인증을 새로 요청합니다. 원격 터미널 명령과 플러그인의 파일 편집은 이 정책의 대상이 아닙니다. 이 정책이 SSH 서버의 권한 부여를 대신하지는 않습니다. 제공자가 작동하지 않으면 마스터 비밀번호로 잠금을 해제하고 그 비밀번호로 정책을 변경하세요. 잠긴 상태의 복구 화면에서는 파괴적 작업 확인을 거쳐 여전히 재설정할 수 있습니다.
Vault 및 IPC 설계
기존 v1 Vault는 계속 scrypt와 AES-256-GCM을 사용하며, 등록으로 인해 파일이 다시 쓰이거나 스키마가 바뀌지 않습니다. 운영체제 자격 증명 저장소로 가는 것은 파생된 32바이트 키의 사본뿐입니다. 평문 마스터 비밀번호는 절대 저장되지 않습니다. 로컬 등록 메타데이터에는 무작위 자격 증명 ID, 제공자, Vault의 변경 불가 메타데이터에 묶인 SHA-256이 들어 있습니다. 복구한 키는 세션을 열기 전에 인증된 복호화를 통과해야 합니다. 메인 프로세스 버퍼는 사용 후 지워집니다. 네이티브 프로토콜 문자열은 일시적으로 프로세스 메모리에 존재할 뿐이며, 관리형 런타임에서 메모리를 완전히 지울 수 있다는 의미는 아닙니다.
도우미 프로그램은 제한된 비공개 stdin/stdout 파이프로 통신하고, 셸 명령을 받지 않으며, 인증 시간 제한이 있고, 정리된 오류 코드를 반환합니다. 도우미 프로그램은 ASAR 바깥의 resources/biometrics에 패키징됩니다. 독립 네이티브 실행 파일이므로 Electron ABI 네이티브 모듈이 필요하지 않습니다. Linux 도우미는 시스템 Python과 GI를 사용합니다. 네이티브 객체와 파생 키는 절대 렌더러/플러그인 브리지를 넘지 않습니다. 생체 인증 IPC는 활성 메인 창과 그 메인 프레임을 검증하므로 플러그인은 이를 호출할 수 없습니다. 명시적으로 잠그면 대기 중인 생체 인증 및 비밀번호 잠금 해제 작업이 취소되어, 늦게 도착한 승인으로 Vault가 다시 열리지 않습니다. 등록을 제거하면 운영체제 저장소가 오프라인이어도 로컬 연결이 취소됩니다. 접근할 수 없는 저장소에는 사용할 수 없는 고아 자격 증명이 남을 수 있습니다.
빌드 및 검증
npm run biometrics:build는 호스트 플랫폼용 도우미를 준비하며, 개발 시작과 릴리스 준비 과정에서 자동으로 실행됩니다. macOS에는 Security와 LocalAuthentication을 포함한 Swift/Apple SDK가, Windows에는 Visual Studio C++ Build Tools, Windows SDK, C++/WinRT가 필요하며, Linux는 Python 도우미를 복사합니다. 새로운 npm 의존성은 추가하지 않습니다. 각 대상 운영체제에서 네이티브로 빌드하세요. macOS 도우미는 번들의 재귀 서명에 포함되며, 이 데스크톱 앱은 샌드박스에서 실행되지 않으므로 App Sandbox 권한이 필요 없습니다. 프로덕션 macOS 배포에는 OpenPGP 릴리스 서명과 별개로 여전히 Developer ID 서명과 공증이 필요합니다.
npm test, npm run test:biometrics:ui, npm run test:diagnostics:ui를 실행하세요. 생체 인증 Node 테스트와 격리된 UI 스모크 테스트는 모의 운영체제 어댑터를 사용하여 성공, 거부/취소, 잘못된 키, 하드웨어/등록 없음, 재설정, 시간 초과 및 늦은 결과, Linux 키링 사용 불가, 운영체제 자격 증명 실패, Windows PIN 승인 응답, macOS 등록 변경, 기존 Vault와의 호환성, IPC 격리, SSH 정리를 다룹니다. 이것으로 하드웨어 인증이 성공한다는 것이 입증되지는 않습니다.
네이티브 컴파일은 macOS arm64와 Windows x64에서 확인했습니다. macOS는 Touch ID를 사용할 수 있다고 보고하고, Windows VM은 Hello를 사용할 수 없다고 보고합니다. 지문/얼굴/PIN 등록, 보호된 키의 실제 조회, 운영체제 대화 상자 취소, 등록 변경에 따른 무효화는 지원되는 각 시스템에서 대화형 하드웨어 테스트가 여전히 필요합니다. Linux 도우미는 지원되는 fprintd 판독기가 있는 데스크톱에서도 추가로 테스트해야 하며, 헤드리스 VM으로는 이를 확인할 수 없습니다.
플랫폼 참고 자료: Apple 생체 인증 접근 제어, Windows 데스크톱 Hello 상호 운용, fprintd 장치 수명 주기, Secret Service 사양.
macOS의 SSH 로컬 네트워크 접근
모든 로컬 SSH 프로필이 connect EHOSTUNREACH로 실패하지만 같은 연결이 '터미널'에서는 작동한다면 System Settings → Privacy & Security → Local Network → CH-J Server Manager(시스템 설정 → 개인정보 보호 및 보안 → 로컬 네트워크 → CH-J Server Manager)를 확인하고 접근을 허용한 뒤, 앱을 완전히 종료했다가 다시 여세요. 이미 허용되어 있다면 권한을 한 번 껐다 켠 뒤 다시 시작하세요. 라우팅, Wi-Fi/이더넷, VPN도 확인하세요. 이 오류만으로 개인정보 보호 권한 거부라고 단정할 수는 없습니다. 이 오류 때문에 Vault를 재설정하거나 신뢰하는 SSH 지문을 버리지 마세요.
앱은 NSLocalNetworkUsageDescription을 선언하며, macOS 네트워크 권한/경로 오류에 대해 현지화된 안내를 제공합니다. 앱이 스스로 권한을 부여할 수는 없습니다. Apple은 macOS가 빌드 간에 네트워크 개인정보 보호 권한을 안정적으로 추적할 수 있도록 Apple이 발급한 서명 ID를 사용할 것을 권장하며, 현재의 애드혹 Alpha 빌드에는 이 제한이 남아 있습니다. Apple의 로컬 네트워크 개인정보 보호 안내를 참고하세요.
Ubuntu 애플리케이션 아이콘
Debian 패키지는 기존 CH-J 아이콘을 표준 hicolor 크기(16–512 px)로 설치하고, 이에 맞는 데스크톱 항목과 Electron 창 클래스를 함께 설정합니다. 메인 창은 다시 만들어질 때도 아이콘을 받습니다. 이미 고정해 둔 이전 실행기를 업데이트한 후에는 고정을 해제하고 새로 설치한 애플리케이션을 고정하세요. 데스크톱에서 로그아웃했다가 다시 로그인하면 오래된 GNOME 실행기 캐시가 새로 고쳐질 수 있습니다.