CREATE
The CREATE packet is sent when a user wants to create a new bucket on a server. The server reacts by creating a bucket which contains 65,536 empty indexes, called slots. When creating a bucket, the creator can set bucket permissions (read, append, write) for both “private” and “public” mode. A permission in public mode only requires the bucket id to perform an action. When set to private mode the server also requires the bucket key. Besides creating, it is also possible to subscribe directly to updates on the whole bucket or to a specific range of slots.
Request
Figure A: Create request byte-map (header and body)
The CREATE request (see Figure A) includes a header. This header contains one field: the bucket id. In this bucket id are also the permissions stored and the lifetime of the bucket in days. See Bucket id for more info. The body contains two optional fields:
- Slot range start (2 bytes, optional): the (zero-based) index of the slot (uint-16) in the bucket to start subscribing to. For instance, you want to subscribe from slot 10 and up you provide “9” and leave slot range end empty.
- Slot range end (2 bytes, optional): the (zero-based) index of the slot (uint-16) in the bucket to subscribe until. For instance, you want to subscribe from slot 5 until 10, you provide “4” to slot range start and “9” to this field.
It is possible to only provide the start slot (subscribe from slot n and up), both slots (subscribe to range of slots) or none by leaving both fields out (subscribe to full bucket).
The CREATE packet request has two flags:
- #6: Also subscribe to the bucket (with optional provided range)
- #7: Don’t persist bucket, but only store bucket in RAM
This first flag must be set if you want to subscribe to the bucket. If you provide a range but don’t set this subscribe flag, the server will not subscribe you.
The second flag could be set if you don’t want the server to store your bucket on the disk for faster access. This is only smart if you want to stream data via the protocol, else using RAM buckets is not recommended because the data won’t persist and your bucket will be lost after a server restart.
Response
Figure B: Create response byte-map
To keep it easy for you, the create response is empty.
You might encounter the following error codes:
- 4 (authentication failed): if no authentication data provided
- 41 (bucket already exists): if ID is already in use
Bucket id and key
The bucket id is used to indicate a bucket on the server and in the CREATE request to set some settings on the bucket (permissions and lifetime). The bucket key is used to perform private or secured operations on the bucket (which is determined by the permissions).
Bucket id
Figure C: Bucket-id byte-map
The bucket id is a 16-byte random identifier that is used to locate a bucket on the server and manage permissions (see Figure C). The bucket id is created the following way:
- Create 16 random bytes.
- Set the bucket lifetime (uint-8) in days (0 for infinite) on the 15th byte.
- Set the following permission flags on the last 6 bits on the 16th byte (NOT zero indexed):
| Bit | Permission |
|---|---|
| 3th | Allow public read |
| 4th | Allow public write (update message at index) |
| 5th | Allow public append (add message to bucket) |
| 6th | Allow private write |
| 7th | Allow private append |
| 8th | Allow the bucket to be deleted |
Private read is always allowed. The 8th bit is set if you want to allow the bucket to be deleted. If this flag is not set, the bucket can only be wiped but not be deleted from the server.
Bucket key
The 32-byte bucket key is not sent over the network, to increase safety and make the protocol more lightweight. However, both the client and the server have to know the key for authentication. So we generate a shared secret using HKDF-SHA256, the session key (from the CONNECT process), the bucket id and the client counter (as uint-16 2 bytes).
Bucket key = HKDF(key: session key, info: concat(bucket id, client counter), salt: nil)
The bucket key is stored and used for authentication.
Process and flow
Figure D: Create process flow
The CREATE process (see Figure D) works as follows:
- The user generates the bucket id and sets the lifetime and the permission flags
- The client sends the CREATE packet to the server
- The server checks and verifies if the ID is not taken and the authentication is correct. If so, the server creates the bucket
- If the bucket id is already taken the server sends error code #41.
- The server subscribes the user to the bucket if flag #6 is set and optionally to a specific range
- The server sends the empty CREATE response.
← Back to Home - To Transport - Prev: CONNECT packet - Next: PUT packet →