Skip to content

Commit

Permalink
reformat all tables
Browse files Browse the repository at this point in the history
  • Loading branch information
@staltz
staltz committed Jul 15, 2021
1 parent 4958efb commit 11f7d16
Showing 1 changed file with 119 additions and 78 deletions.
197 changes: 119 additions & 78 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,144 +1,185 @@
# 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
└─────────────────────────────────────┬────────────────────────────────────────────────┘└────┬─────┘
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
[gabby grove]: https://github.com/ssbc/ssb-spec-drafts/tree/master/drafts/draft-ssb-core-gabbygrove/00
[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

0 comments on commit 11f7d16

Please sign in to comment.