Client API

Scrambling Protocols

The scrambling protocols define three things: the format of the final scrambld content, the metadata of that scrambld content, and the actual scrambling/ciphering transformation. The format specifics are protocol-dependent, but consist of start and end markers for the entire scrambld block, an encoding of the protocol details (e.g., version), an encoding of the XID, and an encoding for the transformed content. (Later protocols could/will include specification of non-Wave policy servers and non-textual data support.)

JavaScript API

The Client API currently consists of a library of JavaScript functions that are used to perform the actual scrambling and descrambling. These functions should be viewed as the reference implementation of the scrambls protocols as they produce and consume data that conform to the protocols.

These functions have no external dependencies and provide the following low-level features:

  • encoding and decoding of XIDs
  • encoding and decoding of keys (byte arrays)
  • (de)scrambling of strings
  • construction of final scrambld string
  • scanning for begin and end markers within a scrambld string
  • descrambling of scrambld strings
These low-level features are sufficient for scrambling and descrambling to conform with the protocols, but they do not, in and of themselves, provide facilities for dealing with web-site level constructs such as DOM/HTML hierarchies that contain scrambld text within some larger context such as a web page.


Scrambling a string:

  1. client code generates a key
  2. client code requests an XID via the server API, passing in a policy ID and the generated key
  3. client code receives the XID
  4. client code calls a single API to scrambl the entire string
  5. client code replaces cleartext with scrambld text


  1. client code gets text that has a substring that is scrambld; note that client code doesn't know which protocol(s) might be used
  2. client code calls client API “scanForBegin” function on all protocols, one after the other, stopping when a protocol search returns true
  3. client code uses found protocol to scan for the end of the scrambld text
  4. client code uses found protocol to descrambl the text between the start and end markers
  5. client code replaces scrambld text with cleartext.