63 lines
2.6 KiB
Markdown
63 lines
2.6 KiB
Markdown
---
|
|
name: open_aead
|
|
kind: function
|
|
lang: go
|
|
domain: cybersecurity
|
|
version: "1.0.0"
|
|
purity: impure
|
|
signature: "func OpenAEAD(key, nonce, ciphertext, aad []byte) ([]byte, error)"
|
|
description: "Descifra y autentica un ciphertext producido por SealAEAD usando ChaCha20-Poly1305. Devuelve error explícito si la autenticación falla (ciphertext alterado, clave incorrecta o AAD distinto)."
|
|
tags: [messaging, e2e-crypto, crypto, aead, chacha20poly1305, symmetric, e2e-messaging]
|
|
uses_functions: []
|
|
uses_types: []
|
|
returns: []
|
|
returns_optional: false
|
|
error_type: "error_go_core"
|
|
imports:
|
|
- golang.org/x/crypto/chacha20poly1305
|
|
params:
|
|
- name: key
|
|
desc: "Clave simétrica de exactamente 32 bytes. Debe ser la misma usada en SealAEAD."
|
|
- name: nonce
|
|
desc: "Nonce de 12 bytes devuelto por SealAEAD. Debe transmitirse junto al ciphertext."
|
|
- name: ciphertext
|
|
desc: "Ciphertext producido por SealAEAD (incluye los 16 bytes del tag Poly1305)."
|
|
- name: aad
|
|
desc: "Datos autenticados adicionales. Debe ser idéntico al aad usado en SealAEAD, o nil si se pasó nil."
|
|
output: "Plaintext descifrado, o error si la autenticación falla o la clave tiene longitud incorrecta."
|
|
tested: true
|
|
tests:
|
|
- "round-trip con aad"
|
|
- "round-trip sin aad (nil)"
|
|
- "error con clave de longitud incorrecta"
|
|
- "error de autenticacion con ciphertext modificado"
|
|
- "error de autenticacion con aad distinto"
|
|
- "nonces distintos en llamadas sucesivas"
|
|
test_file_path: "functions/cybersecurity/e2e_messaging_crypto_test.go"
|
|
file_path: "functions/cybersecurity/open_aead.go"
|
|
---
|
|
|
|
## Ejemplo
|
|
|
|
```go
|
|
// nonce y ct vienen de SealAEAD; aad debe reconstruirse igual
|
|
aad := []byte("room:sala-general:seq:42")
|
|
plaintext, err := cybersecurity.OpenAEAD(key, nonce, ct, aad)
|
|
if err != nil {
|
|
// mensaje alterado, clave incorrecta o aad distinto — descartar
|
|
log.Printf("autenticación fallida: %v", err)
|
|
return
|
|
}
|
|
fmt.Printf("mensaje: %s\n", plaintext)
|
|
```
|
|
|
|
## Cuando usarla
|
|
|
|
Al recibir un mensaje del bus: después de resolver la room key con OpenKeyBox, llama OpenAEAD para descifrar y verificar integridad. Si devuelve error, el mensaje llegó corrupto o fue alterado en tránsito — descartar siempre, nunca procesar plaintext parcial.
|
|
|
|
## Gotchas
|
|
|
|
- El error no distingue entre "clave incorrecta", "nonce incorrecto" y "ciphertext alterado": todos devuelven el mismo error de autenticación por diseño (evita oráculos de padding).
|
|
- Si el ciphertext tiene menos de 16 bytes, la función devuelve error antes de intentar descifrar.
|
|
- El aad debe ser reconstructible por el receptor de forma independiente (no viaja en el mensaje cifrado).
|