MEGA software development kit

Preface

What is the MEGA SDK good for?

The MEGA SDK consists of code and documentation that enables you to make use of MEGA’s API functionality at a comfortably high level of abstraction. Its core component — a code module called client access engine — maintains a current copy of the user’s account in memory (which includes all relevant files, folders, contacts and shares), accepts commands from the application and notifies the application of command results and other updates through callbacks.

How do I use the MEGA client access engine?

The MEGA client access engine comes as a set of C++ classes and interfaces. If you are using C++, you can simply add them to your project. You then instantiate the MegaClient class (which holds the session state) and pass it an instance of your implementation of the HttpIO interface (which handles network requests and blocking) and MegaApp (through which you receive the engine’s callbacks).

The core code is reasonably platform independent (if you encounter any issues with your specific C++ compiler environment, please let us know). To illustrate practical usage, a sample application (a basic ftp-style interactive console client) is included.

Why do you provide a code module rather than documenting the API interface in sufficient detail for me to implement it myself?

• Complexity/efficiency — Since all of MEGA’s crypto logic runs on the client side, you’d be looking at a project exceeding 5,000 lines of code. And, as natural language is rather inefficient when it comes to specifying algorithms, the documentation would be similarly voluminous.
• Consistency/interoperability — Ambiguities in the specification or its imprecise interpretation would inevitably lead to undesired behavioural differences between implementations.

Thanks, but why C++? I am using C, Objective C, C#, Java, Scala, Python, Ruby, Perl, PHP, VB…

The requirement to integrate with projects that compile to native code rules out all languages that rely on specific interpreters or runtime environments. C, being the “lingua franca” of nearly all modern systems, would have been the obvious choice, but the code compactness and readability benefits provided by C++’s syntactic sugar and template library are well worth the minor additional integration overhead. We will work with interested developers to add MEGA support to their preferred environments by way of native code modules/extensions (rather than by porting the functionality to the target language itself). Please contact us at developers@mega.nz if you are willing and able to contribute to a particular integration effort.

Programming model

Interaction

The application submits requests to the client access engine through nonblocking calls to methods of the MegaClient object and signals events to the application by invoking methods of an object of its implementation of the MegaApp interface.

Files and folders

Files and folders are represented by Node objects and referenced by node handles. Nodes point to parent nodes, forming trees. Trees have exactly one root node (circular linkage is not allowed). Node updates (caused by the session’s own actions, other sessions of the same account or other accounts, e.g. through activity in a shared folder) are notified in real time through a callback specifying the affected nodes. Deleted nodes are first notified with their removed flag set before being purged to give the application an opportunity to remove them from the UI view.

There are at least three node trees per account: Root, incoming and rubbish. Additional trees can originate from other users as shared folders.

Users and contacts

Users are referenced by their user handle and/or their primary e-mail address. The engine maintains a User object for every user account that has appeared in the context of the current session: As a contact or merely as the owner of a filesystem node. A visibility flag turns a user into a contact if set.

User attributes can be used to store credentials such as avatar pictures, address, date of birth etc. It is recommended to store application-private user credentials AES-CBC encrypted.

Asynchronous completion

All engine methods are nonblocking — waiting for network communication to complete is not an option. Instead, they merely initiate the desired action, the outcome of which is eventually signalled through a callback. The application should be robust against such callbacks arriving after a long time (i.e., many seconds). Failed requests (e.g. due to network issues) are retried automatically with exponential backoff. The application receives notification of this through a callback and should inform the user accordingly, along with a UI element to manually initiate a retry.

Three types of operation are subject to acceleration by a mechanism called « speculative instant completion »: Node attribute updates, moves and deletions. As these merely receive a highly predictable « OK » or « failure » response from the API, there is some benefit in immediately updating the local nodes and reloading the session state in the rare event of an inconsistency. The engine loosely protects them with an access check that is following the same semantics as the authoritative check on the API server side.

Concurrency considerations

Shared access to a resource (writable nodes accessible to the user’s account) based on a potentially outdated (due to network latency) view is naturally prone to race conditions, leading to inconsistencies when two parties make conflicting updates within the latency window. The engine contains heuristics to detect these conflicts and will ask the application to discard and reload its view if needed (the user should be informed accordingly).

Event processing and threading

Due to its nonblocking nature, the MEGA client access engine integrates extremely well with single-threaded applications (although on platforms without a nonblocking DNS lookup facility, you may not get around using a worker thread for name resolution). If you, however, prefer to use multiple threads, you are welcome to do so – as long as you ensure that no two threads get to enter the engine or access its data structures at the same time.

