mirror of
https://github.com/bitcoin/bips.git
synced 2026-10-19 19:29:18 +00:00
bip-0138: make PLAINTEXT LENGTH mandatory and add optional payload padding
This commit is contained in:
48
bip-0138.md
48
bip-0138.md
@@ -263,7 +263,39 @@ Implementations MUST reject empty payloads.
|
||||
`CIPHERTEXT` is the encrypted data resulting from encryption of `PAYLOAD` with algorithm
|
||||
defined in `ENCRYPTION` where `PAYLOAD` is encoded following this format:
|
||||
|
||||
`CONTENT` `PLAINTEXT`
|
||||
`CONTENT` `LENGTH` `PLAINTEXT` (`PADDING`)
|
||||
|
||||
`LENGTH`: variable-length integer representing the length of `PLAINTEXT` in bytes. It MUST
|
||||
be present.
|
||||
|
||||
`PLAINTEXT`: the `LENGTH` bytes of payload data.
|
||||
|
||||
`PADDING`: OPTIONAL bytes after `PLAINTEXT`, up to the end of the decrypted `PAYLOAD`.
|
||||
Parsers MUST consume exactly `LENGTH` bytes of `PLAINTEXT` and MUST ignore everything after
|
||||
it. These bytes are reserved for size padding (see Padding) and/or vendor-specific data,
|
||||
the same way trailing bytes after `CIPHERTEXT` are reserved and ignored.
|
||||
|
||||
#### Padding
|
||||
|
||||
Backups that are updated over time can leak information through their size even when the
|
||||
contents are encrypted. A wallet that uploads a new backup after every received transaction
|
||||
can reveal activity to the storage provider through changing payload sizes. This is relevant
|
||||
for mutable payloads such as BIP-329 or BIP-0139.[^padding-privacy]
|
||||
|
||||
Padding is OPTIONAL and is an encoder concern only: decoders ignore the `PADDING` bytes and
|
||||
MUST NOT validate any bucket. Because the padding sits inside `CIPHERTEXT`, the
|
||||
`ENCRYPTED_PAYLOAD` `LENGTH` reveals only the padded size, not the real `PLAINTEXT` size.
|
||||
|
||||
Encoders that pad SHOULD zero-fill `PAYLOAD` up to the smallest bucket `S_n` that fits it,
|
||||
with `S_0 = 10240` (10 KiB) and `S_n = floor(S_0 * (5 / 4)^n)`. Payloads of 10 KiB or less
|
||||
are padded to 10 KiB. This keeps padding overhead under 25% above the smallest fitting bucket
|
||||
while coarsening the observable size. Padding is RECOMMENDED for mutable payloads and
|
||||
unnecessary for static ones such as BIP-380 descriptors and BIP-388 wallet policies.
|
||||
|
||||
[^padding-privacy]: **Why pad inside the ciphertext?**
|
||||
Padding the encrypted payload, rather than appending bytes after the backup, hides the
|
||||
real payload size from anyone who parses the backup, not just from someone who measures
|
||||
the file size. The size field a parser sees is the padded `LENGTH`.
|
||||
|
||||
#### Integer Encodings
|
||||
|
||||
@@ -353,19 +385,19 @@ The version field enables possible future enhancements:
|
||||
|
||||
### Test Vectors
|
||||
|
||||
[key_types.json](./bip-encrypted-backup/test_vectors/keys_types.json) contains test
|
||||
[key_types.json](./bip-0138/test_vectors/keys_types.json) contains test
|
||||
vectors for key serialisations.
|
||||
[content_type.json](./bip-encrypted-backup/test_vectors/content_type.json) contains test
|
||||
[content_type.json](./bip-0138/test_vectors/content_type.json) contains test
|
||||
vectors for contents types serialisations.
|
||||
[derivation_path.json](./bip-encrypted-backup/test_vectors/derivation_path.json) contains
|
||||
[derivation_path.json](./bip-0138/test_vectors/derivation_path.json) contains
|
||||
test vectors for derivation paths serialisations.
|
||||
[individual_secrets.json](./bip-encrypted-backup/test_vectors/individual_secrets.json)
|
||||
[individual_secrets.json](./bip-0138/test_vectors/individual_secrets.json)
|
||||
contains test vectors for individual secrets serialization.
|
||||
[encryption_secret.json](./bip-encrypted-backup/test_vectors/encryption_secret.json)
|
||||
[encryption_secret.json](./bip-0138/test_vectors/encryption_secret.json)
|
||||
contains test vectors for generation of encryption secret.
|
||||
[chacha20poly1305_encryption.json](./bip-encrypted-backup/test_vectors/chacha20poly1305_encryption.json)
|
||||
[chacha20poly1305_encryption.json](./bip-0138/test_vectors/chacha20poly1305_encryption.json)
|
||||
contains test vectors for ciphertexts generated using CHACHA20-POLY1305.
|
||||
[encrypted_backup.json](./bip-encrypted-backup/test_vectors/encrypted_backup.json)
|
||||
[encrypted_backup.json](./bip-0138/test_vectors/encrypted_backup.json)
|
||||
contains test vectors for generation of complete encrypted backup.
|
||||
|
||||
## Acknowledgements
|
||||
|
||||
Reference in New Issue
Block a user