---
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`.