egutierrez
988e901066
Añade campos params y output al frontmatter YAML de las 506 funciones del registry. Cada parámetro tiene descripción semántica (qué representa, unidades, rango típico) y cada función describe qué produce su output. Permite a agentes razonar sobre cadenas de composición (ej: prices → log_return → sharpe_ratio) sin leer código.
66 lines
2.6 KiB
Markdown
66 lines
2.6 KiB
Markdown
---
|
|
name: envelope_decrypt
|
|
kind: function
|
|
lang: py
|
|
domain: cybersecurity
|
|
version: "1.0.0"
|
|
purity: impure
|
|
signature: "def envelope_decrypt(ciphertext: bytes, master_key: bytes) -> bytes"
|
|
description: "Descifra datos cifrados con envelope_encrypt. Si los datos no comienzan con el magic b'OVE1', los retorna sin modificar (passthrough). Soporta archivos que pueden o no estar cifrados sin necesidad de chequeo previo."
|
|
tags: [decryption, aes, gcm, envelope-encryption, dek, kek, cryptography, cybersecurity, passthrough]
|
|
uses_functions: [envelope_encrypt_py_cybersecurity]
|
|
uses_types: []
|
|
returns: []
|
|
returns_optional: false
|
|
error_type: "error_go_core"
|
|
imports: [cryptography, struct]
|
|
params:
|
|
- name: ciphertext
|
|
desc: "datos cifrados con envelope_encrypt o datos sin cifrar (passthrough si no comienzan con magic OVE1)"
|
|
- name: master_key
|
|
desc: "clave maestra KEK de 32 bytes para descifrar la file key"
|
|
output: "bytes desencriptados, o bytes sin modificar si el magic no es OVE1"
|
|
tested: true
|
|
tests:
|
|
- "decrypt de datos cifrados"
|
|
- "decrypt de datos no cifrados passthrough"
|
|
- "key incorrecta"
|
|
- "envelope truncado"
|
|
- "magic invalido"
|
|
test_file_path: "python/functions/cybersecurity/envelope_encrypt_test.py"
|
|
file_path: "python/functions/cybersecurity/cybersecurity.py"
|
|
---
|
|
|
|
## Ejemplo
|
|
|
|
```python
|
|
import secrets
|
|
from cybersecurity import envelope_encrypt, envelope_decrypt
|
|
|
|
master_key = secrets.token_bytes(32)
|
|
|
|
# Caso 1: descifrar datos cifrados
|
|
ciphertext = envelope_encrypt(b"datos secretos", master_key)
|
|
plaintext = envelope_decrypt(ciphertext, master_key)
|
|
# plaintext == b"datos secretos"
|
|
|
|
# Caso 2: passthrough — datos no cifrados
|
|
raw = b"archivo en plano"
|
|
result = envelope_decrypt(raw, master_key)
|
|
# result == b"archivo en plano" (sin modificar)
|
|
|
|
# Caso 3: key incorrecta — lanza InvalidTag
|
|
wrong_key = secrets.token_bytes(32)
|
|
# envelope_decrypt(ciphertext, wrong_key) → cryptography.exceptions.InvalidTag
|
|
```
|
|
|
|
## Notas
|
|
|
|
Implementacion original inspirada en OpenViking `openviking/crypto/encryptor.py` (AGPL-3.0). Reimplementada desde cero.
|
|
|
|
- **Passthrough**: si `ciphertext` no empieza con `b"OVE1"`, se retorna sin modificar. Permite usar la funcion indistintamente en archivos cifrados y no cifrados.
|
|
- **Autenticacion GCM**: si la master_key es incorrecta o los datos fueron manipulados, `cryptography.exceptions.InvalidTag` es lanzado por la capa GCM — nunca se retorna texto corrupto.
|
|
- **ValueError**: lanzado si el envelope tiene magic correcto pero estructura invalida (truncado o version no soportada).
|
|
- `master_key` debe ser de exactamente 32 bytes para AES-256.
|
|
- Requiere `cryptography` instalado: `uv add cryptography`.
|