fscryptography 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- fscryptography-0.1.0/LICENSE +25 -0
- fscryptography-0.1.0/MANIFEST.in +3 -0
- fscryptography-0.1.0/PKG-INFO +168 -0
- fscryptography-0.1.0/README.md +133 -0
- fscryptography-0.1.0/docs/api-reference.md +108 -0
- fscryptography-0.1.0/docs/architecture.md +46 -0
- fscryptography-0.1.0/docs/argon2id-benchmark.md +134 -0
- fscryptography-0.1.0/docs/argon2id-policy.md +109 -0
- fscryptography-0.1.0/docs/atomic-operations.md +72 -0
- fscryptography-0.1.0/docs/backend-validation.md +175 -0
- fscryptography-0.1.0/docs/cryptographic-design.md +39 -0
- fscryptography-0.1.0/docs/decisions/0001-initial-design.md +42 -0
- fscryptography-0.1.0/docs/errors.md +82 -0
- fscryptography-0.1.0/docs/file-format.md +156 -0
- fscryptography-0.1.0/docs/filename-encryption.md +149 -0
- fscryptography-0.1.0/docs/filesystem-hardening.md +86 -0
- fscryptography-0.1.0/docs/index.md +29 -0
- fscryptography-0.1.0/docs/key-management.md +66 -0
- fscryptography-0.1.0/docs/master-key-format-test-plan.md +108 -0
- fscryptography-0.1.0/docs/master-key-format.md +205 -0
- fscryptography-0.1.0/docs/platform-compatibility.md +147 -0
- fscryptography-0.1.0/docs/recovery-journal.md +165 -0
- fscryptography-0.1.0/docs/releasing.md +82 -0
- fscryptography-0.1.0/docs/scope.md +26 -0
- fscryptography-0.1.0/docs/security-model.md +28 -0
- fscryptography-0.1.0/pyproject.toml +65 -0
- fscryptography-0.1.0/setup.cfg +4 -0
- fscryptography-0.1.0/src/fscryptography/__init__.py +41 -0
- fscryptography-0.1.0/src/fscryptography/_directory.py +99 -0
- fscryptography-0.1.0/src/fscryptography/_filesystem.py +671 -0
- fscryptography-0.1.0/src/fscryptography/_journal.py +493 -0
- fscryptography-0.1.0/src/fscryptography/_master_key.py +294 -0
- fscryptography-0.1.0/src/fscryptography/crypto.py +89 -0
- fscryptography-0.1.0/src/fscryptography/errors.py +52 -0
- fscryptography-0.1.0/src/fscryptography/file_format.py +178 -0
- fscryptography-0.1.0/src/fscryptography/names/__init__.py +16 -0
- fscryptography-0.1.0/src/fscryptography/names/codec.py +116 -0
- fscryptography-0.1.0/src/fscryptography/names/tink_backend.py +28 -0
- fscryptography-0.1.0/src/fscryptography/names/validation.py +84 -0
- fscryptography-0.1.0/src/fscryptography/py.typed +0 -0
- fscryptography-0.1.0/src/fscryptography.egg-info/PKG-INFO +168 -0
- fscryptography-0.1.0/src/fscryptography.egg-info/SOURCES.txt +43 -0
- fscryptography-0.1.0/src/fscryptography.egg-info/dependency_links.txt +1 -0
- fscryptography-0.1.0/src/fscryptography.egg-info/requires.txt +11 -0
- fscryptography-0.1.0/src/fscryptography.egg-info/top_level.txt +1 -0
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
Copyright (c) 2026 Specter327. All rights reserved.
|
|
2
|
+
|
|
3
|
+
PROPRIETARY SOFTWARE — ALL RIGHTS RESERVED
|
|
4
|
+
|
|
5
|
+
This software, including its source code, documentation, and associated
|
|
6
|
+
materials (the "Software"), is proprietary and is protected by applicable
|
|
7
|
+
copyright and other intellectual property laws.
|
|
8
|
+
|
|
9
|
+
No license or other permission is granted, expressly or by implication, to
|
|
10
|
+
any person to use, reproduce, modify, adapt, translate, publish, distribute,
|
|
11
|
+
sublicense, sell, rent, publicly display, publicly perform, or create
|
|
12
|
+
derivative works of the Software, in whole or in part.
|
|
13
|
+
|
|
14
|
+
Access to, viewing of, or possession of a copy of the Software does not
|
|
15
|
+
constitute permission to exercise any of the rights listed above. Any use,
|
|
16
|
+
copying, modification, or distribution requires the prior express written
|
|
17
|
+
authorization of the copyright holder, unless such activity is permitted
|
|
18
|
+
under applicable mandatory law.
|
|
19
|
+
|
|
20
|
+
To request a separate license or written authorization, contact the
|
|
21
|
+
copyright holder through the repository's official communication channels.
|
|
22
|
+
|
|
23
|
+
THE SOFTWARE IS PROVIDED "AS IS", TO THE MAXIMUM EXTENT PERMITTED BY
|
|
24
|
+
APPLICABLE LAW. THE COPYRIGHT HOLDER DISCLAIMS ALL WARRANTIES AND
|
|
25
|
+
LIABILITY TO THE EXTENT PERMITTED BY LAW.
|
|
@@ -0,0 +1,168 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: fscryptography
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Filesystem-oriented authenticated encryption for files and names
|
|
5
|
+
License-Expression: LicenseRef-Proprietary
|
|
6
|
+
Project-URL: Homepage, https://github.com/specter327/fscryptography
|
|
7
|
+
Project-URL: Repository, https://github.com/specter327/fscryptography
|
|
8
|
+
Project-URL: Documentation, https://github.com/specter327/fscryptography/tree/main/docs
|
|
9
|
+
Project-URL: Issues, https://github.com/specter327/fscryptography/issues
|
|
10
|
+
Project-URL: Changelog, https://github.com/specter327/fscryptography/releases
|
|
11
|
+
Keywords: cryptography,filesystem,file-encryption,authenticated-encryption,tink,argon2id
|
|
12
|
+
Classifier: Development Status :: 3 - Alpha
|
|
13
|
+
Classifier: Intended Audience :: Developers
|
|
14
|
+
Classifier: Topic :: Security :: Cryptography
|
|
15
|
+
Classifier: Operating System :: POSIX :: Linux
|
|
16
|
+
Classifier: Operating System :: Microsoft :: Windows
|
|
17
|
+
Classifier: Programming Language :: Python :: 3
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
21
|
+
Classifier: Typing :: Typed
|
|
22
|
+
Requires-Python: >=3.11
|
|
23
|
+
Description-Content-Type: text/markdown
|
|
24
|
+
License-File: LICENSE
|
|
25
|
+
Requires-Dist: tink<2,>=1.16.1
|
|
26
|
+
Requires-Dist: argon2-cffi<26,>=23.1
|
|
27
|
+
Requires-Dist: cryptography<47,>=42
|
|
28
|
+
Provides-Extra: test
|
|
29
|
+
Requires-Dist: pytest<9,>=8; extra == "test"
|
|
30
|
+
Provides-Extra: dev
|
|
31
|
+
Requires-Dist: build<2,>=1.2; extra == "dev"
|
|
32
|
+
Requires-Dist: pytest<9,>=8; extra == "dev"
|
|
33
|
+
Requires-Dist: twine<7,>=5; extra == "dev"
|
|
34
|
+
Dynamic: license-file
|
|
35
|
+
|
|
36
|
+
# fscryptography
|
|
37
|
+
|
|
38
|
+
**fscryptography** (*filesystem-cryptography*) es una librería Python para cifrar y descifrar archivos y nombres de archivos y directorios directamente sobre rutas del sistema de archivos.
|
|
39
|
+
|
|
40
|
+
Proporciona una API de alto nivel basada en rutas, cifrado autenticado y procesamiento segmentado para archivos grandes. No depende de herramientas de exploración de recursos ni de aplicaciones concretas.
|
|
41
|
+
|
|
42
|
+
## Instalación
|
|
43
|
+
|
|
44
|
+
Requiere Python 3.11 o posterior.
|
|
45
|
+
|
|
46
|
+
```bash
|
|
47
|
+
python -m pip install fscryptography
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
## Inicio rápido
|
|
51
|
+
|
|
52
|
+
```python
|
|
53
|
+
from pathlib import Path
|
|
54
|
+
|
|
55
|
+
import fscryptography
|
|
56
|
+
|
|
57
|
+
# Genera una clave maestra aleatoria codificada en Base64.
|
|
58
|
+
master_key = fscryptography.generate()
|
|
59
|
+
|
|
60
|
+
# Guarda la clave de forma segura fuera del directorio que se cifra.
|
|
61
|
+
# Quien obtenga la clave podrá descifrar los recursos protegidos.
|
|
62
|
+
|
|
63
|
+
with fscryptography.Manager(key=master_key) as manager:
|
|
64
|
+
manager.file.encrypt(Path("document.txt"))
|
|
65
|
+
manager.file.decrypt(Path("document.fscrypt"))
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
Para proteger el contenedor de clave maestra con contraseña:
|
|
69
|
+
|
|
70
|
+
```python
|
|
71
|
+
master_key = fscryptography.generate(password="correct horse battery staple")
|
|
72
|
+
|
|
73
|
+
with fscryptography.Manager(
|
|
74
|
+
key=master_key,
|
|
75
|
+
password="correct horse battery staple",
|
|
76
|
+
) as manager:
|
|
77
|
+
manager.file.encrypt("confidential.pdf", encrypt_name=True)
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
La contraseña se consume al abrir el contenedor y no se conserva en el gestor. No debe confundirse la contraseña con una copia de seguridad de la clave: conserva la cadena Base64 de la MasterKey en un lugar seguro.
|
|
81
|
+
|
|
82
|
+
## API principal
|
|
83
|
+
|
|
84
|
+
```python
|
|
85
|
+
import fscryptography
|
|
86
|
+
|
|
87
|
+
master_key = fscryptography.generate()
|
|
88
|
+
# O bien: fscryptography.generate(password="...")
|
|
89
|
+
|
|
90
|
+
manager = fscryptography.Manager(key=master_key)
|
|
91
|
+
# Para una MasterKey protegida: Manager(key=master_key, password="...")
|
|
92
|
+
|
|
93
|
+
manager.file.encrypt("report.txt")
|
|
94
|
+
manager.file.encrypt("archive.tar.gz", new_extension=".locked")
|
|
95
|
+
manager.file.encrypt("private.txt", encrypt_name=True)
|
|
96
|
+
manager.file.decrypt("report.fscrypt")
|
|
97
|
+
|
|
98
|
+
manager.dir.encrypt("private-directory")
|
|
99
|
+
manager.dir.decrypt("~1...")
|
|
100
|
+
|
|
101
|
+
records = manager.inspect_recovery("/path/to/parent") # Inspección de solo lectura
|
|
102
|
+
exported_key = manager.export_key()
|
|
103
|
+
manager.close()
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
Las operaciones de directorio transforman exclusivamente el nombre del directorio: **no recorren ni cifran su contenido**. La librería no ofrece una API pública de cifrado genérico de bytes o streams.
|
|
107
|
+
|
|
108
|
+
## Diseño criptográfico
|
|
109
|
+
|
|
110
|
+
- Google Tink para Streaming AEAD de contenido (`AES256_GCM_HKDF_1MB`) y AEAD de nombres (`AES256_GCM`).
|
|
111
|
+
- Argon2id y AES-256-GCM para proteger una MasterKey cuando se especifica contraseña.
|
|
112
|
+
- Keysets independientes para contenido y nombres.
|
|
113
|
+
- Formatos versionados y metadata de archivo autenticada.
|
|
114
|
+
- Operaciones de filesystem diseñadas para evitar sobrescrituras accidentales y preservar información de transacciones interrumpidas.
|
|
115
|
+
|
|
116
|
+
## Compatibilidad y límites
|
|
117
|
+
|
|
118
|
+
- Python 3.11+.
|
|
119
|
+
- GNU/Linux y Windows.
|
|
120
|
+
- En GNU/Linux se utilizan operaciones relativas a descriptores de directorio y publicación no-replace cuando el sistema las soporta.
|
|
121
|
+
- En Windows existen diferencias documentadas: no se ofrece el mismo anclaje de directorio ni la misma garantía de cuarentena del origen.
|
|
122
|
+
- No se garantiza protección frente a procesos hostiles que operen bajo el mismo UID/usuario.
|
|
123
|
+
- Las semánticas de durabilidad y renombrado de sistemas de archivos alternativos o de red no están validadas exhaustivamente.
|
|
124
|
+
|
|
125
|
+
La inspección del journal es explícita y de solo lectura. No hay recuperación destructiva ni limpieza automática de transacciones completadas.
|
|
126
|
+
|
|
127
|
+
## Seguridad
|
|
128
|
+
|
|
129
|
+
Esta librería manipula claves criptográficas y archivos del usuario. Revisa el [modelo de seguridad](docs/security-model.md), la [política de gestión de claves](docs/key-management.md), la [compatibilidad de plataformas](docs/platform-compatibility.md) y la [documentación técnica](docs/index.md) antes de integrarla en un flujo sensible.
|
|
130
|
+
|
|
131
|
+
La protección criptográfica no sustituye las copias de seguridad, el control de acceso del sistema operativo ni una política de gestión y rotación de claves. La implementación y sus pruebas automatizadas no equivalen a una auditoría criptográfica independiente.
|
|
132
|
+
|
|
133
|
+
## Licencia y derechos de uso
|
|
134
|
+
|
|
135
|
+
Este proyecto es software propietario y se distribuye bajo una política de **todos los derechos reservados**. No se concede una licencia pública para usar, copiar, modificar o redistribuir el software. Cualquier autorización requiere permiso previo y expreso por escrito del titular de los derechos.
|
|
136
|
+
|
|
137
|
+
Consulta el archivo [LICENSE](LICENSE). La disponibilidad del código fuente en GitHub o de un paquete en PyPI no implica la concesión de derechos adicionales.
|
|
138
|
+
|
|
139
|
+
## Desarrollo
|
|
140
|
+
|
|
141
|
+
Instala las dependencias de desarrollo:
|
|
142
|
+
|
|
143
|
+
```bash
|
|
144
|
+
python -m pip install -e ".[dev]"
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
Ejecuta las pruebas:
|
|
148
|
+
|
|
149
|
+
```bash
|
|
150
|
+
python -m pytest
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
Construye y valida los artefactos de distribución:
|
|
154
|
+
|
|
155
|
+
```bash
|
|
156
|
+
python -m build
|
|
157
|
+
python -m twine check dist/*
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
El proyecto utiliza un diseño `src/` y publica un wheel y un source distribution (sdist). La publicación a PyPI se automatiza mediante GitHub Actions y Trusted Publishing (OIDC); no requiere almacenar un token PyPI de larga duración en los secretos del repositorio.
|
|
161
|
+
|
|
162
|
+
## Estado
|
|
163
|
+
|
|
164
|
+
Versión inicial de distribución: **0.1.0**. El proyecto continúa en fase alpha. Consulta [GitHub Releases](https://github.com/specter327/fscryptography/releases) para conocer las versiones publicadas y sus notas.
|
|
165
|
+
|
|
166
|
+
## Documentación
|
|
167
|
+
|
|
168
|
+
La documentación normativa y técnica está en [docs/](docs/index.md). El [contrato de API](docs/api-reference.md) describe las operaciones, retornos y excepciones.
|
|
@@ -0,0 +1,133 @@
|
|
|
1
|
+
# fscryptography
|
|
2
|
+
|
|
3
|
+
**fscryptography** (*filesystem-cryptography*) es una librería Python para cifrar y descifrar archivos y nombres de archivos y directorios directamente sobre rutas del sistema de archivos.
|
|
4
|
+
|
|
5
|
+
Proporciona una API de alto nivel basada en rutas, cifrado autenticado y procesamiento segmentado para archivos grandes. No depende de herramientas de exploración de recursos ni de aplicaciones concretas.
|
|
6
|
+
|
|
7
|
+
## Instalación
|
|
8
|
+
|
|
9
|
+
Requiere Python 3.11 o posterior.
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
python -m pip install fscryptography
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
## Inicio rápido
|
|
16
|
+
|
|
17
|
+
```python
|
|
18
|
+
from pathlib import Path
|
|
19
|
+
|
|
20
|
+
import fscryptography
|
|
21
|
+
|
|
22
|
+
# Genera una clave maestra aleatoria codificada en Base64.
|
|
23
|
+
master_key = fscryptography.generate()
|
|
24
|
+
|
|
25
|
+
# Guarda la clave de forma segura fuera del directorio que se cifra.
|
|
26
|
+
# Quien obtenga la clave podrá descifrar los recursos protegidos.
|
|
27
|
+
|
|
28
|
+
with fscryptography.Manager(key=master_key) as manager:
|
|
29
|
+
manager.file.encrypt(Path("document.txt"))
|
|
30
|
+
manager.file.decrypt(Path("document.fscrypt"))
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
Para proteger el contenedor de clave maestra con contraseña:
|
|
34
|
+
|
|
35
|
+
```python
|
|
36
|
+
master_key = fscryptography.generate(password="correct horse battery staple")
|
|
37
|
+
|
|
38
|
+
with fscryptography.Manager(
|
|
39
|
+
key=master_key,
|
|
40
|
+
password="correct horse battery staple",
|
|
41
|
+
) as manager:
|
|
42
|
+
manager.file.encrypt("confidential.pdf", encrypt_name=True)
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
La contraseña se consume al abrir el contenedor y no se conserva en el gestor. No debe confundirse la contraseña con una copia de seguridad de la clave: conserva la cadena Base64 de la MasterKey en un lugar seguro.
|
|
46
|
+
|
|
47
|
+
## API principal
|
|
48
|
+
|
|
49
|
+
```python
|
|
50
|
+
import fscryptography
|
|
51
|
+
|
|
52
|
+
master_key = fscryptography.generate()
|
|
53
|
+
# O bien: fscryptography.generate(password="...")
|
|
54
|
+
|
|
55
|
+
manager = fscryptography.Manager(key=master_key)
|
|
56
|
+
# Para una MasterKey protegida: Manager(key=master_key, password="...")
|
|
57
|
+
|
|
58
|
+
manager.file.encrypt("report.txt")
|
|
59
|
+
manager.file.encrypt("archive.tar.gz", new_extension=".locked")
|
|
60
|
+
manager.file.encrypt("private.txt", encrypt_name=True)
|
|
61
|
+
manager.file.decrypt("report.fscrypt")
|
|
62
|
+
|
|
63
|
+
manager.dir.encrypt("private-directory")
|
|
64
|
+
manager.dir.decrypt("~1...")
|
|
65
|
+
|
|
66
|
+
records = manager.inspect_recovery("/path/to/parent") # Inspección de solo lectura
|
|
67
|
+
exported_key = manager.export_key()
|
|
68
|
+
manager.close()
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
Las operaciones de directorio transforman exclusivamente el nombre del directorio: **no recorren ni cifran su contenido**. La librería no ofrece una API pública de cifrado genérico de bytes o streams.
|
|
72
|
+
|
|
73
|
+
## Diseño criptográfico
|
|
74
|
+
|
|
75
|
+
- Google Tink para Streaming AEAD de contenido (`AES256_GCM_HKDF_1MB`) y AEAD de nombres (`AES256_GCM`).
|
|
76
|
+
- Argon2id y AES-256-GCM para proteger una MasterKey cuando se especifica contraseña.
|
|
77
|
+
- Keysets independientes para contenido y nombres.
|
|
78
|
+
- Formatos versionados y metadata de archivo autenticada.
|
|
79
|
+
- Operaciones de filesystem diseñadas para evitar sobrescrituras accidentales y preservar información de transacciones interrumpidas.
|
|
80
|
+
|
|
81
|
+
## Compatibilidad y límites
|
|
82
|
+
|
|
83
|
+
- Python 3.11+.
|
|
84
|
+
- GNU/Linux y Windows.
|
|
85
|
+
- En GNU/Linux se utilizan operaciones relativas a descriptores de directorio y publicación no-replace cuando el sistema las soporta.
|
|
86
|
+
- En Windows existen diferencias documentadas: no se ofrece el mismo anclaje de directorio ni la misma garantía de cuarentena del origen.
|
|
87
|
+
- No se garantiza protección frente a procesos hostiles que operen bajo el mismo UID/usuario.
|
|
88
|
+
- Las semánticas de durabilidad y renombrado de sistemas de archivos alternativos o de red no están validadas exhaustivamente.
|
|
89
|
+
|
|
90
|
+
La inspección del journal es explícita y de solo lectura. No hay recuperación destructiva ni limpieza automática de transacciones completadas.
|
|
91
|
+
|
|
92
|
+
## Seguridad
|
|
93
|
+
|
|
94
|
+
Esta librería manipula claves criptográficas y archivos del usuario. Revisa el [modelo de seguridad](docs/security-model.md), la [política de gestión de claves](docs/key-management.md), la [compatibilidad de plataformas](docs/platform-compatibility.md) y la [documentación técnica](docs/index.md) antes de integrarla en un flujo sensible.
|
|
95
|
+
|
|
96
|
+
La protección criptográfica no sustituye las copias de seguridad, el control de acceso del sistema operativo ni una política de gestión y rotación de claves. La implementación y sus pruebas automatizadas no equivalen a una auditoría criptográfica independiente.
|
|
97
|
+
|
|
98
|
+
## Licencia y derechos de uso
|
|
99
|
+
|
|
100
|
+
Este proyecto es software propietario y se distribuye bajo una política de **todos los derechos reservados**. No se concede una licencia pública para usar, copiar, modificar o redistribuir el software. Cualquier autorización requiere permiso previo y expreso por escrito del titular de los derechos.
|
|
101
|
+
|
|
102
|
+
Consulta el archivo [LICENSE](LICENSE). La disponibilidad del código fuente en GitHub o de un paquete en PyPI no implica la concesión de derechos adicionales.
|
|
103
|
+
|
|
104
|
+
## Desarrollo
|
|
105
|
+
|
|
106
|
+
Instala las dependencias de desarrollo:
|
|
107
|
+
|
|
108
|
+
```bash
|
|
109
|
+
python -m pip install -e ".[dev]"
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
Ejecuta las pruebas:
|
|
113
|
+
|
|
114
|
+
```bash
|
|
115
|
+
python -m pytest
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
Construye y valida los artefactos de distribución:
|
|
119
|
+
|
|
120
|
+
```bash
|
|
121
|
+
python -m build
|
|
122
|
+
python -m twine check dist/*
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
El proyecto utiliza un diseño `src/` y publica un wheel y un source distribution (sdist). La publicación a PyPI se automatiza mediante GitHub Actions y Trusted Publishing (OIDC); no requiere almacenar un token PyPI de larga duración en los secretos del repositorio.
|
|
126
|
+
|
|
127
|
+
## Estado
|
|
128
|
+
|
|
129
|
+
Versión inicial de distribución: **0.1.0**. El proyecto continúa en fase alpha. Consulta [GitHub Releases](https://github.com/specter327/fscryptography/releases) para conocer las versiones publicadas y sus notas.
|
|
130
|
+
|
|
131
|
+
## Documentación
|
|
132
|
+
|
|
133
|
+
La documentación normativa y técnica está en [docs/](docs/index.md). El [contrato de API](docs/api-reference.md) describe las operaciones, retornos y excepciones.
|
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
# API pública
|
|
2
|
+
|
|
3
|
+
## Principios
|
|
4
|
+
|
|
5
|
+
La API opera sobre rutas del filesystem. No expone cifrado general de bytes ni streams suministrados por el consumidor. La clave maestra se representa públicamente como texto Base64 estándar y se decodifica a bytes al entrar en la librería.
|
|
6
|
+
|
|
7
|
+
## Generación de clave maestra
|
|
8
|
+
|
|
9
|
+
import fscryptography
|
|
10
|
+
|
|
11
|
+
# Generación aleatoria
|
|
12
|
+
master_key = fscryptography.generate()
|
|
13
|
+
|
|
14
|
+
# Generación de keysets protegidos por contraseña
|
|
15
|
+
master_key = fscryptography.generate(password="passphrase")
|
|
16
|
+
|
|
17
|
+
Ambas variantes devuelven una cadena Base64 canónica. La cadena representa el contenedor autocontenido MasterKey; no representa una clave AES plana. La variante con contraseña protege el contenedor mediante Argon2id y AES-256-GCM.
|
|
18
|
+
|
|
19
|
+
## Gestor y contexto criptográfico
|
|
20
|
+
|
|
21
|
+
manager = fscryptography.Manager(key=master_key)
|
|
22
|
+
|
|
23
|
+
# Para un contenedor protegido:
|
|
24
|
+
manager = fscryptography.Manager(
|
|
25
|
+
key=master_key,
|
|
26
|
+
password="passphrase",
|
|
27
|
+
)
|
|
28
|
+
|
|
29
|
+
with fscryptography.Manager(key=master_key) as manager:
|
|
30
|
+
...
|
|
31
|
+
|
|
32
|
+
El gestor decodifica Base64 a bytes, valida y abre el contenedor una sola vez, y conserva en su contexto las primitivas Tink independientes para contenido y nombres. Las operaciones posteriores reutilizan ese contexto; no reciben la clave en cada llamada.
|
|
33
|
+
|
|
34
|
+
Si el contenedor fue generado con password=..., la contraseña debe suministrarse al construir el gestor. La contraseña se consume durante la apertura y no se conserva en el objeto. Esto es obligatorio para mantener el contrato MasterKey protegido ya aprobado; no es posible abrirlo únicamente con la cadena Base64.
|
|
35
|
+
|
|
36
|
+
## Cambio y exportación de clave
|
|
37
|
+
|
|
38
|
+
manager.change_key(new_key)
|
|
39
|
+
|
|
40
|
+
# Para una nueva clave protegida:
|
|
41
|
+
manager.change_key(new_key, password="new passphrase")
|
|
42
|
+
|
|
43
|
+
exported_key: str = manager.export_key()
|
|
44
|
+
|
|
45
|
+
change_key() valida y abre completamente la nueva clave antes de sustituir el contexto activo. Si falla, el contexto anterior permanece intacto. export_key() devuelve la representación Base64 canónica de la clave activa.
|
|
46
|
+
|
|
47
|
+
## Operaciones sobre recursos
|
|
48
|
+
|
|
49
|
+
# Nombre visible: salida document.fscrypt
|
|
50
|
+
manager.file.encrypt(path="document.txt")
|
|
51
|
+
|
|
52
|
+
# Extensión de salida personalizada o sin extensión
|
|
53
|
+
manager.file.encrypt(path="archive.tar.gz", new_extension=".locked")
|
|
54
|
+
manager.file.encrypt(path="secret.txt", new_extension="")
|
|
55
|
+
|
|
56
|
+
# El nombre completo se cifra con el keyset AEAD de nombres
|
|
57
|
+
manager.file.encrypt(path="private.txt", encrypt_name=True)
|
|
58
|
+
|
|
59
|
+
manager.file.decrypt(path="document.fscrypt")
|
|
60
|
+
|
|
61
|
+
# Los directorios solo transforman su propio nombre
|
|
62
|
+
manager.dir.encrypt(path="private-directory")
|
|
63
|
+
manager.dir.decrypt(path="~1...")
|
|
64
|
+
|
|
65
|
+
Las operaciones son métodos del contexto del gestor y reutilizan las primitivas abiertas. El cifrado de archivos utiliza Tink Streaming AEAD y la cabecera v1.0 autenticada como AAD. La extensión original y la de salida se guardan en metadata autenticada. `new_extension=None` selecciona `.fscrypt`; `""` elimina la extensión visible; un sufijo explícito como `.locked` la sustituye. Con `encrypt_name=True`, se cifra el nombre completo y `new_extension` debe ser `None`. Los directorios transforman exclusivamente su propio nombre; no recorren ni cifran su contenido.
|
|
66
|
+
|
|
67
|
+
## Representación de claves
|
|
68
|
+
|
|
69
|
+
- Frontera pública: Base64 estándar ASCII (str).
|
|
70
|
+
- Interior de la librería: contenedor binario (bytes) y primitivas criptográficas abiertas.
|
|
71
|
+
- Exportación: serialización de los bytes internos a Base64 estándar.
|
|
72
|
+
- La codificación Base64 no es cifrado ni protección de secretos.
|
|
73
|
+
|
|
74
|
+
El gestor no conserva la contraseña. close() invalida el contexto y libera referencias a la clave y las primitivas; el borrado seguro de memoria no está garantizado por Python.
|
|
75
|
+
|
|
76
|
+
## Retornos y errores
|
|
77
|
+
|
|
78
|
+
Las operaciones file.encrypt(), file.decrypt(), dir.encrypt() y dir.decrypt() devolverán None al completarse correctamente. Los fallos se comunicarán mediante excepciones tipadas; no se devolverá False como sustituto de una excepción.
|
|
79
|
+
|
|
80
|
+
Todas las excepciones propias derivan de FsCryptographyError. La jerarquía, la clasificación de fallos y la política de preservación de excepciones estándar se definen en [Errores y excepciones](errors.md).
|
|
81
|
+
|
|
82
|
+
Los errores de argumentos conservan TypeError o ValueError; los errores ordinarios del filesystem conservan las excepciones estándar de Python cuando sea posible. La contraseña incorrecta y la alteración de un contenedor protegido se presentan como AuthenticationError, sin distinguir públicamente ambos casos.
|
|
83
|
+
|
|
84
|
+
## Inspección de operaciones interrumpidas
|
|
85
|
+
|
|
86
|
+
records = manager.inspect_recovery("/path/to/parent")
|
|
87
|
+
|
|
88
|
+
La llamada inspecciona exclusivamente los directorios `.fscryptography-txn-*` situados directamente bajo el directorio indicado. Devuelve una tupla inmutable de objetos `fscryptography.RecoveryRecord`. Las clasificaciones incluyen `prepared_no_output`, `result_incomplete_or_unverified`, `result_ready`, `published_source_present`, `published_source_missing`, `source_removed`, `ambiguous` y `corrupt`.
|
|
89
|
+
|
|
90
|
+
La inspección es de solo lectura y no requiere una clave abierta: no descifra ni autentica contenido. Los registros completados se conservan como evidencia; no hay limpieza automática ni resolución destructiva. Una clasificación nunca autoriza por sí sola a borrar, restaurar o reemplazar recursos.
|
|
91
|
+
|
|
92
|
+
## Estado de implementación
|
|
93
|
+
|
|
94
|
+
Implementado:
|
|
95
|
+
- fscryptography.generate(password=None).
|
|
96
|
+
- fscryptography.Manager(key, password=None).
|
|
97
|
+
- Decodificación Base64 a bytes para el contexto interno.
|
|
98
|
+
- Reutilización de primitivas abiertas por el gestor.
|
|
99
|
+
- Manager.change_key() con sustitución atómica del contexto.
|
|
100
|
+
- Manager.export_key() a Base64.
|
|
101
|
+
- close() y administrador de contexto.
|
|
102
|
+
|
|
103
|
+
Pendiente:
|
|
104
|
+
- Pruebas de interrupción inyectada en cada barrera de persistencia, fallos de filesystem y carreras hostiles.
|
|
105
|
+
- Política segura de retención/limpieza de journals completados.
|
|
106
|
+
- API separada de resolución explícita; no forma parte de esta versión.
|
|
107
|
+
- Pruebas de conformidad ampliadas, vectores golden y validación de mutaciones.
|
|
108
|
+
- Validación de atomicidad/no-sobrescritura y round-trip en Windows/NTFS y GNU/Linux/ext4 reales.
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
# Arquitectura
|
|
2
|
+
|
|
3
|
+
## Principios
|
|
4
|
+
|
|
5
|
+
La API pública, las operaciones de filesystem, el formato y el backend criptográfico mantienen responsabilidades separadas. La arquitectura interna no debe filtrar objetos específicos del backend a la API pública.
|
|
6
|
+
|
|
7
|
+
## Componentes lógicos
|
|
8
|
+
|
|
9
|
+
- Manager: inicialización, ciclo de vida, almacenamiento binario de la clave y contexto reutilizable de operaciones.
|
|
10
|
+
- File operations: cifrado y descifrado del contenido.
|
|
11
|
+
- Directory operations: transformación del nombre de directorio.
|
|
12
|
+
- Name codec: codificación y validación de nombres cifrados.
|
|
13
|
+
- Key management: generación, derivación, parsing y separación de claves.
|
|
14
|
+
- Format: cabeceras, metadatos y versionado.
|
|
15
|
+
- Filesystem operations: rutas, temporales, publicación no-replace, sincronización y manejo de fallos.
|
|
16
|
+
- Cryptographic backend: integración interna de Tink, Argon2id y AES-GCM de envoltura.
|
|
17
|
+
- Transaction journal (diseño): registro persistente de operaciones interrumpidas e inspección explícita de sus identidades.
|
|
18
|
+
|
|
19
|
+
Esta división define responsabilidades, no obliga a crear un archivo por componente.
|
|
20
|
+
|
|
21
|
+
## Dependencias
|
|
22
|
+
|
|
23
|
+
La biblioteca estándar proporciona I/O, rutas y operaciones de sistema. Google Tink proporciona las primitivas AEAD y Streaming AEAD. Argon2id se integra mediante argon2-cffi y AES-GCM de envoltura mediante cryptography.
|
|
24
|
+
|
|
25
|
+
La primera versión utiliza un único backend criptográfico; no se diseña una arquitectura de backends intercambiables.
|
|
26
|
+
|
|
27
|
+
## Estado de componentes
|
|
28
|
+
|
|
29
|
+
- **Implementado:** validación y codec de nombres Tink; generación/apertura de MasterKey; recuperación de keysets; API `generate()`/`Manager`; cambio y exportación de clave; formato binario de archivo v1.0; cifrado/descifrado de archivos con Tink Streaming AEAD; cifrado/descifrado de nombres de archivos y directorios; temporales privados; publicación no-replace; sincronización del archivo temporal y del directorio padre en GNU/Linux.
|
|
30
|
+
- **Diseño especificado, implementación pendiente:** protocolo de journal por transacción, formato estricto, estados persistentes, validación de identidades y recuperación inicial de solo lectura.
|
|
31
|
+
- **Pendiente de validación de plataforma:** comportamiento real en NTFS y ext4, límites Unicode exactos en Windows, colisiones bajo configuraciones case-sensitive y garantías de durabilidad.
|
|
32
|
+
- **Pendiente de robustecimiento:** integración del journal en operaciones, API tipada de inspección, resolución explícita de transacciones, flush de directorio en Windows, pruebas de concurrencia/cambios hostiles y preservación de metadatos de filesystem.
|
|
33
|
+
|
|
34
|
+
## Flujo de cifrado implementado
|
|
35
|
+
|
|
36
|
+
Validar origen y destino; crear temporal exclusivo en el mismo directorio; escribir la cabecera y cifrar secuencialmente; finalizar el flujo autenticado; sincronizar el archivo temporal; publicar sin reemplazar destinos existentes; sincronizar el directorio padre en GNU/Linux; revalidar y retirar el origen; volver a sincronizar el directorio padre en GNU/Linux. Si falla la primera sincronización del directorio, se conservan origen y destino.
|
|
37
|
+
|
|
38
|
+
## Flujo de descifrado implementado
|
|
39
|
+
|
|
40
|
+
Reconocer y validar la cabecera; preparar temporal privado; descifrar y autenticar todos los segmentos; validar el cierre; sincronizar el archivo temporal; validar el nombre original; publicar únicamente tras autenticación completa; sincronizar el directorio padre en GNU/Linux; retirar el ciphertext y sincronizar nuevamente el directorio padre.
|
|
41
|
+
|
|
42
|
+
## Recuperación y límites
|
|
43
|
+
|
|
44
|
+
No existe todavía journal persistente ni recuperación automática de operaciones interrumpidas abruptamente. Los temporales huérfanos no se eliminan automáticamente. Si la publicación se completó pero el origen no pudo retirarse, ambos recursos se conservan y se informa `AtomicOperationError`.
|
|
45
|
+
|
|
46
|
+
El protocolo propuesto está en `docs/recovery-journal.md`. La primera implementación será de inspección explícita y no mutará el filesystem. No implementar primitivas propias. No publicar plaintext parcial. No sobrescribir destinos por defecto. No asumir que múltiples renames forman una transacción. No prometer borrado seguro absoluto de secretos en memoria Python.
|
|
@@ -0,0 +1,134 @@
|
|
|
1
|
+
# Benchmark reproducible de Argon2id
|
|
2
|
+
|
|
3
|
+
## Estado
|
|
4
|
+
|
|
5
|
+
Herramienta de medición disponible para desarrollo. **El perfil 64 MiB / 3 / p=1 está aprobado como perfil de producción v1** con base en los resultados del equipo de referencia registrados en este documento. Por decisión del proyecto no se realizó validación en otros equipos; la aprobación no certifica todas las plataformas. Este benchmark no implementa ni modifica la apertura de `MasterKey`.
|
|
6
|
+
|
|
7
|
+
## Artefacto
|
|
8
|
+
|
|
9
|
+
El ejecutable `tests/backend_validation/benchmark_argon2id.py` mide la derivación Argon2id usando `argon2-cffi` y los parámetros seleccionados para la propuesta:
|
|
10
|
+
|
|
11
|
+
- Argon2id, versión 19 (`0x13`).
|
|
12
|
+
- Memoria: 65.536 KiB.
|
|
13
|
+
- Iteraciones: 3.
|
|
14
|
+
- Paralelismo: 1.
|
|
15
|
+
- Salida: 32 bytes.
|
|
16
|
+
|
|
17
|
+
No requiere dependencias adicionales a `argon2-cffi` y la biblioteca estándar de Python. No se ejecuta automáticamente en CI: sus tiempos dependen del hardware y no constituyen una prueba estable de regresión.
|
|
18
|
+
|
|
19
|
+
## Ejecución de referencia
|
|
20
|
+
|
|
21
|
+
Desde la raíz del repositorio, con `argon2-cffi` instalado:
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
python tests/backend_validation/benchmark_argon2id.py
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
Por defecto realiza dos derivaciones de calentamiento y siete lotes medidos para cada nivel de concurrencia (1 y 2). El nivel máximo está limitado por un presupuesto estimado predeterminado de 256 MiB de memoria Argon2. La herramienta aborta antes de ejecutar la KDF si la memoria configurada multiplicada por la concurrencia excede ese presupuesto.
|
|
28
|
+
|
|
29
|
+
Para guardar el informe:
|
|
30
|
+
|
|
31
|
+
```bash
|
|
32
|
+
python tests/backend_validation/benchmark_argon2id.py --json argon2id-benchmark.json
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
Los parámetros de ejecución se pueden ajustar explícitamente:
|
|
36
|
+
|
|
37
|
+
```bash
|
|
38
|
+
python tests/backend_validation/benchmark_argon2id.py \
|
|
39
|
+
--iterations 10 \
|
|
40
|
+
--warmup 3 \
|
|
41
|
+
--concurrency 1 2 \
|
|
42
|
+
--max-memory-mib 256
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
El presupuesto es una salvaguarda de memoria de trabajo Argon2 estimada, no una detección de RAM disponible ni una garantía contra OOM. Antes de elevarlo, comprobar memoria libre y cerrar cargas innecesarias.
|
|
46
|
+
|
|
47
|
+
## Resultados de referencia aprobados
|
|
48
|
+
|
|
49
|
+
### Entorno
|
|
50
|
+
|
|
51
|
+
- Sistema: Linux x86_64, kernel `6.17.0-35-generic`, glibc 2.39.
|
|
52
|
+
- Python: CPython 3.12.3.
|
|
53
|
+
- `argon2-cffi`: 25.1.0.
|
|
54
|
+
- CPU lógica: 4.
|
|
55
|
+
- Perfil: Argon2id v19, 65.536 KiB, 3 iteraciones, paralelismo 1, salida de 32 bytes.
|
|
56
|
+
- Presupuesto configurado en el benchmark: 256 MiB de memoria Argon2 estimada.
|
|
57
|
+
|
|
58
|
+
### Latencia (30 lotes por nivel; 5 warmups)
|
|
59
|
+
|
|
60
|
+
| Métrica | Concurrencia 1 | Concurrencia 2 |
|
|
61
|
+
|---|---:|---:|
|
|
62
|
+
| Mediana por derivación | 480,58 ms | 551,85 ms |
|
|
63
|
+
| P95 por derivación | 581,59 ms | 760,73 ms |
|
|
64
|
+
| Máximo por derivación | 584,78 ms | 1.085,04 ms |
|
|
65
|
+
| Mediana de tiempo de lote | 481,14 ms | 559,55 ms |
|
|
66
|
+
| P95 de tiempo de lote | 582,27 ms | 1.040,04 ms |
|
|
67
|
+
|
|
68
|
+
### Memoria residente máxima (medición separada con GNU time)
|
|
69
|
+
|
|
70
|
+
Se ejecutó el benchmark en procesos independientes con `/usr/bin/time -v`, 30 lotes y 5 warmups para cada nivel:
|
|
71
|
+
|
|
72
|
+
| Métrica | Concurrencia 1 | Concurrencia 2 |
|
|
73
|
+
|---|---:|---:|
|
|
74
|
+
| RSS máximo | 85.712 KiB (83,70 MiB) | 151.180 KiB (147,64 MiB) |
|
|
75
|
+
| Presupuesto | 256 MiB | 256 MiB |
|
|
76
|
+
| Margen respecto al presupuesto | 172,30 MiB | 108,36 MiB |
|
|
77
|
+
| Swap reportado | 0 | 0 |
|
|
78
|
+
| Exit status | 0 | 0 |
|
|
79
|
+
|
|
80
|
+
La RSS incluye Python, bibliotecas y memoria auxiliar; no es una medición aislada del área de trabajo de Argon2. Los valores son high-water marks del proceso informados por GNU time. Las mediciones de latencia de estos procesos separados fueron: concurrencia 1, mediana 521,30 ms, P95 658,61 ms y máximo 673,08 ms; concurrencia 2, mediana 560,83 ms, P95 639,99 ms y máximo 955,94 ms. Las variaciones entre ejecuciones son esperables y no deben mezclarse como si fueran una única muestra.
|
|
81
|
+
|
|
82
|
+
**Decisión:** el perfil 64 MiB / 3 / p=1 se aprueba para MasterKey v1. En el equipo medido, dos derivaciones simultáneas alcanzaron 147,64 MiB de RSS máximo, dentro del presupuesto de referencia de 256 MiB. La librería no creará concurrencia interna; la aplicación integradora seguirá siendo responsable de limitar aperturas simultáneas según su presupuesto real. La omisión de pruebas en otros equipos es una decisión de alcance, no evidencia de compatibilidad universal.
|
|
83
|
+
|
|
84
|
+
## Métricas
|
|
85
|
+
|
|
86
|
+
El informe JSON incluye:
|
|
87
|
+
|
|
88
|
+
- Identificación del intérprete, plataforma, arquitectura, procesador y CPUs lógicas.
|
|
89
|
+
- Versión instalada de `argon2-cffi`.
|
|
90
|
+
- Parámetros Argon2id y memoria teórica estimada para la concurrencia máxima.
|
|
91
|
+
- Latencia por derivación: mínimo, mediana, máximo y percentil 95 (nearest-rank).
|
|
92
|
+
- Tiempo de pared por lote concurrente: mediana y percentil 95.
|
|
93
|
+
|
|
94
|
+
La memoria estimada corresponde al coste de trabajo configurado multiplicado por el número de derivaciones concurrentes. No incluye overhead del proceso, bibliotecas, runtime ni sistema operativo. No se presenta una medición portable de memoria residente máxima: comparar RSS entre sistemas requeriría instrumentación específica de plataforma y puede confundir el high-water mark histórico del proceso con el consumo de una ejecución concreta.
|
|
95
|
+
|
|
96
|
+
## Protocolo de medición recomendado
|
|
97
|
+
|
|
98
|
+
1. Ejecutar en el equipo más modesto que se pretenda soportar, conectado a corriente y en un modo de energía documentado.
|
|
99
|
+
2. Registrar modelo de CPU, RAM instalada, sistema operativo, arquitectura, versión de Python y versión de `argon2-cffi`.
|
|
100
|
+
3. Cerrar tareas intensivas y evitar medir durante actualizaciones, compilaciones u otras cargas concurrentes.
|
|
101
|
+
4. Ejecutar el comando predeterminado al menos tres veces como procesos independientes.
|
|
102
|
+
5. Conservar los informes JSON sin modificar y comparar mediana y p95, no una sola observación.
|
|
103
|
+
6. Repetir en cada plataforma objetivo, en particular en equipos de memoria limitada.
|
|
104
|
+
7. Evaluar la concurrencia según el presupuesto real de memoria de la aplicación. El resultado concurrente no debe interpretarse como autorización para que la librería cree concurrencia interna.
|
|
105
|
+
|
|
106
|
+
No combinar mediciones tomadas con distintos perfiles de energía, condiciones térmicas o cargas de fondo como si fueran equivalentes.
|
|
107
|
+
|
|
108
|
+
## Perfil alternativo y pruebas rápidas
|
|
109
|
+
|
|
110
|
+
El script admite parámetros personalizados para experimentación. Cualquier resultado cuyo perfil no sea exactamente 65.536 KiB / 3 / 1 queda etiquetado como `custom-profile-not-production`.
|
|
111
|
+
|
|
112
|
+
Un perfil reducido puede servir para comprobar el funcionamiento del script, pero **no** para estimar el rendimiento del perfil propuesto, validar seguridad ni justificar una decisión de producción. Los parámetros reducidos de los golden vectors tampoco son un perfil de producción.
|
|
113
|
+
|
|
114
|
+
## Seguridad y reproducibilidad
|
|
115
|
+
|
|
116
|
+
- El benchmark usa una contraseña y un salt fijos, públicos y exclusivos de esta herramienta. No son secretos ni deben reutilizarse en producción.
|
|
117
|
+
- No solicita, registra ni persiste contraseñas del usuario.
|
|
118
|
+
- No guarda ni muestra las claves derivadas; solo comprueba su longitud.
|
|
119
|
+
- El salt fijo hace repetible el trabajo de la KDF, pero no modela la generación aleatoria de salt de producción.
|
|
120
|
+
- La herramienta no abre contenedores MasterKey ni keysets Tink y no valida la implementación de producción.
|
|
121
|
+
- No debe ejecutarse automáticamente en cada push ni usarse como umbral de CI.
|
|
122
|
+
|
|
123
|
+
## Criterio de decisión
|
|
124
|
+
|
|
125
|
+
La propuesta actual plantea una latencia orientativa de 0,5–1,5 segundos para una apertura individual en hardware modesto. El benchmark debe aportar evidencia para decidir si ese objetivo es razonable en los dispositivos objetivo. No se debe reducir automáticamente el coste criptográfico para satisfacer el objetivo temporal.
|
|
126
|
+
|
|
127
|
+
La decisión final debe registrar:
|
|
128
|
+
- Equipos y plataformas medidos.
|
|
129
|
+
- Informes completos y condiciones de ejecución.
|
|
130
|
+
- Mediana y p95 por dispositivo.
|
|
131
|
+
- Memoria teórica por concurrencia y presupuesto operativo de la aplicación.
|
|
132
|
+
- Perfil aprobado o cambios explícitos a la política.
|
|
133
|
+
|
|
134
|
+
El perfil está aprobado para v1. Los límites de entrada y contraseña continúan pendientes de confirmación contractual; las pruebas del parser productivo también siguen pendientes.
|