Zax 2.0 File Commands

Overall protocol of file exchange from Alice to Bob is outlined here

Available commands

• startFileUpload
• uploadFileChunk
• fileStatus
• downloadFileChunk
• deleteFile

startFileUpload

Ask Zax to start a new upload session, and get a unique file identifier required to upload file chunks.

Request Body

Parameter	Description	Example	Required
to	base64(hpk_to) Use in Glow lib: Recipient's name (should already be in the user's keyring)	"KgJjZGvlfha6YER5Im+a6 Wfi0yAl3yenyzcxjhpMh8I" 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'}	✅

Metadata contents

Object with the following properties is encrypted hpk_from ▶ hpk_to with public key, to allow recipient to access the metadata. This data is not accessible to the relay since the relay never has access to the hpk_to private key.

Parameter	Value	Example	Required
name	Original filename with extension, as used on the user's file system. May include the 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	'qzMFuWUp0ot4bx5z4QJKq fk2CJimN7XqbOilOybrUv8='	✅
md5	MD5 hash of the original file. May be used by the recipient to verify the transfer after the file is decoded	'5c03b7b871a4070 572e73de9236bfd0b'
created	File created timestamp	1492992000
modified	File modified timestamp	1493121600
attrs	chmod-compatible file mode	'0777'

Response Body

Parameter	Value
uploadID	Unique ID 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 any associations between the issued uploadID and files stored by relay.
max_chunk_size	Maximum size of encrypted chunk (in bytes) that the current relay may handle
storage_token	This message's (startFileUpload) Zax token. It can be used with the standard Zax messageStatus and delete commands to check on that message's status in Zax storage until deleted by the recipient (with delete) or expiration. It represents a message with metadata about the upcoming file, not the file itself. The Glow library Mailbox.relay_msg_status(storage_token) can be used to monitor the status of that message.

Errors

Errors are communicated back via HTTP codes 400, 401 and 500. No error details are given to the client, relay owner can look into relay logs for specific and detail information about every error. Set log level to INFO to see every detail of relay operations in log. 400 and 401 errors generally indicate error in given parameters or operations. 500 errors indicate some failure of relay backend system (such as redis going offline) and might indicate relay should not be used in the near term.

uploadFileChunk

Transfer the encrypted chunk of the file to the Zax relay.

Once the client obtains an uploadID from the startFileUpload response, it should split the binary into chunks of the same size. The size of the last chunk may be less than all of others', if it's not evenly divisible. Then the client encrypts them with NaCl Secretbox and sends the chunks sequentially to the server. The maximum size of an encoded chunk is determined by maxChunkSize which the relay declares in response to startFileUpload.

If a file is small enough to fit into a single chunk, it's just a particular case: only one request is needed to upload it. The part param should be equal 0, and total_parts == 1.

Request Body

Parameter	Description	Example	Required
uploadID	Unique identifier of the file being uploaded, recognized by the relay	'C0mtKFFIy8xJVUgu Sk0sSU1RSMsvUnDPy'	✅
part	Sequential number of the file chunk, starting with 0	2	✅
nonce	Secretbox nonce in Base64 format	'AAAAAFkDa8dMC0tY iS9PR+d38Puh4yAq'	✅
last_chunk	Present when the 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 the POST	Secretbox encoded chunk in Base64 format. The 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 transferred outside of the usual Zax encrypted command. Instead it's sent as an extra line of the Zax command POST.	'IZIyZTXIRnq8gTn xYrOxm25Tutva...'	✅

Response Body

Parameter	Value
status	OK or one of the errors

uploadFileChunk Errors

• HTTP Method Not Allowed: The current relay does not support operations with files
• One or more params in the request body are missing or invalid
• Unknown uploadID
• No free space is available on the Zax relay

fileStatus

Get the 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.

Request Body

Parameter	Value	Example	Required
uploadID	Unique identifier of the file	'C0mtKFFIy8xJVUguSk0sSU1RSMsvUnDPy'	✅

Response Body

Parameter	Description	Example
status	One of the statuses	'COMPLETE'
file_size	Size announced during the startFileUpload command	20100
bytes_stored	Total bytes in all chunks stored so far by the relay for this file	5000
total_chunks	If the status is COMPLETE (e.g. client has sent a chunk with lastChunk flag), this field will be present with the total number of chunks received	5

fileStatus Statuses

Status code	Description
NOT_FOUND	File does not exist or has already been deleted.
START	startFileUpload request received by Zax, and the given uploadID is valid.
UPLOADING	At least one chunk was successfully uploaded, but not all of them.
COMPLETE	File is fully stored on the relay as it has received a file chunk marked with lastChunk.

downloadFileChunk

Download the encrypted file chunk from the Zax relay. The total number of chunks can be retrieved via a fileStatus request, so to restore, the file recipient has to download, decrypt, and merge all of the chunks.

Request Body

Parameter	Value	Example	Required
uploadID	Unique identifier of the file, received from file info message in hpk_to mailbox	'C0mtKFFIy8xJVUgu Sk0sSU1RSMsvUnDPy'	✅
part	Sequential number of file chunk, starting with 0	2	✅

Response Body

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 the startFileUpload call from hpk_from ▶ hpk_to, and then used to decrypt all of the chunks. The relay never sees this key explicitly. The cipher text of the file chunk is sent outside of the encrypted Zax command block (since it's already encrypted with the symmetric key) and sent instead as an extra last line of the command POST in base64.

Errors

• HTTP Method Not Allowed: The current relay does not support operations with files
• One or more params in the request body are missing or invalid
• Unknown uploadID

deleteFile

Delete a file from the relay (or all chunks uploaded so far, if the upload was not completed). Can be called by either the sender or recipient.

Request Body

Parameter	Description	Example	Required
uploadID	Unique identifier of the file	'C0mtKFFIy8xJVUguSk0sSU1RSMsvUnDPy'	✅

Response Body

Parameter	Description
status	OK or NOT_FOUND if the file does not exist (or has already been deleted)