Running the engine

There are three approaches to integrating the engine with the application. The goal is to have the engine get the CPU (through MegaClient’s exec() method) swiftly whenever one of its wakeup triggers fires:

• block inside the engine’s own blocking callback (which waits for socket I/O and timeouts) and include the application’s own wakeup triggers
• record the engine’s wakeup triggers and include them in the application’s existing blocking facility
• dedicate a worker thread to the MEGA engine and interact with the application through e.g. a bidirectional message queue (inefficient, but the only option if, for some reason, you cannot modify the application’s event processing)

File name conflicts

Applications must be prepared to deal with file and folder name clashes. In many scenarios, this is trivial – the user sees all copies and makes the decision which file he is interested in, mostly based on its timestamp. Some applications, however, map a MEGA node tree to a resource that uses file paths as unique keys, e.g. filesystems. In this case, we recommend that only the most recent node is used.

Filename characters that are not allowed on the host must be urlencoded using %xx. When writing files back to the server, valid urlencoded sequences must be replaced with the encoded character. This has the potential unwanted side effect of mangling filenames that originally contained valid %xx sequences, but this should be rare, and they’ll be unmangled when read back to the local machine.

Namespace management: Node, file and user attributes

We kindly ask all application developers wishing to introduce new node, file or user attributes to coordinate the numbering/naming and formatting conventions with us to maximize cross-application interoperability. Should you elect not to do so, please avoid cluttering the namespaces and prefix the new attribute names with your abbreviated company or application name.

Implementation

Interfaces

The following interfaces need to be implemented by the application:

• FileAccess – File opening/closing/reading/writing
• HttpIO – HTTP requests with SSL support
• PrnGen – Cryptographically strong pseudo-random number generator
• SymmCipher – AES cryptography
• AsymmCipher – RSA cryptography
• MegaApp – callbacks to the application

The SDK provides reference implementations of FileAccess (using POSIX calls), HttpIO (using cURL) and of PrnGen SymmCipher and AsymmCipher (using Crypto++). If you decide to use cURL in your application, please ensure that it was built with c-ares support for asynchronous DNS requests. Some platforms (e.g. MacOS and Fedora) bundle cURL binaries that were compiled with threaded-resolver support – these will not work.

Usage

To access MEGA, an application needs to instantiate three classes:

• its own implementation of the MegaApp interface
• its own implementation of the HttpIO interface
• MegaClient

Then, the application must call MegaClient ’s wait() immediately before or instead of blocking for events itself. If wait() wishes to block, it calls HttpIO ’s waitio() , supplying a timeout. The application can either piggyback its own wakeup criteria onto the socket events/timeout in waitio() , or record the criteria waitio() gets waken up by and include these in its own blocking logic. The supplied SDK example (megaapp.cpp) uses the former approach, adding fileno(stdin) to the select() fd set to process user input in real time.

The application must call MegaClient’s exec() at least once after every wakeup by the waitio() criteria (it doesn’t hurt to call it too often).

Data structures

A MEGA session consists of:

• nodes ( MegaClient::nodes )
• users ( MegaClient::users )
• active file transfers ( MegaClient::ft )
• the root nodes’ handles ( MegaClient::rootnodes )
• the logged in user’s own handle and e-mail address ( MegaClient::me , MegaClient::myemail )

Nodes

A node has the following properties:

• handle (caveat: the application-side handle bit layout is endian-dependent – do not transfer between systems using different CPU architectures!)
• type (file, folder, …)
• its parent (if any)
• its children (if any)
• file size (if file node)
• file attributes (if file node)
• attributes (such as file/folder name)
• crypto key
• creation and modification times
• owner
• share information (share key, outgoing share peers, incoming share properties)
• a generic pointer to private application data
• a removed flag used to notify node deletion

Please refer to the supplied source code for details.

Users

A third-party user is part of the session either because he is in a contact relationship with the session user, or because he owns at least one of the session’s nodes. A user record is also created when a share is added to a previously unregistered e-mail address. Users can be referenced by their handle or by their e-mail address.

User properties:

• handle
• email address (case-insensitive unique key)
• name
• contact visibility
• shared node handles
• public key
• time the user was added as a contact
• user properties

File I/O

File transfers

Multiple concurrent file transfers are supported. It is strongly suggested not to run more than one large upload and one large download in parallel to avoid network congestion (there will be little, if any, speed benefit). A file transfer can aggregate multiple TCP channels (recommended starting point: 4) for greater throughput. File transfers can be aborted at any time by calling MegaClient::tclose() . Significant local network congestion during uploads is common with ADSL uplinks and can be prevented by enabling an automatic or fixed rate limit.

