From b7ba2840a980ffde6831bc270fe804e041b1e638 Mon Sep 17 00:00:00 2001
From: pythcoiner <pythcoiner@proton.me>
Date: Thu, 18 Jun 2026 03:02:17 -0400
Subject: [PATCH] bip-138: clarify CONTENT is a single TLV and forbid all-zero
 nonce

---
 bip-0138.md | 24 ++++++++++++++++--------
 1 file changed, 16 insertions(+), 8 deletions(-)

diff --git a/bip-0138.md b/bip-0138.md
index e70ab3e7..b88356b5 100644
--- a/bip-0138.md
+++ b/bip-0138.md
@@ -167,6 +167,9 @@ and integrity.
 * let $nonce$ = random(96 bits)
 * let $ciphertext$ = encrypt($payload$, $secret$, $nonce$)
 
+The $nonce$ MUST NOT be all zero. If the random source yields an all-zero nonce,
+the encoder MUST generate a new one.
+
 ### Decryption
 
 In order to decrypt the payload of a backup, the owner of a certain public key p
@@ -309,6 +312,10 @@ it follows this format:
 
 `TYPE` (`LENGTH`) `DATA`
 
+`CONTENT` is a single `TYPE (LENGTH) DATA` triple, one blob describing `PLAINTEXT`.
+It is not a sequence of entries; it is immediately followed by the payload `LENGTH`
+and `PLAINTEXT`.
+
 `TYPE`: 1-byte unsigned integer identifying how to interpret `DATA`.
 
 | Value  | Definition                             |
@@ -332,16 +339,17 @@ For `TYPE` values defined above:
 For all `TYPE` values except `0x01`, parsers MUST reject `CONTENT` if `LENGTH` exceeds
 the remaining payload bytes.
 
-Parsers MUST skip unknown `TYPE` values less than `0x80`, by consuming `LENGTH` bytes
-of `DATA`.
+For an unknown `TYPE` less than `0x80`, parsers MUST consume its `LENGTH` bytes of
+`DATA`, treat the content type as unknown, and continue with the payload `LENGTH`
+and `PLAINTEXT`.
 
-For unknown `TYPE` values greater than or equal to `0x80`, parsers MUST stop parsing
-`CONTENT`.[^type-upgrade]
+For an unknown `TYPE` greater than or equal to `0x80`, parsers MUST reject the
+payload.[^type-upgrade]
 
 [^type-upgrade]: **Why the 0x80 threshold?**
-    The `TYPE >= 0x80` rule means we're not stuck with the current TLV encoding.
-    It has a nice upgrade property: you can still encode backward compatible stuff
-    at the start.
+    The `TYPE >= 0x80` rule keeps the encoding upgradeable. A future version can
+    define a new content type at or above `0x80` that older parsers reject rather
+    than misread, while types below `0x80` stay backward compatible.
 
 #### Encrypted Payload
 
@@ -349,7 +357,7 @@ For unknown `TYPE` values greater than or equal to `0x80`, parsers MUST stop par
 
 `NONCE` `LENGTH` `CIPHERTEXT`
 
-`NONCE`: 12-byte (96-bit) nonce.
+`NONCE`: 12-byte (96-bit) nonce. Parsers MUST reject a backup whose `NONCE` is all zero.
 `LENGTH`: variable-length integer representing ciphertext length.
 `CIPHERTEXT`: variable-length ciphertext.