gpasskey

.. image:: https://gitlab.com/renich/gpasskey/-/raw/master/assets/logo.svg :width: 140px :align: center :alt: gpasskey logo

Linux를 위한 중앙 집중식 암호화 ID 엔클레이브.

.. caution::

사전 알파(Pre-Alpha) 소프트웨어 — 사용 시 본인 책임입니다!

릴리스 번호와 관계없이 gpasskey는 현재 급속한 아키텍처 개발이 진행 중인 실험적인 사전 알파 소프트웨어입니다. 암호화 스키마, 볼트 형식, 프로토콜 브리지는 이전 버전과의 호환성 없이 변경될 수 있습니다.

키 및 데이터 손실 위험이 높음: 24단어 BIP39 복구 문구를 항상 기록하고 안전하게 보관하세요.
보조 2FA 유지: 프로덕션 계정에 가상 FIDO2 보안 키를 등록할 때 항상 보조 2FA 방법(TOTP 또는 백업 복구 코드)을 구성하세요.
보증 없음: GNU GPLv3 라이선스에 따라 어떠한 종류의 보증도 없이 "있는 그대로" 제공됩니다.

개요

gpasskey는 개인 키를 암호화된 볼트에 저장하는 하드웨어 기반 보안 엔클레이브를 제공합니다. SSH 에이전트, age 암호화 플러그인 프로토콜, GnuPG 커밋 서명 에뮬레이션을 지원하는 다중 프로토콜 브리지 역할을 합니다.

주요 기능

다중 프로토콜 지원:
- FIDO2 / CTAP2 패스키: 네이티브 브라우저(Firefox, Chrome, Chromium) 및 OS 패스키 인증을 위한 /dev/uhid 기반 가상 USB 보안 키 에뮬레이터.
- SSH 에이전트: OpenSSH 호환 에이전트 프로토콜.
- age-plugin: age (v1) 파일 암호화에 대한 네이티브 지원.
- GnuPG 브리지: Git 커밋 서명 및 검증을 원활하게 하도록 GPG CLI를 에뮬레이션합니다.
하드웨어 기반 보안: 개인 키는 AES-256-GCM으로 암호화되며, SRK 캐싱을 통해 주로 TPM 2.0에 봉인됩니다.
암호화 PIN 바인딩 및 UV 캐시: 모든 작업은 잠긴 RAM(mlock)에 15초 보안 세션 캐시를 두고 PIN 파생 하위 키에 바인딩됩니다.
Argon2id KDF: 마스터 패스프레이즈, 복구 및 하위 키에 대한 메모리 하드 키 유도.
무차별 대입 공격 방지: 실패한 인증 시도에 대한 자동 지수 백오프.
지능형 UI 라우팅: 인증 프롬프트를 위한 자동 세션 감지(GUI vs TTY).
안전한 메모리: mmap/mlock 및 "Wrap and Clear" 전략을 사용하여 키 자료가 스왑이나 GC 힙으로 유출되는 것을 방지합니다.
ID 관리: 볼트 관리 및 암호화된 비밀 관리용 강력한 CLI(gpasskey-cli).

TPM 2.0 통합

gpasskey는 TPM 2.0을 통한 하드웨어 기반 보안을 지원합니다. 이를 통해 마스터 키가 암호화되지 않은 채 TPM을 벗어나지 않으며 시스템 부팅 상태에 바인딩됩니다.

요구 사항


* TPM 2.0 호환 장치(또는 개발용 ``swtpm``).
* 시스템에 ``tpm2-tools``가 설치되어 있어야 합니다.

초기화

TPM 저장소는 새 ID를 생성할 때 자동으로 초기화됩니다. TPM 상태를 확인하려면:

.. code-block:: bash

gpasskey-cli status

사용법


초기화되면 TPM은 데몬에 의해 투명하게 사용됩니다. 모든 민감한 데이터는 **PCR 0**(코어 시스템 펌웨어) 및 **PCR 7**(보안 부팅 상태)에 대해 봉인됩니다. 펌웨어나 Secure Boot 구성이 수정되면 볼트 잠금이 해제되지 않으므로 오프라인 공격과 무단 OS 변조를 방지할 수 있습니다.

빠른 시작
-----------

사용자 계정에 빌드 및 설치(권장, 비루트)::

   make clean && make all
   make install-user   # Installs to ~/.local/bin, ~/.config/systemd/user, ~/.local/share/dbus-1

또는 시스템 전체에 설치(루트 필요)::

   sudo make install   # Installs to /usr/local/bin

소켓 활성화를 활성화 및 시작::

   systemctl --user enable --now gpasskey-ssh.socket gpasskey-gpg.socket

볼트를 초기화하고 상태 확인::

   gpasskey-cli status
   # Identities are enrolled automatically on first use by clients 
   # (WebAuthn passkeys, SSH, age, GPG) or via the portal API.

브라우저에서 WebAuthn 패스키::

   # Open Firefox or Chrome, go to https://webauthn.io/
   # Click "Register" -> enter your PIN in the gpasskey prompt -> Passkey is created!
   # Click "Authenticate" -> enter your PIN -> Instant login verified!