Transfer queueing

Applications that transfer batches of files should do using the engine’s transfer queueing functionality. It uses pipelining (new transfers are dispatched approximately three seconds before the end of the current transfer) to reduce or eliminate the dead time between files. Failed transfers are retried with exponential backoff.

File attributes

Files can have attributes. Only the original creator of a file can update its attributes. All nodes referencing the same encrypted file see the same attributes. Attributes carry a 16-bit type field. The client access engine supports attaching file attributes during or after the upload and their bulk retrieval.

Thumbnails

All applications capable of uploading image files should add thumbnails in the process (remember that there is no way for us to do this on the server side). Thumbnails are stored as type 0 file attributes and should be 120p*120p JPEGs compressed to around 3-4 KB. The sample application supplied with the SDK demonstrates how to do this using the FreeImage library. As the extraction of a thumbnail from a large image can take a considerable amount of time, it is also suggested to perform this in separate worker threads to avoid stalling the application.

Quota enforcement

There are two types of quota limitations an application can encounter during its operation: Storage and bandwidth. MEGA, by policy, is quite generous on both, which means that only a small fraction of your user base will ever run out of quota, but it is essential that if it happens, the situation is handled correctly – the user needs to be informed about the reason for his upload or download failing rather than being left in the dark with what looks like a malfunction.

Storage quota

An upload will be rejected with error EOVERQUOTA if there is not enough storage quota available to complete it. Once the upload has started, it will complete, even if you run out of disk space through other means in the meantime (e.g. by your Pro status expiring). This error will also occur if your application tries to send files to a third-party account without sufficient quota.

Bandwidth quota

A download attempt will be rejected with error EOVERQUOTA if the bandwidth consumption during the past five to six hours plus the residual size of all running downloads plus the size of the file to download would exceed the current per-IP bandwidth limit (if any).

In contrast to uploads, running downloads can be interrupted with an out-of-quota error under certain circumstances, which will trigger a quota_exceeded() callback, and the download will retry automatically until bandwidth quota becomes available.

API access authorization

You can find our other libraries on our general GitHub page. If you would like to use our code commercially in a way which is outside the scope of these licences, please contact us to discuss.

Development process

The release of the C++ SDK is merely a starting point, and it will evolve over time. We’d like to hear from developers actually using it in their applications – if you find bugs, design flaws or other shortcomings, please get in touch at developers@mega.nz. MEGA is hiring, so be prepared to receive an offer if your feedback indicates that you are a bright mind.

A developer forum and source code repository will be made available soon.

Planned future enhancements

Login acceleration

Large MEGA accounts can take a considerable amount of time to load. This is due to the sheer size of the state information that has to be read from the API cluster. There are two ways around this:

• Maintaining the account state in a local persistent database rather than in memory. Upon login, the client would ask the server for the number of operations that have affected the account since the last database update, and then decide whether it is more efficient to wipe the local state and reload, or to continue with the stored state and apply the queued updates to it (in the vast majority of cases, it will be the latter).
• The application initially loads only folder nodes and retrieves file nodes dynamically when they are actually needed.

Allow for existing files to be opened for writing

Currently, files cannot be modified after creation. This limitation will be overcome by using encrypted delta files.

Allow for integrity-checked partial reads

Currently, a file’s integrity is verified only after it was downloaded in full. Chunk MAC verification will enable applications to ensure the integrity of partial reads.

SDK sample client application

Compiling and linking megaclient

To build megaclient , you need the following:

• a POSIX-compliant environment
• a C++ compiler with STL
• libcurl, built with c-ares
• a recent version of FreeImage
• libcrypto++
• libreadline

At this time, the SDK does not come with an autoconf script, so you may have to manually adapt the Makefile to your system.

Using megaclient

Similar to the UNIX ftp command, megaclient displays a prompt and accepts commands to log into a MEGA account or exported folder link, list folder contents, create folders, copy, move and delete files and folders, view inbound and outbound folder shares, establish, modify and delete outbound folder shares, upload and download files, export links to folders and files, import file links, view the account’s status and change its password.

Command reference

login – log into an account or folder link

To log into an account, specify the account’s e-mail address and optionally the password (for which you will be prompted otherwise).

To log into an exported folder link, specify the full link, including the key (prompting for the key has not been implemented yet).

Note that exported folders cannot be written to.

mount – display available filesystem trees

