keyroost

FIDO2 / CTAP2 관리

USB-HID 및 PC/SC(NFC, ISO-7816 T=0 접촉식 리더) 경로 모두에서 인증기 정보 조회(`authenticatorGetInfo`), 레지던트 자격증명(패스키) 관리, PIN 설정·변경·검증·재설정, 지문 등록 관리, FIDO Metadata Service(MDS) 표시, client-PIN 프로토콜 v1/v2, CTAP 2.1 보안 정책(`always-require-UV`, 최소 PIN 길이, PIN 변경 강제, enterprise attestation), `large-blob` 저장소를 지원합니다.

OATH (TOTP/HOTP)

PC/SC 기반으로 OATH 계정을 나열·추가·삭제·코드 계산하며, 애플릿 비밀번호 설정·해제·잠금 해제와 공장 초기화(`oath reset –yes`)를 제공합니다. GUI에서는 OTP 비밀 필드의 표시 토글(눈 아이콘)을 통해 커밋 전 비밀을 확인할 수 있습니다.

OpenPGP 카드 (v3.4)

카드 상태 조회, 온카드 키 생성(RSA 2048/3072/4096, Ed25519, X25519, NIST P-256/384/521, secp256k1, brainpool)을 서명·암호화·인증 슬롯에 수행하거나 RSA-2048 키 가져오기, SHA-256/SHA-1 서명, 복호화, INTERNAL AUTHENTICATE 기반 클라이언트/SSH 인증, 카드 소유자 이름/URL 설정, 사용자/관리자 PIN 변경 및 잠금 해제, 공장 초기화를 지원합니다.

PIV (SP 800-73-4)

애플릿/펌웨어 버전·시리얼·PIN 잔여 횟수·슬롯 9A/9C/9D/9E의 인증서 보유 여부 등 상태 조회, 온카드 키 생성, 인증서 가져오기/내보내기, 자체 서명 인증서 또는 CA용 CSR 생성, 슬롯의 인증서 또는 키 삭제, 슬롯 간 키 이동(YubiKey 5.7+), 새 CHUID 발급, PIN/PUK/관리 키 변경, 애플릿 리셋을 지원합니다. 모든 슬롯 명령은 9A/9C/9D/9E뿐 아니라 20개의 Yubico retired 키 관리 슬롯(82–95)까지 대상으로 지정할 수 있어 키 보관 및 순환이 가능합니다.

Token2 Molto2 / Molto2v2 프로그래밍

`otpauth://` URI로 슬롯을 프로그래밍하거나, Aegis(평문 또는 암호화), 2FAS, `otpauth://` URI 목록, PNG/JPEG 스크린샷 또는 화면에서 스캔한 QR 코드로 대량 가져오기를 수행합니다. 호스트 시계 동기화, 고객 키 로테이션, 공장 초기화 기능을 포함합니다.

Token2 단일 프로필 프로그래머블 TOTP 토큰

OTPC-P1-i / P2-i, miniOTP-2-i / 3-i, C301-i, C302-i 모델에 대해 고정 디바이스 키 인증 방식으로 PC/SC 리더를 통해 시드 및 TOTP 설정을 기록합니다. 디바이스 시리얼/모델 인식, 온디바이스 시계 읽기, 시드 쓰기, HMAC 알고리즘·시간 단계·표시 시간 초과 설정(`prog info`/`seed`/`config`)을 지원합니다.

Token2 온디바이스 OTP (PIN+ Series)

Token2 FIDO 보안 키에 TOTP/HOTP 자격증명을 저장하고 USB-HID/NFC/CCID로 코드를 읽으며, 단일 HOTP-on-touch 슬롯 구성, 시리얼 읽기, USB 인터페이스(FIDO/키보드-HID/CCID) 활성화/비활성화를 지원합니다. R3.4+ 키에서는 OTP PIN으로 코드 보호가 가능합니다.

원샷 공장 초기화

