git-remote-pqcrypt

ESTO ES UN PROYECTO EXPERIMENTAL, no ha pasado por una auditoría de seguridad formal. NO confíes en esto para repositorios críticos.

git-remote-pqcrypt es un ayudante remoto de Git cifrado similar a gcrypt. Almacena los paquetes (packfiles) de Git y los metadatos del repositorio cifrados en repositorio. El acceso se realiza con el envoltorio post-cuántico XWing.

Versión actual del crate: 0.2.0.

Cómo funciona

1. git-remote-pqcrypt init crea una clave maestra del repositorio.
2. La clave maestra se envuelve para cada usuario con su clave pública.
3. Los paquetes de Git y el manifiesto se cifran usando la clave maestra.
4. Git utiliza pqcrypt a través del ayudante remoto git-remote-pqcrypt.
5. La clave maestra se descifra localmente por el ayudante y luego los paquetes se descifran en el repositorio local.

Ejemplo de archivos del almacenamiento remoto:

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

keys.json contiene metadatos y envolturas cifradas de la clave maestra.

Instalación

Instalación rápida con Cargo

Instala la compilación predeterminada desde Git:

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

Esto instala git-remote-pqcrypt en el directorio binario de Cargo, normalmente ~/.cargo/bin.

Asegúrate de que el directorio binario de Cargo esté en tu PATH, luego verifica que funciona:

git-remote-pqcrypt --help

La compilación predeterminada incluye soporte para sistema de archivos local y almacenamiento basado en Git.

Para instalar con soporte SFTP en sistemas tipo Unix:

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

La característica sftp actualmente no es compatible con Windows.

Compilar desde el código fuente

Compila con soporte de backend predeterminado:

cargo build --release

Esto incluye soporte para sistema de archivos local y almacenamiento basado en Git.

Para compilar con soporte SFTP en sistemas tipo Unix:

cargo build --release --features sftp

Instala el binario en tu PATH:

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

El nombre del binario debe permanecer git-remote-pqcrypt, porque Git encuentra los ayudantes remotos buscando git-remote-[nombre].

Verifica que funciona:

git-remote-pqcrypt --help

Requisitos

• Cadena de herramientas de Rust para compilar desde el código fuente
• git debe estar instalado
• Para almacenamiento basado en Git, se requieren credenciales funcionales de Git y una identidad Git configurada
• Para acceso SSH/SFTP, se debe tener configurada la autenticación SSH existente
• El soporte SFTP requiere compilar con --features sftp y actualmente solo es para sistemas tipo Unix

Inicio rápido

1. Ve a un repositorio Git existente o crea uno.

2. Inicializa el almacenamiento pqcrypt.

Ruta local:

git-remote-pqcrypt init pqcrypt:///ruta/al/almacen-cifrado

SFTP requiere compilar con la característica sftp y actualmente solo es compatible en sistemas tipo Unix:

git-remote-pqcrypt init pqcrypt::sftp://[email protected]/ruta/al/almacen

Basado en Git:

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

Si no existe una clave privada, se genera una en ~/.config/pqcrypt/key y se imprime la clave pública.

Se te solicitará un comentario opcional para la clave, por ejemplo personal o laptop-trabajo.

Después de init, se agrega un remoto Git llamado pqcrypt:

git remote -v

Ejemplo:

pqcrypt  pqcrypt::/ruta/al/almacen-cifrado (fetch)
pqcrypt  pqcrypt::/ruta/al/almacen-cifrado (push)

3. Empuja (push):

git push pqcrypt main

4. Clona o obtén (fetch):

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

5. Agrega otro usuario.

Ellos deben generar un par de claves con:

git-remote-pqcrypt keygen

Pueden obtener su clave pública con:

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

O pueden copiar la clave pública impresa por keygen.

Luego, un usuario autorizado existente los agrega al repositorio:

git-remote-pqcrypt add-user <clave-publica-base64>

Ejecuta esto para más opciones:

git-remote-pqcrypt add-user -h

Por defecto, add-user busca un remoto Git local cuya URL comience con pqcrypt y agrega la clave pública allí.

Comportamiento de push

pqcrypt distingue los pushes normales de los pushes forzados mediante la refspec de Git.

Los pushes normales se verifican con avance rápido (fast-forward) y se rechazan si sobrescribirían el historial remoto.

Comportamiento del ayudante remoto

Git invoca a pqcrypt como un ayudante remoto a través del binario git-remote-pqcrypt.

Cuando Git lo invoca, el ayudante espera la forma de argumento de ayudante remoto utilizada por Git, por ejemplo:

git-remote-pqcrypt origin pqcrypt::/ruta/al/almacen

Los subcomandos directos de CLI como init, add-user, keygen, pubgen y help se tratan como comandos normales de usuario, no como invocaciones de ayudante remoto.

