61 lines
2.7 KiB
Markdown
61 lines
2.7 KiB
Markdown
---
|
|
name: seal_aead
|
|
kind: function
|
|
lang: go
|
|
domain: cybersecurity
|
|
version: "1.0.0"
|
|
purity: impure
|
|
signature: "func SealAEAD(key, plaintext, aad []byte) (nonce, ciphertext []byte, err error)"
|
|
description: "Cifra plaintext con ChaCha20-Poly1305 usando una clave simétrica de 32 bytes. Genera un nonce aleatorio por llamada. Admite datos autenticados adicionales (AAD) para vincular contexto al cifrado sin cifrarlo."
|
|
tags: [messaging, e2e-crypto, crypto, aead, chacha20poly1305, symmetric, e2e-messaging]
|
|
uses_functions: []
|
|
uses_types: []
|
|
returns: []
|
|
returns_optional: false
|
|
error_type: "error_go_core"
|
|
imports:
|
|
- crypto/rand
|
|
- golang.org/x/crypto/chacha20poly1305
|
|
params:
|
|
- name: key
|
|
desc: "Clave simétrica de exactamente 32 bytes (256 bits). Típicamente la room key distribuida con SealKeyBox."
|
|
- name: plaintext
|
|
desc: "Bytes a cifrar. Puede ser vacío."
|
|
- name: aad
|
|
desc: "Datos autenticados adicionales (AAD): se autentican pero no se cifran. Útil para room ID, número de secuencia, etc. Puede ser nil."
|
|
output: "nonce (12 bytes aleatorios), ciphertext (plaintext cifrado + 16 bytes de tag Poly1305), o error si la clave tiene longitud incorrecta o falla el RNG."
|
|
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/seal_aead.go"
|
|
---
|
|
|
|
## Ejemplo
|
|
|
|
```go
|
|
key := make([]byte, 32) // en producción: room key distribuida con SealKeyBox
|
|
aad := []byte("room:sala-general:seq:42")
|
|
nonce, ct, err := cybersecurity.SealAEAD(key, []byte("hola sala"), aad)
|
|
if err != nil {
|
|
log.Fatal(err)
|
|
}
|
|
// Almacenar nonce junto al ciphertext para descifrar después
|
|
```
|
|
|
|
## Cuando usarla
|
|
|
|
Al cifrar cada mensaje en una sala del bus: usa la room key de la sala como `key`, incluye el ID de sala y número de secuencia en `aad` para prevenir replay attacks entre salas, y transmite `nonce + ciphertext` juntos al destinatario.
|
|
|
|
## Gotchas
|
|
|
|
- El nonce es aleatorio (12 bytes): con una misma key, la probabilidad de colisión de nonces es despreciable para <2^32 mensajes, pero en escenarios de alto volumen considera rotar la room key periódicamente.
|
|
- El ciphertext es 16 bytes más largo que el plaintext (tag Poly1305).
|
|
- `aad` no viaja cifrado: el destinatario debe reconstruirlo independientemente para verificar. Si aad difiere aunque sea 1 bit, OpenAEAD falla con error de autenticación.
|
|
- Nunca reutilizar `(key, nonce)` para dos plaintexts distintos: rompe la confidencialidad de ChaCha20.
|