fn_registry/python/functions/cybersecurity/envelope_decrypt.md

name, kind, lang, domain, version, purity, signature, description, tags, uses_functions, uses_types, returns, returns_optional, error_type, imports, params, output, tested, tests, test_file_path, file_path

name	kind	lang	domain	version	purity	signature	description	tags	uses_functions	uses_types	returns	returns_optional	error_type	imports	params	output	tested	tests	test_file_path	file_path
envelope_decrypt	function	py	cybersecurity	1.0.0	impure	def envelope_decrypt(ciphertext: bytes, master_key: bytes) -> bytes	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.	decryption aes gcm envelope-encryption dek kek cryptography cybersecurity passthrough	envelope_encrypt_py_cybersecurity			false	error_go_core	cryptography struct	name desc ciphertext datos cifrados con envelope_encrypt o datos sin cifrar (passthrough si no comienzan con magic OVE1) name desc master_key clave maestra KEK de 32 bytes para descifrar la file key	bytes desencriptados, o bytes sin modificar si el magic no es OVE1	true	decrypt de datos cifrados decrypt de datos no cifrados passthrough key incorrecta envelope truncado magic invalido	python/functions/cybersecurity/envelope_encrypt_test.py	python/functions/cybersecurity/cybersecurity.py

Ejemplo

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.