* **TPM 2.0**: 하드웨어 TPM 2.0 장치(``/dev/tpmrm0`` 또는 ``/dev/tpm0``), 또는 소프트웨어 에뮬레이션 개발용 ``swtpm``.
* **/dev/uhid를 지원하는 Linux 커널**: 가상 FIDO2/CTAP2 브라우저 패스키를 지원하기 위한 사용자 공간 HID 장치에 대한 네이티브 커널 지원(최신 배포판에서 기본 활성화됨).

런타임 종속성

* **Go 1.26** 이상
* **GNU Make**
* **swtpm**(선택 사항, 전체 통합 테스트 스위트 실행에 필요)

패키지 관리자 설치
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Fedora/RHEL/AlmaLinux에서:

.. code-block:: bash

   sudo dnf install golang make tpm2-tools zenity pinentry wl-clipboard swtpm

Arch Linux에서:

.. code-block:: bash

   sudo pacman -S go make tpm2-tools zenity pinentry wl-clipboard swtpm

Debian/Ubuntu에서:

.. code-block:: bash

   sudo apt install golang-go make tpm2-tools zenity pinentry-curses wl-clipboard swtpm

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

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

.. code-block:: bash

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

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

.. code-block:: bash

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

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

.. code-block:: bash

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

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

.. code-block:: bash

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

자동화 스크립트 또는 헤드리스 세션을 위한 캐시 사전 인증:

.. code-block:: bash

   # Unlock cache interactively via TTY:
   ge unlock

   # Or pre-authenticate via pipeline in scripts:
   echo "$PIN" | ge unlock --stdin

   # Purge and lock immediately when finished:
   ge lock


브라우저에서 WebAuthn 패스키:

.. code-block:: bash

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

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

.. code-block:: bash

   ge set-secret my-api-key "super-secret-value"
   ge get-secret my-api-key

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

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

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

사용자 가이드
~~~~~~~~~~~

* `User Quick Start`_ - 5분 안에 시작하기.
* `Installation Guide`_ - 상세한 빌드, udev, systemd 설정.
* `OpenSSH Guide`_ - OpenSSH 에이전트 통합, 점프 호스트, FIDO2 키.
* `GnuPG & Git Signing Guide`_ - OpenPGP 키 관리 및 Git 커밋 서명.
* `Pluggable Factors Guide`_ - 키파일, YubiKey, 생체 인식, Shamir 쿼럼.
* `Security Guide`_ - 하드웨어 TPM 2.0 엔클레이브 및 "Wrap and Clear" 메모리 격리.
* `Configuration Guide`_ - 환경 변수 및 서비스 옵션.
* `CLI Reference`_ - 전체 명령줄 인터페이스 문서.

.. _Functional Spec Index: docs/functional/spec.rst
.. _Technical Spec Index: docs/technical/spec.rst
.. _ADR Index: docs/adrs/index.rst
.. _API Spec Index: docs/api/spec.rst
.. _Roadmap Index: docs/project/roadmap.rst
.. _User Quick Start: docs/user/quickstart.rst
.. _Installation Guide: docs/user/installation.rst
.. _OpenSSH Guide: docs/user/ssh.rst
.. _GnuPG & Git Signing Guide: docs/user/gpg.rst
.. _Pluggable Factors Guide: docs/user/factors.rst
.. _Security Guide: docs/user/security.rst
.. _Configuration Guide: docs/user/configuration.rst
.. _CLI Reference: docs/user/cli.rst

플러그형 팩터 및 다자간 쿼럼 (Phase 7)
------------------------------------------------

**Phase 7: 플러그형 다중 팩터 및 다자간 쿼럼 엔진**은 다음을 제공합니다:

* **스트리밍 임의 파일 해셔**: 짧은 시부터 100GB 오디오 마스터 FLAC 또는 이미지에 이르기까지 모든 파일을 일정한 :math:`\mathcal{O}(1)` 메모리 사용량(:math:`\le 64\,\text{KB}` 버퍼)으로 인증 팩터로 사용할 수 있습니다.
* **다자간 쿼럼("코카콜라 레시피")**: HMAC 검증 태그를 사용한 :math:`\text{GF}(2^8)` 상의 **키 래핑 Shamir 비밀 공유**로, :math:`k`-of-:math:`n` 분할 키 인증을 가능하게 합니다.
* **하드웨어 및 생체 인식**: 물리적 YubiKey(Slot 2 HMAC-SHA1), 물리적 FIDO2 키(``hmac-secret``), Linux 생체 인식(``fprintd``).
* **동적 팩터 재키잉**: 키를 재생성하지 않고 ID의 팩터 정책을 즉시 전환하기 위한 원자적 인메모리 재암호화(``ge rekey``).
* **CLI 현대화**: 명령줄 인터페이스를 표준 ``ge``로 간소화.
* **데스크톱 자동 잠금 해제**: 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

구성 요소
----------

* **genclaved**: 핵심 보안 엔클레이브 및 가상 USB CTAP2/FIDO2 보안 키 데몬(``man 8 genclaved``).
* **ge**: 볼트 관리, OpenSSH/GnuPG 키 생성, 암호화된 구성을 위한 기본 명령줄 도구(``man 1 ge``).
* **age-plugin-ge**: ``age`` 암호화 도구용 플러그인(``man 1 age-plugin-ge``).
* **genclave-gpg**: GnuPG 호환 서명 및 검증을 위한 에뮬레이션 브리지(``man 1 genclave-gpg``).
* **genclave-ui**: PIN 입력을 위한 그래픽 도우미(``man 1 genclave-ui``).

개발
-----------

단위 테스트 실행:

.. code-block:: bash

   make test

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

.. code-block:: bash

   make integration-test

지원 및 기부
-------------------

**gEnclave**가 유용하다고 생각하고 지속적인 개발을 지원하고 싶다면 Liberapay를 통해 기부하는 것을 고려해 보십시오:

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

라이선스
-------

Copyright 2026 EVALinux

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