git-remote-pqcrypt

THIS IS AN EXPERIMENTAL PROJECT, there hasnt been a formal security audit. DO NOT rely on this for any critical repositories.

git-remote-pqcrypt은 gcrypt와 유사한 암호화된 Git 원격 헬퍼입니다. Git packfile과 저장소 메타데이터를 저장 시 암호화합니다. 접근은 양자 내성 XWing 래핑을 사용합니다.

현재 크레이트 버전: 0.2.0.

작동 방식

1. git-remote-pqcrypt init이 저장소 마스터 키를 생성합니다.
2. 각 사용자의 공개 키로 마스터 키를 래핑합니다.
3. Git packfile과 매니페스트를 마스터 키로 암호화합니다.
4. Git은 git-remote-pqcrypt 원격 헬퍼를 통해 pqcrypt를 사용합니다.
5. 헬퍼가 로컬에서 마스터 키를 복호화한 후, packfile을 로컬 저장소로 복호화합니다.

원격 저장소 파일 예시:

keys.json
manifest.enc
objects/
    pack-.....pack.enc

keys.json에는 메타데이터와 암호화된 마스터 키 래핑이 포함됩니다.

설치

Cargo로 빠른 설치

Git에서 기본 빌드를 설치합니다:

cargo install --git https://github.com/Torm0r/git-remote-pqcrypt --locked

이 명령은 git-remote-pqcrypt를 Cargo 바이너리 디렉토리(보통 ~/.cargo/bin)에 설치합니다.

Cargo 바이너리 디렉토리가 PATH에 있는지 확인한 후, 다음 명령으로 작동을 확인합니다:

git-remote-pqcrypt --help

기본 빌드에는 로컬 파일시스템 및 Git 기반 저장소 지원이 포함됩니다.

Unix 계열 시스템에서 SFTP 지원을 설치하려면:

cargo install --git https://github.com/Torm0r/git-remote-pqcrypt --locked --features sftp

sftp 기능은 현재 Windows에서 지원되지 않습니다.

소스에서 빌드

기본 백엔드 지원으로 빌드:

cargo build --release

로컬 파일시스템 및 Git 기반 저장소 지원이 포함됩니다.

Unix 계열 시스템에서 SFTP 지원으로 빌드하려면:

cargo build --release --features sftp

바이너리를 PATH에 설치:

sudo cp target/release/git-remote-pqcrypt /usr/local/bin/

Git은 git-remote-[name] 형식의 원격 헬퍼를 찾으므로 바이너리 이름은 반드시 git-remote-pqcrypt여야 합니다.

작동 확인:

git-remote-pqcrypt --help

요구 사항

• 소스 빌드를 위한 Rust 툴체인
• git이 설치되어 있어야 함
• Git 기반 저장소의 경우, Git 자격 증명과 구성된 Git 아이덴티티 필요
• SSH/SFTP 접근의 경우, 기존 SSH 인증이 구성되어 있어야 함
• SFTP 지원은 --features sftp로 빌드해야 하며, 현재 Unix 계열에서만 가능

빠른 시작

1. 기존 Git 저장소로 이동하거나 새로 만듭니다.

2. pqcrypt 저장소를 초기화합니다.

로컬 경로:

git-remote-pqcrypt init pqcrypt:///path/to/encrypted-store

SFTP는 sftp 기능으로 빌드해야 하며 현재 Unix 계열 시스템에서만 지원됩니다:

git-remote-pqcrypt init pqcrypt::sftp://[email protected]/path/to/store

Git 기반:

git-remote-pqcrypt init pqcrypt::[email protected]:org/store.git

개인 키가 없으면 ~/.config/pqcrypt/key에 생성되고 공개 키가 출력됩니다.

선택적 키 코멘트(예: personal 또는 work-laptop)를 입력하라는 메시지가 표시됩니다.

초기화 후 pqcrypt라는 Git 원격이 추가됩니다:

git remote -v

예시:

pqcrypt  pqcrypt::/path/to/encrypted-store (fetch)
pqcrypt  pqcrypt::/path/to/encrypted-store (push)

3. 푸시:

git push pqcrypt main

4. 클론 또는 페치:

git clone pqcrypt::[email protected]:Torm0r/pqcrypt-test.git my-clone

5. 다른 사용자를 추가합니다.

다른 사용자는 다음 명령으로 키 쌍을 생성해야 합니다:

git-remote-pqcrypt keygen

공개 키를 얻는 방법:

git-remote-pqcrypt pubgen ~/.config/pqcrypt/key

또는 keygen이 출력한 공개 키를 복사할 수 있습니다.

그런 다음 기존 권한 사용자가 저장소에 사용자를 추가합니다:

git-remote-pqcrypt add-user <base64-public-key>

더 많은 옵션을 보려면 다음을 실행하세요:

git-remote-pqcrypt add-user -h

기본적으로 add-user는 URL이 pqcrypt로 시작하는 로컬 Git 원격을 찾아 그곳에 공개 키를 추가합니다.

푸시 동작

pqcrypt는 Git refspec을 기준으로 일반 푸시와 강제 푸시를 구분합니다.

일반 푸시는 fast-forward 검사를 수행하며, 원격 히스토리를 덮어쓰는 경우 거부됩니다.

원격 헬퍼 동작

Git은 git-remote-pqcrypt 바이너리를 통해 pqcrypt를 원격 헬퍼로 호출합니다.

Git이 호출할 때, 헬퍼는 Git이 사용하는 원격 헬퍼 인자 형태를 예상합니다. 예:

