Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

name changes to types/format #12

Merged
merged 10 commits into from
Aug 15, 2021
Merged

name changes to types/format #12

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
39d3bac
name changes to types/format
mixmix Aug 11, 2021
f7cd8bd
review changes (to be squashed)
mixmix Aug 12, 2021
2304c30
add pobox diffie-hellman key type
mixmix Aug 12, 2021
aaa12ab
add identity type, with po-box format
mixmix Aug 12, 2021
3636fe2
Merge pull request #15 from ssb-ngi-pointer/identity
mixmix Aug 13, 2021
883b59c
Merge pull request #14 from ssb-ngi-pointer/po-box-key
mixmix Aug 13, 2021
bbb9448
Update README.md
mixmix Aug 13, 2021
576e5ef
new column in readme.md tables, for bfe.json parity
staltz Aug 13, 2021
65a7633
Merge pull request #18 from ssb-ngi-pointer/third-col
staltz Aug 14, 2021
e09bb27
rename key > encryption key
mixmix Aug 15, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
99 changes: 52 additions & 47 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,29 +15,29 @@ as **T-F-D**:
## Types

| Type code | Referencing |
| ----------- | ------------------ |
| 0 | Peer ID |
| 1 | Message ID |
| 2 | Blob ID |
| 3 | Diffie-Hellman key |
| 4 | Signature |
| 5 | Encrypted data |
| 6 | Generic data |

### Peer ID formats

A peer ID TFD represents the public portion of a cryptographic keypair used to
|:-----------:| ------------------ |
| 0 | feed |
| 1 | msg |
| 2 | blob |
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would be nice to preserve what was before, i.e. uppercase. Otherwise it feels like it's undoing what I did here 11f7d16

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was following the principle of keeping the string the new ad the steering names in the bfe.json
So that people using NAMED_TYPES can just look at this table and type it without having to guess the case, spaces, hyphens

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So that people using NAMED_TYPES can just look at this table and type it without having to guess the case, spaces, hyphens

There is bfe.json for that.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah I'm i at what you mean. I think i was being paranoid expecting people to get confused. But if you think it's fine I'm happy for readme to be more human descriptive

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh, you know what? We could have a third column that reflects the name used in bfe.json

| 3 | key |
| 4 | signature |
| 5 | encrypted |
| 6 | generic |

### 0. Feed ID formats

A feed 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 code | Format code | Data length | Format name | Specification |
|-----------|-------------|-------------|-----------------|------------------|
| 0 | 0 | 32 bytes | Classic | [classic] |
| 0 | 1 | 32 bytes | Gabby Grove | [gabby grove] |
| 0 | 2 | 32 bytes | Bamboo | [bamboo] |
| 0 | 3 | 32 bytes | Bendy Butt | [bendy butt] |
| 0 | 4 | 32 bytes | Fusion Identity | [fusionidentity] |
|:---------:|:-----------:|-------------|-----------------|------------------|
| 0 | 0 | 32 bytes | classic | [classic] |
| 0 | 1 | 32 bytes | gabby-grove | [gabby grove] |
| 0 | 2 | 32 bytes | bamboo | [bamboo] |
| 0 | 3 | 32 bytes | bendy-butt | [bendy butt] |
| 0 | 4 | 32 bytes | fusion-identity | [fusionidentity] |

#### Example

Expand All @@ -58,19 +58,19 @@ type │ data
format
```

### Message ID formats
### 1. Msg 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 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 | 64 bytes | Bamboo | [bamboo] |
| 1 | 4 | 32 bytes | Bendy Butt | [bendy butt] |
|:---------:|:-----------:|-------------|---------------|-----------------|
| 1 | 0 | 32 bytes | classic | [classic] |
| 1 | 1 | 32 bytes | gabby-grove | [gabby grove] |
| 1 | 2 | 32 bytes | cloaked | [private group] |
| 1 | 3 | 64 bytes | bamboo | [bamboo] |
| 1 | 4 | 32 bytes | bendy-butt | [bendy butt] |

#### Example

Expand All @@ -91,13 +91,13 @@ type │ data
format
```