`keyroostctl factory-reset –yes` 명령과 GUI의 디바이스 개요 탭은 OATH, OpenPGP, PIV, Token2 OTP, FIDO2 순서로 각 애플릿을 초기화합니다. USB 키에서는 마지막 FIDO2 단계가 분리/재연결 및 터치로 진행되며, 스마트카드 리더의 카드는 인플레이스 전원 사이클로 초기화됩니다.

디바이스 이름 관리

여러 보안 키가 연결된 경우 `keys.json` 레지스트리를 통해 `/dev/hidrawN` 경로 대신 사용자 지정 이름으로 특정 키를 지정할 수 있습니다. Windows에서는 `%APPDATA%` 아래에 레지스트리가 위치하며, 이름에는 안티 스푸핑 검증이 적용됩니다. 파괴적인 작업은 항상 명시적인 대상을 지정해야만 실행됩니다.

Windows (winget)

winget 카탈로그를 통해 GUI와 CLI를 모두 설치할 수 있습니다. 서명된 zip이 배포될 때까지 winget이 동기화되므로, 즉시 사용하려면 GitHub 릴리스에서 직접 zip을 내려받아 PATH에 추가하는 방법도 있습니다.

Linux 및 macOS

Homebrew, AUR(`keyroost-bin`), Flatpak, AppImage 등 다양한 채널을 통해 설치할 수 있습니다. Flatpak은 CLI를 함께 포함하며 자동 업데이트되며, AppImage는 GUI 전용입니다. macOS/Windows의 PC/SC 지원은 내장되어 있지만 FIDO HID 백엔드는 `hidapi`를 통해 자동 동작합니다.

스마트카드 사전 준비

OATH, OpenPGP, PIV 및 Molto2 프로그래밍은 PC/SC를 통해 진행되므로 호스트에 `pcscd` 데몬이 실행 중이어야 합니다. 설치 후 `keyroostctl doctor` 명령은 PC/SC 서비스, 리더, FIDO HID 접근, udev 규칙을 읽기 전용으로 점검합니다.

FIDO HID 접근 (Linux udev 규칙)

`/dev/hidraw*` 노드는 기본적으로 root 전용이므로, 번들된 `udev/70-keyroost-fido.rules`를 `/etc/udev/rules.d/`에 복사한 뒤 `udevadm`으로 규칙을 다시 로드하고 키를 재연결해야 FIDO 인터페이스에 접근할 수 있습니다.

빠른 시작

설치 후 `keyroostctl list`로 연결된 PC/SC 리더와 FIDO 인증기를 확인하고, `keyroostctl doctor`로 환경을 진단할 수 있습니다. FIDO2 명령 예시로는 `fido info`, `fido creds-list –pin-stdin` 등이 있으며, PIN은 인자(argv)가 아닌 표준 입력으로 전달됩니다.

어떤 보안 키를 지원하나요?

Token2 Molto2/Molto2v2, Token2 단일 프로필 프로그래머블 TOTP 토큰, Token2 PIN+ Series, YubiKey 5 시리즈, SoloKeys Solo 2, Nitrokey 3, Swissbit iShield Key 2 Pro가 문서화된 지원 대상이며, 공개 표준을 따르는 모든 FIDO2 인증기에서도 CTAP2 관리 명령이 동작합니다.

설치 후 환경을 어떻게 점검하나요?

`keyroostctl doctor` 명령으로 PC/SC 서비스, 리더, FIDO HID 접근, udev 규칙, 레지스트리 권한을 읽기 전용으로 진단할 수 있습니다.

Windows에서도 모든 기능을 그대로 사용할 수 있나요?

Molto2/OATH/OpenPGP/PIV 기능은 PC/SC를 통해 관리자 권한 없이 동작하지만, FIDO 명령과 FIDO2 탭은 Windows가 raw FIDO HID 접근을 제한하므로 관리자 권한으로 실행해야 합니다.

대량 키 프로비저닝에는 어떤 경로를 권장하나요?

PIV에서 다수의 슬롯이나 키를 프로비저닝할 때는 GUI보다 CLI가 권장됩니다. 관리 키와 PIN을 환경 변수 또는 표준 입력으로 한 번만 전달하면 셸 루프 등으로 일괄 작업을 처리할 수 있습니다.