== INTRODUCTION ==

The dataSync extension is used to synchronize data from your profile to a
remote web server (of your choosing). The extension is comprised of two
parts - the browser overlay and the gzIDataSync component. The component
does all of the hard work. It encrypts and exchanges data with the XML
data exchange processor (that must be created or setup) on the remote
server and then notifies the extension that something has happened. The
extension handles the notifictions and displays the results using an
infobar (mostly). The gzIDataSync component is modular in design, new
processing modules can be created and placed into the <profile>/dataSync
directory to expand functionality. The builtin types (as of v0.1) are
bookmarks, permissions, cookies, and stylish (http://userstyles.org).


== GETTING STARTED ==

1) Configuring the web server

The first thing you need to do is configure the 'datasync.server.url' pref.
The only protocol currently supported (as of v0.1) is HTTP. The data is sent
to the server using a POST containing XML data. A XML data exchange processor
must be setup on the URL to write out files and send responses. This can be
written in any language you'd like, so long as it adheres to the specs below.
If you're using a PHP-enabled web server, a working example can be found in
the examples/ directory. It was created and tested using Apache (2) and uses
the SimpleXML features added in PHP 5.

Protecting the URL with basic authentication and/or IP restrictions is
strongly suggested. If the data exchange processor stores the data in files
and the files are stored in a subdirectory or anything within the server's
document root, as is done with the PHP example, requests to these files
should be blocked outright (a "Deny from all" in the .htaccess).

If the URL has been setup with authentication, the datasync.server.user and
datasync.server.pass prefs can be configured with the login credentials or
they can be left unset and the password manager allowed to manage them. If
set, these values will be stored in plain text in the <profile>/prefs.js
file, and will be passed to the .open() function call of the XMLHttpRequest
when the POST request is sent to the configured URL.

2) Selecting the data encryption method

Now that the URL has been configured, you need to decide how the data will
be encrypted. If the datasync.encryption.key pref is set, an RC4 passphrase-
based encryption will be used to encrypt the data stored on the remote
server. This method is useful when security is not or less of a concern (the
key is stored in clear text in prefs.js) and/or when working with multiple
profiles. The most secure method would be to leave this pref unset, causing
the secret decoder ring to be used. This is problematic when working with
multiple profiles as the key is unique to the profile. Encryption across
different profiles will fail unless the same key3.db is used on each.

3) Finishing up

With everything properly configured, you should be ready to go. Any modules
not disabled with the datasync.modules.@moduleType boolean pref should show
up under the "Data Sync" Tools menu with options to Import, Export, and
possibly open a preferences window if the module has one.

The auto-update check timer will be running in the background. Once an URL is
configured, it well attempt to send requests to the server. If you happen to
see an error message or two before exporting any data, it can be ignored.

When you're ready, attempt an export of the selected data type. If all goes
well, you should see an infobar with a successful export message.


== USAGE AND NOTES ==

A "Data Sync" menuitem will appear on the Tools menu with submenus for each
installed module. Modules can be disabled (and the menuitems hidden) by
setting the datasync.modules.|moduleType|.enabled pref to false. Selecting
the "Export" menuitem will send the current data to the remote server and
return a status message indicating success or failure. Obviously, each type
must be exported before it can be imported. A confirmation prompt will appear
before each import and export operation by default. This can be disabled by
setting the datasync.(import|export).prompt boolean prefs to false.

If one or more updates are available, an infobar will appear for each, with
a button to import the data. The datasync.update.interval controls the update
interval check. The default interval is 3 hours (10800 seconds). Updates for
disabled modules will be ignored. It is possible to automatically import
updates with the global datasync.update.auto_import pref or individually with
the datasync.modules.|moduleType|.auto_import prefs, allowing some modules to
be imported automatically while others require interaction. No prompting will
occur in the event of an auto-import, regardless of the datasync.import.prompt
pref.

The component and builtin modules have been thoroughly tested and the best
effort made to avoid dataloss, but the possibility always exists. Regular
backups are recommended to ensure the safety of your profile data and allow
for recovery from the unexpected.

There is currently no functionality to compare the local and remote versions
before import and export operations, so no warnings will be issued before
any transactions involving old data.


== XML SPECIFICATIONS ==

# key:
#   [varName] - a variable set by the gzIDataSync component
#   @varName  - a variable that must be set by the xml data exchange server


# xml sent when exporting data:
#   [dataType]   - exported type of data (bookmarks, permissions, cookies)
#   [docVersion] - version of the exported document
#   [dataHash]   - hash of [data]
#   [dataSerial] - serial number (timestamp) of the export
#   [data]       - base64 encoding of encrypted data
#   [encType]    - encryption type used (sdr, rc4 - integer value from 0)
<dataSync action="export" type="[dataType]" version="[docVersion]"
          hash="[dataHash]" serial="[dataSerial]" encryption="[encType]">
  [data]
</dataSync>

# xml expected back when exporting:
#   @type     - the type being exported
#   @message  - an optional status message
#   @serial   - the serial number sent during the export process
<dataSync response="export" version="0" type="@type" message="@message"
          serial="@serial"/>


# xml sent when importing:
<dataSync action="import" type="[dataType]" version="[docVersion]"/>

# xml expected back when importing:
<dataSync response="import" type="[dataType]" version="[docVersion]"
          hash="[dataHash]" serial="[dataSerial]" encryption="[encType]">
  [data]
</dataSync>


# xml sent when checking for updates:
<dataSync action="updates" version="[docVersion]"/>

# xml expected back when checking for updates (w/example types and serials):
#   bookmarks, permissions, and cookies are exported types, their text node
#   contains the serial number of the last export which should match up
#   with the serial number sent during the export process
<dataSync response="updates" version="0">
  <bookmarks>1250349600</bookmarks>
  <permissions>1250349593</permissions>
  <cookies>0</cookies>
</dataSync>


# xml expected back if an error occurs:
#   @type    - the type being processed (if known)
#   @message - a status message
#   @action  - the 'action' sent during the original transaction, optional
<dataSync response="error" version="0" type="@type" message="@message"
          action="@action"/>