### Blob ID formats
### 2. Blob ID formats

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

| Type code | Format code | Data length | Format name | Specification |
|-----------|-------------|-------------|-------------|---------------|
| 2 | 0 | 32 bytes | Classic | [classic] |
|:---------:|:-----------:|-------------|-------------|---------------|
| 2 | 0 | 32 bytes | classic | [classic] |

#### Example

Expand All @@ -118,17 +118,21 @@ type │ data
format
```

### Diffie-Hellman formats
### 3. Encryption Key formats

| Type code | Format code | Data length | Format name | Specification |
|-----------|-------------|-------------|-------------|---------------|
| 3 | 0 | 32 bytes | curve25519 | |
keys used for encryption

| Type code | Format code | Data length | Format name | Specification |
|:---------:|:-----------:|-------------|----------------|--------------------|
| 3 | 0 | 32 bytes | box2-dm-dh | [private group dm] |


### 4. Signature formats

### Signature formats
| Type code | Format code | Data length | Format name | specification |
|:---------:|:-----------:|-------------|-----------------|---------------|
| 4 | 0 | 64 bytes | msg-ed25519 | |

| Type code | Format code | Data length | Format name | specification |
|-----------|-------------|-------------|-------------|---------------|
| 4 | 0 | 64 bytes | ed25519 | |

#### Example

Expand All @@ -149,34 +153,35 @@ type │ data
format
```

### Encrypted data formats
### 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 code | Format code | Data length | Format name | Specification |
|-----------|-------------|-------------|-------------|-----------------|
| 5 | 0 | Arbitrary | box | [private box] |
| 5 | 1 | Arbitrary | box2 | [envelope spec] |
|:---------:|:-----------:|-------------|-------------|-----------------|
| 5 | 0 | Arbitrary | box1 | [private box] |
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This one still confuses me, which one is it, box1 or box? I honestly don't know. I know that once code broke everywhere because we were using box1 and it had to be box. But I think (??) ssb-tribes uses box1.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ssb tribes uses box2
The original is box, but since the advent of box2 we talked about box saying "box1"... but the suffix is the OG box

At least I think that's how it went down

| 5 | 1 | Arbitrary | box2 | [private group] |

### Generic data formats
### 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 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] |
| 6 | 3 | Arbitrary | Arbitrary bytes | N/A |
|:---------:|:-----------:|-------------|-------------|-------------------------------|
| 6 | 0 | Arbitrary | string-UTF8 | [UTF8] |
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would appreciate if this is reverted.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please respond to my values /proposals
Specifically, I don't want spaces in the name because it makes uris have to have some rule for dealing with them (or you could propose one)

Copy link
Member

@staltz staltz Aug 13, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The response to values/proposals is that this markdown document is for humans to read, so let's use formal English, while the json is for computers to parse. In the markdown we should be trying to explain to people what this is, and this table doesn't look like it's explaining, looks like it's stating raw data.

As for URIs, we're not going to have SSB URIs for these Generic data formats, so I don't understand what's the need for the hyphen.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agree about ssb uri for generic types. I reckon that can be reverted happily then

| 6 | 1 | 1 byte | boolean | Data byte is 0 for False, 1 for True |
| 6 | 2 | 0 bytes | nil | [null pointer] |
| 6 | 3 | Arbitrary | any-bytes | N/A |
mixmix marked this conversation as resolved.
Show resolved Hide resolved

