diff --git a/README.md b/README.md index c522508..86ed7be 100644 --- a/README.md +++ b/README.md @@ -1,114 +1,138 @@ -# SSB binary field encodings +# SSB Binary Field Encodings Shortname: SSB-BFE Definition of binary encodings for common types such as message ids -and feed ids to be used in binary feed formats. This can be seen as an -extension of the types defined in [TFK]. +and feed ids to be used in binary feed formats. -The binary encoding is defined as the concatenation of: -- the `type` of thing as a UInt8 -- the `format` of the `type` as a UInt8 -- the `data` for the actual bytes +The binary encoding is defined as the concatenation of three parts, often known +as **T-F-D**: -## Codes +- The `type` of thing as a UInt8 byte +- The `format` of the `type` as a UInt8 byte +- The `data` as a sequence of UInt8 bytes - | type code | referencing | - | ----------- | ------------- | - | 0 | identity | - | 1 | message | - | 2 | blob | - | 3 | diffie-hellman key | - | 4 | signature | - | 5 | box encoding | - | 6 | value types | +## Types -For canonical, machine-readable definitions, see `binary-field-encodings.json` + | Type code | Referencing | + | ----------- | ------------------ | + | 0 | Peer ID | + | 1 | Message ID | + | 2 | Blob ID | + | 3 | Diffie-Hellman key | + | 4 | Signature | + | 5 | Encrypted data | + | 6 | Generic data | -### Identity type +### Peer ID formats -Sometimes also know as feeds. Since this encompasses identities that -does not create messages themselves, such as fusion identities -we will use the name identity instead. +A peer ID TFD represents the public portion of a cryptographic keypair used to +identify a peer, and in turn identify feeds. Note however that there are some +identities that do not have a feed nor create messages, such as Fusion +Identities. -| Type | format code | format name | specification | -|------|-------------|-----------------|------------------| -| 0 | 0 | classic | [classic] | -| 0 | 1 | gabby grove | [gabby grove] | -| 0 | 2 | bamboo | [bamboo] | -| 0 | 3 | bendy butt | [bendy butt] | -| 0 | 4 | fusion identity | [fusionidentity] | +| Type code | Format code | Data length | Format name | Specification | +|-----------|-------------|-------------|-----------------|------------------| +| 0 | 0 | 32 bytes | Classic | [classic] | +| 0 | 1 | 32 bytes | Gabby Grove | [gabby grove] | +| 0 | 2 | ? | Bamboo | [bamboo] | +| 0 | 3 | 32 bytes | Bendy Butt | [bendy butt] | +| 0 | 4 | 32 bytes | Fusion Identity | [fusionidentity] | -Example: +#### Example -String encoding of a classic feed: +Given a sigil-based string encoding of a classic SSB feed: ``` @6CAxOI3f+LUOVrbAl0IemqiS7ATpQvr9Mdw9LC4+Uv0=.ed25519 │└─────────────────────┬────────────────────┘└───┬──┘ - sigil base64 encoded key suffix + sigil base64 encoded data suffix ``` -### Message type +Its BFE encoding are the following bytes displayed in hexadecimal: -| Type | format code | format name | specification | -|------|-------------|---------------|-----------------| -| 1 | 0 | classic | [classic] | -| 1 | 1 | gabby grove | [gabby grove] | -| 1 | 2 | cloaked group | [private group] | -| 1 | 3 | bamboo | [bamboo] | -| 1 | 4 | bendy butt | [bendy butt] | +``` + 00 00 e8 20 31 38 8d df f8 b5 0e 56 b6 c0 97 42 1e 9a a8 92 ec 04 e9 42 fa fd 31 dc 3d 2c 2e 3e 52 fd + │ │ └────────────────────┬────────────────────────────────────────────────────────────────────────┘ +type │ data + format +``` + +### Message ID formats + +A message ID TFD represents the hash that uniquely identifies a message +published on a feed. Some message ID formats directly reference the hash +algorithm utilized, while others leave it implicit in the specification. -Example: +| Type code | Format code | Data length | Format name | Specification | +|---------- |-------------|-------------|---------------|-----------------| +| 1 | 0 | 32 bytes | Classic | [classic] | +| 1 | 1 | 32 bytes | Gabby Grove | [gabby grove] | +| 1 | 2 | 32 bytes | Cloaked group | [private group] | +| 1 | 3 | ? | Bamboo | [bamboo] | +| 1 | 4 | 32 bytes | Bendy Butt | [bendy butt] | -String encoding of a classic message id: +#### Example + +Given a sigil-based string encoding of a classic SSB message ID: ``` %R8heq/tQoxEIPkWf0Kxn1nCm/CsxG2CDpUYnAvdbXY8=.sha256 - │└─────────────────────┬────────────────────┘└───┬─┘ - sigil base64 encoded key suffix + │└─────────────────────┬────────────────────┘└──┬──┘ + sigil base64 encoded data suffix ``` -Binary encoding (as hex) of the same thing: +Its BFE encoding are the following bytes displayed in hexadecimal: ``` - 01 00 47 c8 5e ab fb 50 a3 11 08 3e 45 9f d0 ac 67 d6 70 a6 fc 2b 31 1b 60 83 a5 46 27 02 f7 5b 5d 8f - │ │ └────────────────────┬────────────────────────────────────────────────────────────────────────┘ -type │ hex encoded key + 01 00 47 c8 5e ab fb 50 a3 11 08 3e 45 9f d0 ac 67 d6 70 a6 fc 2b 31 1b 60 83 a5 46 27 02 f7 5b 5d 8f + │ │ └────────────────────┬────────────────────────────────────────────────────────────────────────┘ +type │ data format ``` -### Blob type +### Blob ID formats + +A blob ID TFD represents the hash that uniquely identifies the blob. -| Type | format code | format name | specification | -|------|-------------|-------------|---------------| -| 2 | 0 | classic | [classic] | +| Type code | Format code | Data length | Format name | Specification | +|-----------|-------------|-------------|-------------|---------------| +| 2 | 0 | 32 bytes | Classic | [classic] | -Example: +#### Example -String encoding of a classic blob id: +Given a sigil-based string encoding of a classic SSB blob ID: ``` &S7+CwHM6dZ9si5Vn4ftpk/l/ldbRMqzzJos+spZbWf4=.sha256 │└─────────────────────┬────────────────────┘└───┬─┘ - sigil base64 encoded key suffix + sigil base64 encoded data suffix ``` -### Diffie-hellman type +Its BFE encoding are the following bytes displayed in hexadecimal: -| Type | format code | format name | specification | -|------|-------------|-------------|---------------| -| 3 | 0 | curve25519 | | +``` + 02 00 4b bf 82 c0 73 3a 75 9f 6c 8b 95 67 e1 fb 69 93 f9 7f 95 d6 d1 32 ac f3 26 8b 3e b2 96 5b 59 fe + │ │ └────────────────────┬────────────────────────────────────────────────────────────────────────┘ +type │ data + format +``` + +### Diffie-hellman formats + +| Type code | Format code | Data length | Format name | Specification | +|-----------|-------------|-------------|-------------|---------------| +| 3 | 0 | 32 bytes | curve25519 | | -### Signature type +### Signature formats -| Type | format code | format name | specification | -|------|-------------|-------------|---------------| -| 4 | 0 | ed25519 | | +| Type code | Format code | Data length | Format name | specification | +|-----------|-------------|-------------|-------------|---------------| +| 4 | 0 | 64 bytes | ed25519 | | -Example: +#### Example -String encoding of a classic ed25519 signature: +Given a base64 string encoding of a classic SSB ed25519 signature: ``` nkY4Wsn9feosxvX7bpLK7OxjdSrw6gSL8sun1n2TMLXKySYK9L5itVQnV2nQUctFsrUOa2istD2vDk1B0uAMBQ==.sig.ed25519 @@ -116,23 +140,36 @@ String encoding of a classic ed25519 signature: base64 encoded signature suffix ``` -### Box encoding type +Its BFE encoding are the following bytes displayed in hexadecimal: + +``` + 04 00 9e 46 38 5a c9 fd 7d ea 2c c6 f5 fb 6e 92 ca ec ec 63 75 2a f0 ea 04 8b f2 cb a7 d6 7d 93 30 b5 ca c9 26 0a f4 be 62 b5 54 27 57 69 d0 51 cb 45 b2 b5 0e 6b 68 ac b4 3d af 0e 4d 41 d2 e0 0c 05 + │ │ └────────────────────┬────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +type │ data + format +``` + +### Encrypted data formats + +When content is encrypted (in other words, "boxed") in SSB, it is provided as +uninterpretable bytes, plus a tag that identifies which algorithm was used for +encrypting it, such as `box` or `box2`. -| Type | format code | format name | specification | -|------|-------------|-------------|---------------| -| 5 | 0 | box1 | | -| 5 | 1 | box2 | | +| Type code | Format code | Data length | Format name | Specification | +|-----------|-------------|-------------|-------------|-----------------| +| 5 | 0 | Arbitrary | box | [private box] | +| 5 | 1 | Arbitrary | box2 | [envelope spec] | -### Value type +### Generic data formats -| Type | format code | format name | specification | -|------|-------------|--------------|-------------------------------| -| 6 | 0 | utf8 string | | -| 6 | 1 | boolean | false 0x060100, true 0x060101 | -| 6 | 2 | nil | 0x0602 | +BFE supports encoding data types with no semantics attached to them. They are +merely categorized into formats that represent their data type. -Value type can be used for binary encodings that has limited support -for different types such as [bencode]. +| Type code | Format code | Data length | Format name | Specification | +|-----------|-------------|-------------|-------------|-------------------------------| +| 6 | 0 | Arbitrary | UTF8 string | [UTF8] | +| 6 | 1 | 1 byte | Boolean | Data byte is 0 for False, 1 for True | +| 6 | 2 | 0 bytes | Nil | [null pointer] | [TFK]: https://github.com/ssbc/envelope-spec/blob/master/encoding/tfk.md [classic]: https://ssbc.github.io/scuttlebutt-protocol-guide/#message-format @@ -140,5 +177,9 @@ for different types such as [bencode]. [bamboo]: https://github.com/AljoschaMeyer/bamboo [private group]: https://github.com/ssbc/private-group-spec [bendy butt]: https://github.com/ssb-ngi-pointer/bendy-butt-spec +[private box]: https://ssbc.github.io/scuttlebutt-protocol-guide/#private-messages +[envelope spec]: https://github.com/ssbc/envelope-spec +[null pointer]: https://en.wikipedia.org/wiki/Null_pointer +[UTF8]: https://datatracker.ietf.org/doc/html/rfc3629 [fusionidentity]: https://github.com/ssb-ngi-pointer/fusion-identity-spec/ [bencode]: https://en.wikipedia.org/wiki/Bencode