git-remote-pqcrypt origin pqcrypt::/path/to/store

init, add-user, keygen, pubgen, help와 같은 직접 CLI 서브명령은 원격 헬퍼 호출이 아닌 일반 사용자 명령으로 처리됩니다.

바이너리 진입점은 라이브러리 런타임에 위임되므로, 설치된 바이너리를 통해서뿐만 아니라 크레이트 라이브러리를 통해서도 애플리케이션 로직을 테스트할 수 있습니다.

Git 기반 저장소 캐시

Git 기반 저장소 URL의 경우 pqcrypt는 시스템 캐시 디렉토리 아래에 로컬 캐시를 유지합니다. 예:

~/.cache/pqcrypt/

pqcrypt는 작업 전에 백업 Git 저장소에서 암호화된 상태를 가져오고, 업데이트 후 암호화된 상태를 푸시합니다.

캐시 손상 또는 캐시 손실이 감지되면 pqcrypt는 백업 Git 저장소에서 다시 가져와 캐시를 자동으로 재생성합니다.

URL 형식

pqcrypt::, pqcrypt://, pqcrypt: 모두 허용되며 내부적으로 pqcrypt::로 정규화됩니다.

다음은 동일합니다:

git-remote-pqcrypt init pqcrypt:///path/to/store
git-remote-pqcrypt init pqcrypt::/path/to/store
git-remote-pqcrypt init pqcrypt:/path/to/store

백엔드는 저장소 경로에 따라 결정됩니다:

예시:

pqcrypt::/tmp/store
pqcrypt:///tmp/store
pqcrypt:/tmp/store
pqcrypt::[email protected]:org/store.git
pqcrypt::https://github.com/org/store.git
pqcrypt::sftp://[email protected]/path/to/store

개인 키 탐색 로직

복호화 시 pqcrypt는 다음 순서로 개인 키를 찾습니다:

1. PQCRYPT_KEY_PATH 환경 변수
2. git config pqcrypt.keypath
3. 현재 디렉토리의 .pqcrypt/key
4. ~/.config/pqcrypt에서 일치하는 모든 키 파일(모두 테스트)

여러 키 설정(예: 업무용 및 개인용 키)의 경우:

git config pqcrypt.keypath ~/.config/pqcrypt/work-key

키는 init 중에 사용되었거나 add-user로 추가된 것이어야 합니다.

개발

전체 테스트 스위트 실행:

cargo test

Unix 계열 시스템에서 SFTP 활성화하여 실행:

cargo test --features sftp

Windows에서는 Unix 계열 로컬 경로 동작에 의존하는 일부 엔드투엔드 테스트가 무시됩니다.

CI 빌드

GitHub Actions는 Linux, macOS, Windows에서 프로젝트를 빌드합니다. 워크플로 아티팩트에는 CI 실행의 바이너리가 포함될 수 있지만, 이는 공식 릴리스가 아닙니다.

보안 정보

• 저장소 내용은 XChaCha20Poly1305를 사용하여 암호화됩니다.
• 저장소 마스터 키는 XWing이 포함된 HPKE를 사용하여 사용자에게 래핑됩니다.
• 각 권한 있는 공개 키는 마스터 키의 암호화된 복사본을 받습니다.
• 키에 첨부된 코멘트는 HPKE 연관 데이터로 인증됩니다. 즉, 코멘트 메타데이터가 손상되면 해당 래핑에 대해 마스터 키가 더 이상 복호화되지 않을 수 있습니다.
• Git refs 및 packfile 메타데이터는 암호화된 매니페스트 내에 저장됩니다.
• 개인 키 파일은 Unix 계열 시스템에서 0600 권한으로 생성됩니다.

제한 사항

• 이 프로젝트는 실험적이며 공식 보안 감사를 받지 않았습니다.
• 현재 로컬 파일시스템, Git 기반, 선택적 SFTP 저장소 백엔드만 지원됩니다.
• SFTP 지원은 선택적 sftp 기능 뒤에 있으며 현재 Windows에서는 지원되지 않습니다.
• SFTP/Git 백엔드는 강력한 분산 잠금이 부족하므로 동시 푸시로 인해 데이터 손실이 발생할 수 있습니다.
• Git 원격 헬퍼 동작은 아직 상대적으로 최소화되어 있으며, 모든 Git 워크플로나 CI/CD 작업을 지원하지 않을 수 있습니다.
• 강제 푸시는 지원되지만, 일반 Git 강제 푸시와 마찬가지로 암호화된 원격 히스토리를 덮어쓸 수 있습니다.
• HPKE 크레이트는 게시된 크레이트 릴리스에서 XWing이 아직 지원되지 않으므로 Git 소스에 의존합니다. HPKE가 업데이트되면 변경될 예정입니다.
• 사용자 접근을 취소하거나 제거할 방법이 없습니다. 사용자가 Git 히스토리에서 마스터 키를 복구할 수 있으므로, 가장 좋은 방법은 새 마스터 키로 저장소를 다시 초기화하고 원격을 삭제하는 것입니다.
• 향후 버전에서 저장소 형식이 변경될 수 있습니다.
• Git 기반 저장소는 커밋을 위해 Git 자격 증명과 구성된 Git 아이덴티티가 필요합니다.
• Git, SSH 또는 SFTP 인증을 위해 pqcrypt는 기존 SSH/Git 자격 증명에 의존합니다.
• ssh와 git이 설치되어 있어야 합니다.