This command takes no parameters and displays the paths of your available filesystem trees (typically / for the main tree, //in for the inbox, //bin for the rubbish bin and email:sharename for inbound shares from user email.

ls – list files and folders

ls lists the contents of the current folder (if given with the qualifier -R , it does so recursively) or the specified path.

Paths can be relative or absolute. Valid absolute paths start with one of the prefixes displayed by the mount command.

File and folder properties are displayed along with their names: File size and available file attributes, or exported folder links and outbound folder shares.

cd – change current working directory

cd changes the current working directory to the specified folder path. If no path is given, it changes to / .

pwd – display current folder

pwd displays the current folder as an absolute path.

lcd – change current local working directory

lcd changes the current local working directory to the specified path.

get – add file(s) to the download queue

get queues the specified file for download. If you specify a folder, all files contained in the folder are queued for download (but not the contents of its subfolders).

put – add file(s) to the upload queue

put queues the specified file for upload. Patterns are supported – put *.jpg will upload all .jpg files present in the current local directory.

getq and putq – list/remove/abort queued transfers

The queued transfers are listed with an index, target path (uploads only) and activity status. To cancel a transfer, specify its index.

mkdir – create folders

mkdir creates an empty subfolder in the specified (or current) folder. Although MEGA permits identical folder names, mkdir fails if the folder already exists.

cp , mv – copy or move, rename files and folders

The specified source path or folder is copied or moved to the destination folder. If the destination indicates a new name in an existing folder, a rename takes place along the way.

rm – delete file or folder

rm deletes the specified file or folder. If the folder contains files or subfolders, these are recursively deleted as well. All affected outbound shares and exported folder links are canceled in the process.

The deletion is final. To take advantage of the rubbish bin functionality, use mv path //bin instead.

share – manage outbound folder shares

share lists, creates, updates or deletes outbound shares on the specified folder. The folder cannot be in an inbound share.

To list the existing shares on a folder, use share path.

To cancel a folder share to a user, use share path email.

To create or modify a folder share, use share path email access.

Supported access levels are: Read-only ( r ), read/write ( rw ) and full ( full ).

export – create or cancel file or folder link

export creates a read-only file or folder link that contains the related encryption key. To cancel an existing link, add the keyword del.

import – import exported file

import adds the file described by the supplied link (importing folder links is currently unsupported) to the current folder.

putbps – set upload speed limit

Uploading through a DSL line can cause significant outbound packet loss. You can limit the send rate by specifying an absolute maximum in bytes per second, auto to have the server figure out your line speed and leave approximately 10% of it idle, or none to transfer at full speed.

It is currently not possible to change the send rate of an active upload. The setting will only affect subsequent uploads.

whoami – display account details

whoami displays various account quota, balances and the session history.

passwd – change account password

passwd prompts for the current password and then asks for the new password and its confirmation. No password quality checking is performed.

retry – immediately retry all pending operations

retry resets all exponential backoff timers.

recon – reconnect

recon tears down all existing server connections. This has no effect on ongoing operations other than causing transfers to take longer due to partially transferred chunks being discarded and having to be resent.

reload – wipe and reload account state

reload purges the local state and forces a full reload from the server. This is useful in response to the detection of a race condition-related inconsistency between the client’s view and the server state.

logout – terminate current session

logout purges all local session state.

debug – toggle debug mode

Debug mode outputs HTTP connection activity and the raw JSON API requests and responses.

Method/callback overview

Hashing a password

Hashes a UTF-8-encoded password and stores the result in the supplied buffer.

Method: error hashpw_key(const char* password, char* hash)

Return codes: API_EARGS in case of invalid UTF-8 encoding

Logging into an account

Initiates a session login based on the user e-mail address (case insensitive) and the corresponding password hash.

Method: void login(const char* email, const char* hash)

Callback: login_result(error e)

Error codes: API_ENOENT : Invalid e-mail address or password, API_EKEY : Private key could not be decrypted

Logging into an exported folder

Method: void folderaccess(const char* node, const char* key)

Callback: none (does not interact with the server, proceed with calling fetchnodes() )

Fetching the session’s nodes and users

Method: void fetchnodes()

Callback: fetchnodes_result(client, error e)

Upon completion, also calls nodes_updated().

Retrieving user account details, quota and history

Method: void getaccountdetails(AccountDetails* result, int storage, int transfer, int pro, int transactions, int purchases, int sessions)

Updates the supplied AccountDetails structure with information on current storage and transfer utilization and quota, Pro status, and the transaction and session history. You can specify which types of information you are interested in by setting the related flag to a non-zero value.

Changing the logged in account’s password

Method: error changepw(const char* currentpwhash, const char* newpwhash)

Callback: changepw_result(error e)

Return code: API_EACCESS if no user session exists.

Updating a node’s attributes (with instant completion)

Method: error setattr(Node* node, const char** newattr)

Return value: API_EACCESS if node not writable.

Callback: setattr_result(handle nodehandle, error e)

The node’s current attributes are pushed to the server. The optional newattr parameter specifies attribute deltas as NULL-terminated sequence of attribute name/attribute C-string pointer pairs. In setattr_result(), nodehandle is the node’s handle.

Moving a node to a new parent folder (with instant completion)

Method: error rename(Node* node, Node* newparent)

Return value: API_EACCESS if node’s parent or newparent are not writable (with full and read/write access, respectively) or the move would be between different user accounts, API_ECIRCULAR if a circular linkage would result.

Callback: rename_result(handle nodehandle, error e)

The node (along with all of its children) is moved to the new parent node, which must be part of the same user account as the node itself. You cannot move a node to its own subtree.

Deleting a node tree (with instant completion)

Method: error unlink(Node* node)

Return value: API_EACCESS if the node’s parent is not writable (with full access).

Callback: unlink_result(handle nodehandle, error e)

The node and all of its subnodes are deleted. The node’s parent must be writable (with full access). Affected outbound shares are canceled.

Transferring files

Uploads and downloads are started with topen() , which returns a transfer descriptor identifying the transfer. Multiple transfers can run in parallel, and each transfer can use multiple TCP connections in parallel. Efficient transfer queueing with pipelining is available. Uploads can be speed-limited using an absolute or a dynamic cap.

Progress information is conveyed through the callback transfer_update(int td, m_off_t bytes, m_off_t size, dstime starttime) , whereby td identifies the transfer, bytes denotes the number of bytes transferred so far, size indicates the total transfer size, and starttime is the time the transfer started.

A running transfer can be aborted at any time by calling tclose(int td) . Failure-indicating callbacks perform the tclose() implicitly. The callback indicating a transient HTTP error, transfer_error(int td, int httpcode, int count) will call tclose() if the application returns a non-zero value.

Uploading

Method: int topen(const char* localfilename, int speedlimit, int connections)

speedlimit – maximum upload speed in bytes/second or -1 for approx. 90% of the line speed

connections – number of parallel connections to use (default: 3)

Return value: transfer descriptor or API_ETOOMANY if all transfer channels are busy, API_ENOENT if file failed to open.

Callback upon completion: transfer_complete(int td, handle uploadhandle, const byte* uploadtoken, const byte* filekey, SymmCipher* filekey)

Callback upon failure: transfer_failed(int td, error e)

Downloading

Method: int topen(handle nodehandle, const byte* key, m_off_t start, m_off_t len, int c)

nodehandle is the handle of the node to download (if key is set, the handle part of the exported file link)

key is the base64-decoded key part of the exported file link if set

start and len can be set to download only a slice of the file (default: 0, -1 for the full file)

c denotes the number of parallel TCP connections that this download should employ.

Return value: transfer descriptor or API_ETOOMANY if all transfer channels are busy, API_ENOENT if local file is not present, API_EACCESS if attempting to download a non-file

Callback upon opening of the file to download: topen_result(int td, string* filename, const char* fa, int pfa)

td identifies the transfer

filename is the name of the file as specified by the node attribute ‘n’

fa are the file attributes available for this file

pfa is a flag that indicates whether the requesting user is allowed to write file attributes (i.e., is the file’s owner)

Callback upon succcessful completion: transfer_complete(int td, chunkmac_map* macs, const char* fn)

td identifies the transfer

macs contains the MAC hash for each file chunk

fn is the filename (UTF-8)

Callback upon failure: transfer_failed(int td, string& filename, error e)

Callback upon reaching the transfer limit: transfer_limit(int td)

Transfer queueing

The engine maintains separate upload and download queues, putq and getq. Transfers are started by pushing transfer objects (classes FilePut and FileGet onto these queues). You no longer need to call topen() / tclose() yourself, but you still need to process the transfer callbacks. A transfer is considered failed if no bytes were transmitted for at least XFERTIMEOUT deciseconds, in which case it will be aborted and repeated indefinitely with exponential backoff.

The main benefit of using the engine-supplied transfer queueing is not the reduced application complexity, but the built-in overlapping transfer pipelining that reduces the impact of transitions between files on your overall throughput.

Adding nodes

Nodes can be added to putnodes_result(error e, targettype t, NewNode* nn)

Method: void putnodes(handle parenthandle, NewNode* newnodes, int numnodes)

parenthandle is the handle of the new nodes’ parent node.

newnodes is an array of populated NewNode structures. Under some circumstances, this array will be accessed after the call to putnodes() has already returned. Therefore, always allocate this array from the heap and free it in putnodes_result().

numnodes is the number of NewNode records present.

Callback: putnodes_result(client,error) if the operation

Create folder share or create folder key

Method: setshare(node,targetuser,accesslevel)

Callback: share_result(client,error)

Callback: share_result(client,int,error)

Check if user is logged into a full account

Method: loggedin()

Returns: 1 if logged in, 0 otherwise

Check access to a node

Method: checkaccess(node,level)

Returns: 1 if access allowed, 0 otherwise

Check if a move node operation would be permitted

Method: checkmove(node,targetnode)

Returns: error code (API_OK, API_EACCESS or API_ECIRCULAR)

Prefix and encrypt JSON object for use as node attribute string

Method: makeattr(cipher,targetstring,jsonstring,length)

Request for new FileAccess object

Callback: newfile()

Returns: Application-specific FileAccess object

User update notification

Callback: users_updated(client,users,count) – users were added or updated (users are never deleted)

Node update notification

Callback: node_updated(client,nodes,count) – nodes were added, updated or removed

Callback: notify_retry(client,time) – specifies time in deciseconds until the next retry

Callback: reload(client,reason) – possible inconsistency, reload account state

Error codes

• API_OK (0): Success
• API_EINTERNAL (-1): An internal error has occurred. Please submit a bug report, detailing the exact circumstances in which this error occurred.
• API_EARGS (-2): You have passed invalid arguments to this command.
• API_EAGAIN (-3) (always at the request level): A temporary congestion or server malfunction prevented your request from being processed. No data was altered. Retry. Retries must be spaced with exponential backoff.
• API_ERATELIMIT (-4): You have exceeded your command weight per time quota. Please wait a few seconds, then try again (this should never happen in sane real-life applications).
• API_EFAILED (-5): The upload failed. Please restart it from scratch.
• API_ETOOMANY (-6): Too many concurrent IP addresses are accessing this upload target URL.
• API_ERANGE (-7): The upload file packet is out of range or not starting and ending on a chunk boundary.
• API_EEXPIRED (-8): The upload target URL you are trying to access has expired. Please request a fresh one.
• API_EOENT (-9): Object (typically, node or user) not found
• API_ECIRCULAR (-10): Circular linkage attempted
• API_EACCESS (-11): Access violation (e.g., trying to write to a read-only share)
• API_EEXIST (-12): Trying to create an object that already exists
• API_EINCOMPLETE (-13): Trying to access an incomplete resource
• API_EKEY (-14): A decryption operation failed (never returned by the API)
• API_ESID (-15): Invalid or expired user session, please relogin
• API_EBLOCKED (-16): User blocked
• API_EOVERQUOTA (-17): Request over quota
• API_ETEMPUNAVAIL (-18): Resource temporarily not available, please try again later
• API_ETOOMANYCONNECTIONS (-19): Too many connections on this resource
• API_EWRITE (-20): Write failed
• API_EREAD (-21): Read failed
• API_EAPPKEY (-22): Invalid application key; request not processed

Under the hood

Knowledge of the following low-level details is not required to develop MEGA client applications. It is provided as a reference to those who are interested in fully understanding how MEGA’s API works.

Communication protocol

The MEGA API is based on a simple HTTP/JSON request-response scheme. Requests are submitted as arrays of command objects and can be initiated by both the client and the server, effectively resulting in bidirectional RPC capability. To see the raw request flow in the SDK’s megaclient sample app, use the debug command.

Cryptography

All symmetric cryptographic operations are based on AES-128. It operates in cipher block chaining mode for the file and folder attribute blocks and in counter mode for the actual file data. Each file and each folder node uses its own randomly generated 128 bit key. File nodes use the same key for the attribute block and the file data, plus a 64 bit random counter start value and a 64 bit meta MAC to verify the file’s integrity.

Each user account uses a symmetric master key to ECB-encrypt all keys of the nodes it keeps in its own trees. This master key is stored on MEGA’s servers, encrypted with a hash derived from the user’s login password.

File integrity is verified using chunked CBC-MAC. Chunk sizes start at 128 KB and increase to 1 MB, which is a reasonable balance between space required to store the chunk MACs and the average overhead for integrity-checking partial reads.

In addition to the symmetric key, each user account has a 2048 bit RSA key pair to securely receive data such as share keys or file/folder keys. Its private component is stored encrypted with the user’s symmetric master key.

Shared folders

The owner of the folder is solely responsible for managing access; shares are non-transitive (shares cannot be created on folders in incoming shares). All participants in a shared folder gain cryptographic access through a common share-specific key, which is passed from the owner (theoretically, from anyone participating in the share, but this would create a significant security risk in the event of a compromise of the core infrastructure) to new participants through RSA. All keys of the nodes in a shared folder, including its root node, are encrypted to this share key. The party adding a new node to a shared folder is responsible for supplying the appropriate node/share-specific key. Missing node/share-specific keys can only be supplied by the share owner.

Unauthenticated delivery

MEGA supports secure unauthenticated data delivery. Any fully registered user can receive files or folders in their inbox through their RSA public key.

Login Sessions

Each login starts a new session. For regular accounts, this involves the server generating a random session token and encrypting it to the user’s private key. The user password is considered verified if it decrypts the private key, which then decrypts the session token.

To prevent remote offline dictionary attacks on a user’s password, the encrypted private key is only supplied to the client if a hash derived from the password is presented to the server.

API request flow and execution

API requests flow in two directions: client → server and server → client

Client-server requests are issued as HTTP POST with a raw JSON payload. A request consists of one or multiple commands and is executed as a single atomic, isolated and consistent transaction – in the event of a request-level error response, no data was altered. Requests are idempotent – sending the same request multiple times is equivalent to sending it once, which makes it safe to retry them, e.g. in case of intermittent network issues. Each request must therefore be tagged with a session-unique identifier (e.g., a sequence number) to prevent inadvertent cache hits caused by preceding identical requests.

While a request is executed, all users that may be affected by it are locked. This includes the requesting user and all users that are in a shared folder relationship and/or in the contact list. A request may return the error code EAGAIN in the event of a failed locking attempt or a temporary server-side malfunction. The request is likely to complete when retried. Client applications must implement exponential backoff (with user-triggerable immediate retry) and should inform the user of a possible server or network issue if the EAGAIN condition persists or no response is received for more than a few seconds.

An executed request returns an array of result objects, with each result appearing in the same array index location as the corresponding command.

Request URL format

Target URL: https://g.api.mega.co.nz/cs?id=sequence_number&ak=appkey&[&sid=sessionid|&n=node]

• sequence_number is a session-unique number that is incremented per dispatched request (but not changed when requests are repeated in response to network issues or EAGAIN)
• appkey is the application’s key
• appkey is the application’s key
• node is the node token of the filesystem tree authentication mode

POST JSON request payload structure

The JSON object shall be sent as the payload of a raw POST request. No additional framing shall take place. The Content-Type HTTP header is not processed, but should be set to application/json.
Its structure is an array of commands: [cmd1,cmd2,…]
with cmd = { a : command type, [argument : value]* }.

POST JSON response payload structure

The response to the request is a raw JSON object of content-type application/json.

It is structured as single number (e.g. -3 for EAGAIN) in the case of a request-level error or as an array of per-command return objects: [res1,res2,…]

To prevent infrastructure overload, dynamic rate limiting is in effect. Before a request is executed, the total « weight » of the commands it contains is computed and checked against the current balance of the requesting IP address. If the total exceeds a defined threshold, the request is rejected as a whole and must be repeated with exponential backoff

Server-client requests

As a server cannot reliably establish a connection to a client, server-client requests have to be polled by the latter through a blocking read loop.

Request URL format

Target URL: https://g.api.mega.co.nz/sc?id=sequence_reference[&sid=sessionid|&n=node][ssl=1]

• sequence_reference tells the server which server-client request(s) to deliver next. It is initialized from the response to a filesystem tree fetch (f command).
• sessionid is the session ID of the user session authentication mode
• node is the node token of the filesystem tree authentication mode
• ssl=1 forces an HTTPS URL for the returned wait_url (which is needed for most browsers, but not in an application context)

POST JSON response payload structure

A request level error is received as a single number (e.g. -3 for EAGAIN) or a raw JSON object with content-type application/json. Its structure is as follows:
{ a : [req1,req2,…], [ sn : sequence_reference | w : wait_url ] }

• req² are server-client requests
• sequence_reference updates the sequence reference that is used the invocation of the /cs request URL
• wait_url requests that the client connects to this (potentially long) URL, which will block until new requests are ready for delivery, so once it disconnects (with an HTTP 200 OK response and a content-length of 0), the polling process shall loop back to fetching new requests, using the current sequence_reference.

JSON data encoding

As JSON is not binary clean, all non-ASCII data has to be encoded. For binary data, the MEGA API uses a variation of base64 with -_ instead of +/ and the trailing = stripped (where necessary, the actual payload length is heuristically inferred after decoding, e.g. by stripping trailing NULs). UNICODE text has to be encoded as UTF-8.

API data types

The MEGA API uses the following major data types:

Node handles

Node handles are eight alphanumeric characters in length and case sensitive.

User handles

User handles consist of eleven base64-characters.

Encryption keys

Encryption keys are always base64-encoded. The following key types exist:

• Symmetric AES keys (22 characters)
• Folder node keys (22 characters)
• File node keys (43 characters)
• RSA public/private keys (2048 bit: 348/875 characters)
• Node and file keys in a share context are transmitted in a compound per-share format: sharehandle:key/sharehandle:key/… – each key is encrypted to its corresponding share handle

File encryption

MEGA uses client-side encryption/decryption to end-to-end-protect file transfers and storage. Data received from clients is stored and transmitted verbatim; servers neither decrypt, nor re-encrypt, nor verify the encryption of incoming user files. All cryptographic processing is under the control of the end user.

To allow for integrity-checked partial reads, a file is treated as a series of chunks. To simplify server-side processing, partial uploads can only start and end on a chunk boundary. Furthermore, partial downloads can only be integrity-checked if they fulfil the same criterion.
Chunk boundaries are located at the following positions:
0 / 128K / 384K / 768K / 1280K / 1920K / 2688K / 3584K / 4608K / … (every 1024 KB) / EOF
A file key is 256 bits long and consists of the following components:

• A 128 bit AES-128 key
• The upper 64 bit n of the counter start value (the lower 64 bit are starting at 0 and incrementing by 1 for each AES block of 16 bytes)
• A 64 bit meta-MAC m of all chunk MACs

A chunk MAC is computed as follows (this is essentially CBC-MAC, which was chosen instead of the more efficient OCB over intellectual property concerns):
h := (n << 64) + n
For each AES block d: h := AES(k,h XOR d)
A chunk is encrypted using standard counter mode:
For each AES block d at block position p: d’ := d XOR AES(k,(n << 64)+p)
MAC computation and encryption can be performed in the same loop.
Decryption is analogous.
To obtain the meta-MAC m, apply the same CBC-MAC to the resulting block MACs with a start value of 0. The 64 bit meta-MAC m is computed as ((bits 0-31 XOR bits 32-63) << 64) + (bits 64-95 XOR bits 96-127).

Uploads

Uploads are performed by POSTing raw data to the target URL returned by the API u command. If so desired, an upload can be performed in chunks. Chunks can be sent in any order and can be of any size, but they must begin and end on a chunk boundary. The byte offset x of a chunk within the file is indicated by appending /x to the URL. Multiple chunks can be sent in parallel. After a chunk completes, the server responds with a status message, which can be:

• Empty – successful receipt
• A (negative) error code in decimal ASCII representation, typically requiring a restart of the upload from scratch
• A 27-character base64-encoded completion handle that must be used in conjunction with the p (put node) API command to complete the upload

The per-upload encryption key must be generated by a strong random number generator. Using a weak one will undermine the confidentiality and integrity of your data.

Downloads

TCP throughput on high-latency links is adversely affected by slow congestion window growth, insufficient send or receive buffer size and (even mild) packet loss. All of these factors can be mitigated by using multiple transfer connections in parallel. Client applications are encouraged to offer users to configure up to six parallel connections in each direction. The recommended default value is four.

HTTPS vs. HTTP

All MEGA servers support HTTPS access – this is due to many web browsers enforcing a policy where HTTP requests cannot be made from an HTTPS page at all (IE, Firefox 18+) or at least trigger a visual warning (Chrome, Firefox until 17). However, only two types of requests actually benefit from and therefore require HTTPS: The loading of https://mega.nz/index.html and the API request interface. Neither the hash-protected loading of static .html and .js components, nor the waiting for new server-client requests, nor already encrypted and MAC’ed data transfers from and to the storage cluster benefit from HTTPS in any meaningful way. Client applications are therefore required to use SSL for access to the API interface, but strongly discouraged from doing so for wait requests and bulk file transfers.

MEGA’s HTTPS access supports most ciphers/hashes and uses strong 2048 bit RSA where SSL is relevant (i.e. on the root HTML and the API servers) and RC4/MD5 with CPU-saving 1024 bit RSA where it is not (i.e. on static HTML and storage servers).

PFS (« perfect forward secrecy ») is supported on the API servers only, because secrecy is not required for public static content.