TPM 기반 구성 저장소에서 암호화된 비밀 관리::

   gpasskey-cli set-secret my-api-key "super-secret-value"
   gpasskey-cli get-secret my-api-key

문서 및 사양
------------------------------

포괄적인 엔지니어링 문서는 모듈식 사양, 아키텍처 기록, 로드맵으로 구성됩니다:

* **기능 사양**: `기능 사양 색인`_ — 사용자 요구 사항 및 권한 부여 모델을 정의합니다.
* **기술 청사진**: `기술 사양 색인`_ — 상세한 Go 아키텍처, 암호화 기본 요소, 엔클레이브 설계.
* **아키텍처 결정 기록(ADR)**: `ADR 색인`_ — 아키텍처, 암호화, 보안 선택에 대한 불변 로그.
* **API 및 와이어 프로토콜**: `API 사양 색인`_ — 관리 소켓, D-Bus 포털, 브리지 와이어 스키마.
* **프로젝트 실행 로드맵**: `로드맵 색인`_ — 단계별 엔지니어링 일정 및 마일스톤 산출물.

사용자 가이드

사용자 빠른 시작_ - 5분 안에 시작하기.
설치 가이드_ - 상세한 빌드, udev, systemd 설정.
보안 가이드_ - 하드웨어 TPM 2.0 엔클레이브 및 "Wrap and Clear" 메모리 격리.
구성 가이드_ - 환경 변수 및 서비스 옵션.

.. _기능 사양 색인: docs/functional/spec.rst .. _기술 사양 색인: docs/technical/spec.rst .. _ADR 색인: docs/adrs/index.rst .. _API 사양 색인: docs/api/spec.rst .. _로드맵 색인: docs/project/roadmap.rst .. _사용자 빠른 시작: docs/user/quickstart.rst .. _설치 가이드: docs/user/installation.rst .. _보안 가이드: docs/user/security.rst .. _구성 가이드: docs/user/configuration.rst

현재 계획 중인 기능 (7단계)

현재 7단계: 플러그형 다중 요소 및 다자간 쿼럼 엔진을 설계하고 아키텍처를 구축 중입니다:

스트리밍 임의 파일 해셔: 일정한 :math:\mathcal{O}(1) 메모리 사용량(:math:\le 64\,\text{KB} 버퍼)으로 모든 파일(짧은 시 텍스트부터 100GB 오디오 마스터 FLAC 또는 이미지까지)을 인증 요소로 사용합니다.
다자간 쿼럼("코카콜라 레시피"): HMAC 검증 태그가 있는 :math:\text{GF}(2^8) 기반 키 래핑 샤미르 비밀 공유로 :math:k-of-:math:n 분할 키 인증을 지원합니다.
하드웨어 및 생체 인식: 물리적 YubiKey(Slot 2 HMAC-SHA1), 물리적 FIDO2 키(hmac-secret), Linux 생체 인식(fprintd).
동적 요소 재키잉: 키를 다시 만들지 않고 ID의 요소 정책을 즉시 전환하는 원자적 인메모리 재암호화(gpk rekey).
CLI 현대화: 명령줄 인터페이스를 표준 gpk(/usr/local/bin/gpk)로 간소화.
데스크톱 자동 잠금 해제: Freedesktop Secret Service(org.freedesktop.secrets)와 원활한 통합.

전체 사양은 Phase 7 Roadmap_ 및 ADR-006_을 참조하세요.

.. _Phase 7 Roadmap: docs/project/roadmaps/phase-7-pluggable-factors.rst .. _ADR-006: docs/adrs/2026-08-25-pluggable-auth-factors.rst

구성 요소

gpasskeyd: 핵심 보안 엔클레이브 및 가상 USB CTAP2/FIDO2 보안 키 데몬.
gpasskey-cli: 볼트 관리 및 암호화 구성을 위한 관리 도구.
age-plugin-gpasskey: age 암호화 도구용 플러그인.
gpasskey-gpg: GnuPG 호환 서명 및 검증용 에뮬레이션 브리지.
gpasskey-ui: PIN 입력용 그래픽 도우미.

개발

단위 테스트 실행::

make test

전체 Go 네이티브 통합 테스트 스위트 실행(swtpm 필요)::

make integration-test

지원 및 기부

gpasskey가 유용하다고 생각하시고 지속적인 개발을 지원하고 싶다면 Liberapay를 통한 기부를 고려해 주세요:

.. image:: https://liberapay.com/assets/widgets/donate.svg :target: https://liberapay.com/Renich/donate :alt: Donate using Liberapay

라이선스

이 프로젝트는 GNU General Public License v3.0 이상에 따라 라이선스가 부여됩니다. 자세한 내용은 LICENSE 파일을 참조하세요.

gpasskey

인기

gpasskey

개요

주요 기능

TPM 2.0 통합

현재 계획 중인 기능 (7단계)

구성 요소

개발

지원 및 기부

라이선스