[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
[private group]: https://github.com/ssbc/private-group-spec/tree/master/encryption
[private group dm]: https://github.com/ssbc/private-group-spec/tree/master/direct-messages
[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
Expand Down
32 changes: 16 additions & 16 deletions bfe.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,45 +4,45 @@
"type": "feed",
"sigil": "@",
"formats": [
{ "code": 0, "format": "ssb/classic", "data_length": 32, "suffix": ".ed25519" },
{ "code": 1, "format": "ssb/gabby-grove", "data_length": 32, "suffix": ".ggfeed-v1" },
{ "code": 2, "format": "bamboo", "data_length": 32, "suffix": ".bamboo" },
{ "code": 3, "format": "ssb/bendy-butt", "data_length": 32, "suffix": ".bbfeed-v1" },
{ "code": 4, "format": "ssb/fusion-identity", "data_length": 32, "suffix": ".fusion-v1" }
{ "code": 0, "format": "classic", "data_length": 32, "suffix": ".ed25519" },
{ "code": 1, "format": "gabby-grove", "data_length": 32, "suffix": ".ggfeed-v1" },
{ "code": 2, "format": "bamboo", "data_length": 32, "suffix": ".bamboo" },
{ "code": 3, "format": "bendy-butt", "data_length": 32, "suffix": ".bbfeed-v1" },
{ "code": 4, "format": "fusion-identity", "data_length": 32, "suffix": ".fusion-v1" }
]
},
{
"code": 1,
"type": "msg",
"sigil": "%",
"formats": [
{ "code": 0, "format": "ssb/classic", "data_length": 32, "suffix": ".sha256" },
{ "code": 1, "format": "ssb/gabby-grove", "data_length": 32, "suffix": ".ggmsg-v1" },
{ "code": 2, "format": "cloaked msg", "data_length": 32, "suffix": ".cloaked" },
{ "code": 3, "format": "bamboo", "data_length": 64, "suffix": ".bamboo" },
{ "code": 4, "format": "ssb/bendy-butt", "data_length": 32, "suffix": ".bbmsg-v1" }
{ "code": 0, "format": "classic", "data_length": 32, "suffix": ".sha256" },
{ "code": 1, "format": "gabby-grove", "data_length": 32, "suffix": ".ggmsg-v1" },
{ "code": 2, "format": "cloaked", "data_length": 32, "suffix": ".cloaked" },
{ "code": 3, "format": "bamboo", "data_length": 64, "suffix": ".bamboo" },
{ "code": 4, "format": "bendy-butt", "data_length": 32, "suffix": ".bbmsg-v1" }
]
},
{
"code": 2,
"type": "blob",
"sigil": "&",
"formats": [
{ "code": 0, "format": "ssb/classic", "data_length": 32, "suffix": ".sha256" }
{ "code": 0, "format": "classic", "data_length": 32, "suffix": ".sha256" }
]
},
{
"code": 3,
"type": "diffie-hellman",
"type": "key",
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe "encryption key" (was that what we agreed on in the meeting? I don't accurately remember)? "key" is a very generic word.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Correct but in the types key is only ever going to mean a key for unlocking.

See also "no spaces / short words for ssb uri"

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This PR then automatically means you're proposing the SSB URI ssb:keys/box2-dm-dh/ and I believe ssb:keys/ is going to confuse a lot of people on what it means (given the existence of ssb-keys). Why not ssb:encryption-keys/box2-dm-dh ?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Mainly because it's hella long, and I wasn't to save my bytes!

I'm up for something different to reduce confusion. Couldn't think of anything right though. Maybe emoji? Joking

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's not prohibitively long. Remember SSB URIs are for human readability (while still computer parse-able), and we have other long SSB URIs such as ssb:experimental?action=claim-http-invite&.....

"formats": [
{ "code": 0, "format": "curve25519", "data_length": 32, "key_length": 32 }
{ "code": 0, "format": "box2-dm-dh", "data_length": 32, "key_length": 32 }
]
},
{
"code": 4,
"type": "signature",
"formats": [
{ "code": 0, "format": "ed25519", "data_length": 64, "signature_length": 64, "suffix": ".sig.ed25519" }
{ "code": 0, "format": "msg-ed25519", "data_length": 64, "signature_length": 64, "suffix": ".sig.ed25519" }
]
},
{
Expand All @@ -57,10 +57,10 @@
"code": 6,
"type": "generic",
"formats": [
{ "code": 0, "format": "UTF8 string" },
{ "code": 0, "format": "string-UTF8" },
{ "code": 1, "format": "boolean" },
{ "code": 2, "format": "nil" },
{ "code": 3, "format": "arbitrary bytes" }
{ "code": 3, "format": "any-bytes" }
]
}
]