Home

Awesome

<!-- SPDX-FileCopyrightText: 2021 Anders Rune Jensen SPDX-License-Identifier: CC0-1.0 -->

SSB Binary Field Encodings Specification

Shortname: ssb-bfe-spec

Definition of binary encodings for common types such as message IDs and feed IDs to be used in binary feed formats.

The binary encoding is defined as the concatenation of three parts, often known as T-F-D:

Types

Type codeReferencingIn bfe.json
0Feed IDfeed
1Message IDmessage
2Blob IDblob
3Encryption keyencryption-key
4Signaturesignature
5Encrypted dataencrypted
6Generic datageneric
7Identityidentity

0. Feed ID formats

A feed ID TFD represents the public portion of a cryptographic keypair used to identify a feed, and verify message signatures.

Type codeFormat codeData lengthSpecificationIn bfe.json
0032 bytesClassic SSB Feedclassic
0132 bytesGabby Grovegabbygrove-v1
0232 bytesBamboobamboo
0332 bytesBendy Buttbendybutt-v1
0432 bytesButtwoobuttwoo-v1
0532 bytesIndex feedindexed-v1

Example

Given a sigil-based string encoding of a classic SSB feed:

  @6CAxOI3f+LUOVrbAl0IemqiS7ATpQvr9Mdw9LC4+Uv0=.ed25519
  │└─────────────────────┬────────────────────┘└───┬──┘
 sigil           base64 encoded data            suffix

Its BFE encoding is the following bytes displayed in hexadecimal:

  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

1. 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.

Type codeFormat codeData lengthSpecificationIn bfe.json
1032 bytesClassic SSB Msgclassic
1132 bytesGabby Grovegabbygrove-v1
1232 bytesPrivate Groupcloaked
1364 bytesBamboobamboo
1432 bytesBendy Buttbendybutt-v1
1532 bytesButtwoobuttwoo-v1
1632 bytesIndex feedindexed-v1

Example

Given a sigil-based string encoding of a classic SSB message ID:

  %R8heq/tQoxEIPkWf0Kxn1nCm/CsxG2CDpUYnAvdbXY8=.sha256
  │└─────────────────────┬────────────────────┘└──┬──┘
 sigil           base64 encoded data            suffix

Its BFE encoding is 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  │                    data
     format

2. Blob ID formats

A blob ID TFD represents the hash that uniquely identifies the blob.

Type codeFormat codeData lengthSpecificationIn bfe.json
2032 bytesClassic SSB Blobclassic

Example

Given a sigil-based string encoding of a classic SSB blob ID:

  &S7+CwHM6dZ9si5Vn4ftpk/l/ldbRMqzzJos+spZbWf4=.sha256
  │└─────────────────────┬────────────────────┘└───┬─┘
 sigil           base64 encoded data            suffix

Its BFE encoding is the following bytes displayed in hexadecimal:

  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

3. Encryption Key formats

Keys used for encryption

Type codeFormat codeData lengthSpecificationIn bfe.json
3032 bytesPrivate Group DMbox2-dm-dh
3132 bytesPrivate Group PO boxbox2-pobox-dh

4. Signature formats

Type codeFormat codeData lengthSpecificationIn bfe.json
4064 bytesClassic SSB Signaturemsg-ed25519

Example

Given a base64 string encoding of a Classic SSB ed25519 signature:

  nkY4Wsn9feosxvX7bpLK7OxjdSrw6gSL8sun1n2TMLXKySYK9L5itVQnV2nQUctFsrUOa2istD2vDk1B0uAMBQ==.sig.ed25519
  └─────────────────────────────────────┬────────────────────────────────────────────────┘└────┬─────┘
                             base64 encoded signature                                        suffix

Its BFE encoding is 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

5. 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 codeFormat codeData lengthSpecificationIn bfe.json
50ArbitraryPrivate Boxbox1
51ArbitraryPrivate Groupbox2

6. Generic data formats

BFE supports encoding data types with no semantics attached to them. They are merely categorized into formats that represent their data type.

Type codeFormat codeData lengthSpecificationIn bfe.json
60ArbitraryUTF8 Stringstring-UTF8
611 byteBoolean: data byte is 0 for False, 1 for Trueboolean
620 bytesNull pointernil
63ArbitraryAny sequence of bytesany-bytes

7. Identity formats

Identities are distinct from feedIds in that they are not a key bound to a single feed/ device, and they are never used for signing of messages.

Type codeFormat codeData lengthSpecificationIn bfe.json
7032Private Group PO boxpo-box
7132Private Groupgroup