Home

Flow

New user comes online

1. User Bob joins system via pairing. Bob subscribes to his keyTopicId and groupTopicId.
2. As part of pairing process, other users encrypt symmetric keys for group topics to Bob's public key.
3. Bob pulls all the symmetric keys from his keyTopic and decrypts the keys.
4. Bob pulls all of the topicIds from groupTopic.
5. Bob subscribes to all the new topics from the previous step.
6. Bob gets all the events from the new topics and decrypts their contents with the associated symmetric keys.
7. Bob is now up to date and can continue processing and publishing events.

Producer creates a new topic

1. Get unique ids from Merrimack for topicId, keyId.
2. Generate secret key.
3. Publish secret key to all consumers' keyTopics, using the EncryptedKeyEvent.
4. Publish the new topic to the groupTopic, using NewTopicEvent.
5. Start publishing events to the topic.

Structure

topicId

• Producers get a unique id from Merrimack for each topicId.
• Users will have to know the specific topicIds.
• Each user has its own keyTopicId which is communicated to other users during pairing. All new encrypted keys for the user are sent to this topic.
• Each group of users has its own groupTopicId. This is where users in the group can learn about new topics.
• Producers get a unique id from Merrimack for each symmetric key they generate, for encrypting records.

events

Each event record is a protocol buffer structure made up of an unencrypted header and an encrypted body. The message body can be a Node.js buffer that's transparent to Powwow or a special Powwow body, as we define later on.

message Header {
  required uint64 eventId = 1;
  required uint64 topicId = 2;
  optional uint64 keyId = 3;
}

enum EventBodyType {
  PUBLIC_KEY_REC = 0;
}

message UnencryptedEvent {
  required Header header = 1;
  required EventBodyType eventBodyType = 2;
  required bytes body = 3;
}

message EncryptedEvent {
  required Header header = 1;
  optional bytes encryptedBody = 2;
}

keys

A producer can start encrypting events with a new symmetric key at any time. It must publish encrypted versions of the key to all consumers. The key is encrypted to the public key of each consumer.

enum KeyType {
  NACL_SECRETBOX = 0;
}

message KeyRec {
  required uint64 keyId = 1;
  required KeyType keyType = 2;
  required bytes key = 3;
}

special powwow topics

userTopic

This is where new users announce themselves. The PublicKeyRec is sent as an UnencryptedEvent.

The UserRole enum is defined by the application using Powwow.

message PublicKeyRec {
  required uint64 userId = 1;
  required uint64 publicKeyId = 2;
  required uint64 keyTopicId = 3;
  required PublicKeyType publicKeyType = 4;
  required bytes publicKey = 5;
  required UserRole userRole = 6;
  optional string userName = 7;
}

The rest of these all get encrypted in the event body and can't be seen by the server

clusterTopic

This is where users announce new topics of interest to the cluster. There is one of these topics for each cluster. There will probably be more stuff to help users figure out what topics to listen on.

Subscribing to this topic means the user has joined the cluster.

enum TopicType {
  POWWOW_KEY_TOPIC = 0;
  POWWOW_GROUP_TOPIC = 1;
  OTHER = 2;
}

message NewTopicEvent {
  required uint64 topicId = 1;
  required string name = 2;
  optional TopicType topicType = 3;
}

Encrypted key event

A producer that creates a new symmetric encrypting key sends this event to each consumer's keyTopic.

message EncryptedKeyEvent {
  required uint64 publicKeyId = 1;
  required bytes encryptedKeyRec = 2;
}

Inbox

Each user has its own inboxTopic, where it can receive private messages from other users.