El punto de entrada del binario delega en la biblioteca en tiempo de ejecución, por lo que la lógica de la aplicación se puede probar tanto a través de la biblioteca del crate como a través del binario instalado.

Caché de almacenamiento basado en Git

Para URLs de almacenamiento basado en Git, pqcrypt mantiene una caché local en el directorio de caché del sistema, por ejemplo:

~/.cache/pqcrypt/

pqcrypt obtiene el estado cifrado del repositorio Git de respaldo antes de las operaciones y empuja el estado cifrado después de las actualizaciones.

Si se detecta corrupción o pérdida de la caché, pqcrypt intenta recrear la caché automáticamente volviendo a obtener datos del repositorio Git de respaldo.

Formatos de URL

pqcrypt::, pqcrypt:// y pqcrypt: son aceptados y normalizados internamente a pqcrypt::.

Estos son equivalentes:

git-remote-pqcrypt init pqcrypt:///ruta/al/almacen
git-remote-pqcrypt init pqcrypt::/ruta/al/almacen
git-remote-pqcrypt init pqcrypt:/ruta/al/almacen

El backend se determina por la ruta de almacenamiento:

Ejemplos:

pqcrypt::/tmp/almacen
pqcrypt:///tmp/almacen
pqcrypt:/tmp/almacen
pqcrypt::[email protected]:org/almacen.git
pqcrypt::https://github.com/org/almacen.git
pqcrypt::sftp://[email protected]/ruta/al/almacen

Lógica de descubrimiento de clave privada

Durante el descifrado, pqcrypt busca una clave privada en este orden:

1. Variable de entorno PQCRYPT_KEY_PATH
2. git config pqcrypt.keypath
3. .pqcrypt/key en el directorio actual
4. Cualquier archivo de clave coincidente en ~/.config/pqcrypt, donde se prueban todos

Para configuraciones de múltiples claves, por ejemplo clave de trabajo y personal:

git config pqcrypt.keypath ~/.config/pqcrypt/clave-trabajo

La clave debe ser una que se usó durante init o se agregó mediante add-user.

Desarrollo

Ejecuta la suite de pruebas completa:

cargo test

Ejecuta con SFTP habilitado en sistemas tipo Unix:

cargo test --features sftp

Algunas pruebas de extremo a extremo que dependen del comportamiento de rutas locales tipo Unix se ignoran en Windows.

Compilaciones CI

GitHub Actions compila el proyecto en Linux, macOS y Windows. Los artefactos del flujo de trabajo pueden contener binarios de ejecuciones CI, pero estos no son lanzamientos oficiales.

Información de seguridad

• El contenido del repositorio se cifra usando XChaCha20Poly1305.
• La clave maestra del repositorio se envuelve para los usuarios utilizando HPKE con XWing.
• Cada clave pública autorizada recibe su propia copia cifrada de la clave maestra.
• Los comentarios adjuntos a las claves se autentican como datos asociados de HPKE. Esto significa que si los metadatos del comentario se corrompen, la clave maestra puede no descifrar para ese envoltorio.
• Las referencias de Git y los metadatos del paquete se almacenan dentro del manifiesto cifrado.
• Los archivos de clave privada se crean con permisos 0600 en sistemas tipo Unix.

Limitaciones

• Este proyecto es experimental y no ha recibido una auditoría de seguridad formal.
• Actualmente solo se admiten backends de almacenamiento de sistema de archivos local, basado en Git y SFTP opcional.
• El soporte SFTP está detrás de la característica opcional sftp y actualmente no es compatible con Windows.
• Los backends SFTP/Git carecen de bloqueo distribuido robusto, por lo que los pushes concurrentes podrían provocar pérdida de datos.
• El comportamiento del ayudante remoto de Git sigue siendo relativamente mínimo y puede no admitir todos los flujos de trabajo de Git u operaciones CI/CD.
• Los pushes forzados son compatibles, pero pueden reescribir el historial remoto cifrado al igual que los pushes forzados normales de Git.
• El crate HPKE depende de una fuente Git porque XWing aún no es compatible con las versiones publicadas del crate. Esto cambiará una vez que se actualice HPKE.
• No hay forma de revocar o eliminar el acceso de un usuario. Dado que los usuarios pueden recuperar la clave maestra del historial de Git, la mejor opción es reiniciar el repositorio con una nueva clave maestra y limpiar el remoto.
• El formato de almacenamiento podría cambiar en versiones futuras.
• El almacenamiento basado en Git requiere credenciales de Git funcionales y una identidad Git configurada para los commits.
• Para la autenticación Git, SSH o SFTP, pqcrypt depende de las credenciales SSH/Git existentes.
• ssh y git deben estar instalados.