-
Notifications
You must be signed in to change notification settings - Fork 13
Zax 2.0 File Commands
Ask Zax to start a new upload session, and get an unique file identifier required to upload file chunks.
| Parameter | Description | Example | Required |
|---|---|---|---|
to |
base64(hpk_to)Use in Glow lib: Recipient's name (should be already in the user's keyring) |
"KgJjZGvlfha6YER5Im+a6Wfi0yAl3yenyzcxjhpMh8I" or 'Alice'
|
✅ |
file_size |
Size in bytes of the original file (not encrypted yet) | 34524 |
✅ |
metadata |
Cryptobox-encrypted metadata of the file. JSON object consists of 2 fields: nonce and ctext. ctext is encrypted hpk_from ▶ hpk_to with nonce
|
{ ctext: 'qT7U....e9uFuO==', nonce: 'a1ec978b...8978k'}
|
✅ |
Object with the following properties is encrypted hpk_from ▶ hpk_to with public key, to allow recipient access the metadata. This data is not accessible to relay since relay never has access to hpk_to private key.
| Parameter | Value | Example | Required |
|---|---|---|---|
name |
Original filename with extension, as used on user's file system. May include relative path | 'Documents/New/Bob.docx' |
✅ |
orig_size |
Size in bytes of the original file (not encrypted yet) | 34524 |
✅ |
skey |
Symmetric key, used to encrypt the file using NaCl secret_box. Recipient will use the same key to decrypt all chunks |
'qzMFuWUp0ot4bx5z4QJKqfk2CJimN7XqbOilOybrUv8='
|
✅ |
md5 |
MD5 hash of the original file. May be used by recipient to verify the transfer after the file is decoded |
'5c03b7b871a4070572e73de9236bfd0b'
|
|
created |
File created timestamp | 1492992000 |
|
modified |
File modified timestamp | 1493121600 |
|
attrs |
chmod-compatible file mode |
'0777' |
| Parameter | Value |
|---|---|
uploadID |
Unique ID needed used in subsequent requests to upload by hpk_from and download by hpk_to file chunks. Specific to the current relay and file metadata. Deleting secret_seed in shared/uploads will permanently destroy associations between issued uploadID and files stored by relay. |
max_chunk_size |
Maximum size of encrypted chunk (in bytes) that current relay may handle |
storage_token |
This message (startFileUpload) Zax token. It can be used with statadard Zax messageStatus and delete commands to check on that message status in Zax storage until deleted by recipient (with delete) or expiration. It represents a message with metadata about the upcoming file, not the file itself. Glow library Mailbox.relay_msg_status(storage_token) can be used to monitor status of that message. |
- HTTP Method Not Allowed: Current relay does not support operations with files
- One or more params in request body are missing or invalid
- Glow: Guest not found in the keyring
- No free space is available on Zax relay
Transfer the encrypted chunk of the file to Zax relay.
Once client obtains uploadID from startFileUpload response, it should split the binary into the chunks of the same size. Size of the last chunk may be less than of all others', if it's not evenly divisible. Then client encrypts them with NaCl Secretbox and sends chunks sequentially to the server. Maximum size of encoded chunk is determined by maxChunkSize relay declared in startUpload response.
If file is small enough to fit the single chunk, it's just a particular case: only one request is needed to upload it. part param should be equal 0, and total_parts == 1.
| Parameter | Description | Example | Required |
|---|---|---|---|
uploadID |
Unique identifier of the file being uploaded, recognized by relay |
'C0mtKFFIy8xJVUguSk0sSU1RSMsvUnDPy'
|
✅ |
part |
Sequential number of file chunk, starting with 0 | 2 |
✅ |
nonce |
Secretbox nonce in Base64 format |
'AAAAAFkDa8dMC0tYiS9PR+d38Puh4yAq'
|
✅ |
last_chunk |
Present when client sends the last chunk of given file. Upon seeing this flag, Zax will mark the status of this file as COMPLETE
|
true |
|
Last line of POST
|
Secretbox encoded chunk in Base64 format. Secretbox key for this encryption is passed previously inside cyphertext of startFileUpload call from hpk_from ▶ hpk_to. The encrypted contents of file chunk is transfered outside of usual Zax encrypted command. Instead its sent as extra line of zax command POST. |
'IZIyZTXIRnq8gTnxYrOxm25Tutva...'
|
✅ |
| Parameter | Value |
|---|---|
status |
OK or one of the errors
|
- HTTP Method Not Allowed: Current relay does not support operations with files
- One or more params in request body are missing or invalid
- Unknown
uploadID - No free space is available on Zax relay
Get status of the file by its relay-specific uploadID. Uploader can call it to verify the correct transfer, and downloader can check if the file exists and retrieve the number of chunks.
| Parameter | Value | Example | Required |
|---|---|---|---|
uploadID |
Unique identifier of the file | 'C0mtKFFIy8xJVUguSk0sSU1RSMsvUnDPy' |
✅ |
| Parameter | Description | Example |
|---|---|---|
status |
One of the statuses | 'COMPLETE' |
file_size |
Size announced during startFileUpload command |
20100 |
bytes_stored |
Total bytes in all chunks stored so far by the relay for this file | 5000 |
total_chunks |
If status is COMPLETE (e.g. client has sent a chunk with lastChunk flag), this field will be present with total number of chunks received |
5 |
| Status code | Description |
|---|---|
NOT_FOUND |
File does not exist or has been already deleted. |
START |
startFileUpload request received by Zax, and given uploadID is valid. |
UPLOADING |
At least one chunk was successfully uploaded, but not all of them. |
COMPLETE |
File is fully stored on relay because it received file chunk marked with lastChunk. |
Download the encrypted file chunk from Zax relay. Total number of chunks can be retrieved via fileStatus request, so to restore the file recipient has to download, decrypt and merge all of them.
| Parameter | Value | Example | Required |
|---|---|---|---|
uploadID |
Unique identifier of the file, received from file info message in hpk_to mailbox |
'C0mtKFFIy8xJVUguSk0sSU1RSMsvUnDPy'
|
✅ |
part |
Sequential number of file chunk, starting with 0 | 2 |
✅ |
| Parameter | Value |
|---|---|
nonce |
Secretbox nonce in Base64 format |
Last line of POST
|
Secretbox encoded chunk in Base64 format. Secretbox key to decrypt the chunk is passed previously inside cyphertext of startFileUpload call from hpk_from ▶ hpk_to, and then used to decrypt all the chunks. Relay never sees this key explicitly. The cipher text of file chunk is sent outside of encrypted Zax command block (since its already encrypted with symmetric key) and sent instead as extra last line of command POST in base64. |
- HTTP Method Not Allowed: Current relay does not support operations with files
- One or more params in request body are missing or invalid
- Unknown
fileID
Delete a file from the relay (or all chunks uploaded so far, if upload was not completed). Can be called by either sender or recipient.
| Parameter | Description | Example | Required |
|---|---|---|---|
uploadID |
Unique identifier of the file | 'C0mtKFFIy8xJVUguSk0sSU1RSMsvUnDPy' |
✅ |
| Parameter | Description |
|---|---|
status |
OK or NOT_FOUND if file does not exist (or has been already deleted) |