Saphe Implementation - SaphePlugin


The Saphe plugin is based on the aforementioned examples from Mozilla.

Any Firefox plugin must implement a given set of API functions that the browser can use to communicate with it. All of these functions have a empty implementation by the standrad base class nsPluginCreateData.


Resources gathering

The Gecko API provides browser-side functions that allow the plugin to request URLs that will be retrieved by the browser.

This operation is asynchronous:

Plugin-side functions implemented by SaphePlugin

SaphePlugin implements the following functions:

  • NewStream - called by the browser when a new resposne 'stream' is ready for the plugin. The plugin verifies that the proper StreamInfo was passed, and allocates a new incoming buffer if needed
  • DestroyStream - called by the browser when a 'stream' is finished. Does nothing
  • WriteReady - called by the browser before passing 'stream' data to the plugin. Returns the maximum possible length, telling the browser to bring everything it got
  • Write - called by the browser to pass 'stream' data to the plugin. The plugin verifies that a proper StreamInfo identifies the stream, and if so - copies the given data to the buffer allocated in NewStream, re-allocating it as needed
  • URLNotify - called by the browser when a stream retrieval process is finished, either successfully or unsuccessfully if the resource was requested by calling a function with a 'Notify' suffix. In the SaphePlugin this function handles all the response parsing code, but first it verifies that a valid StreamInfo instance identifies the given stream

Plugin class functionality

The implementation allows only one plugin instance per Firefox 'tab'. This is enforced by maintaining a map from HWND handles of the tabs to NPP plugin handles.

There are several functions that were inherited from nsPluginCreateData:

  • init - called by the wrapping infrastructure after a new plugn instance is created. This function first verifies that no other plugin instance was created for the current Firefox tab by searching the HWND-to-NPP map for the parent of the HWND handle of the creating Windows that was passed as an argument (this is the HWND of the tab). If an instance already exists for this tab - the function returns. Otherwise, the map is updated and a new dialog box is created for this instance. After the dialog box is up and ready, it is insructed to ask the browser to retrieve the user's real IP address from the currently selected 'whatsmyip' server
  • shut - called by the wrapping infrastructure just before the plugin instance is destroyed. It removes the NPP which represents this instance from the map if it exists there and destroys the dialog box
  • isInitialized - returns TRUE if the plugin instance was successfully initialized or FALSE otherwise

The map is static STL map called current_instances, and access to it is guraded using a static critical section object called critical_section.

General plugin functionality

  • NS_PluginInitialize - called when the browser starts. Initializes the critical section that protects the HWND-to-NPP map and attempts to retrieve the default CSP's handle
  • NS_PluginShutdown - called when the broser closes. Destroys the critical section and frees the CSP handle
  • NS_NewPluginInstance - called whenever a new plugin instance is created. This function is given the 'creation data' structure of the plugin instance, which includes all the parameters that were included in the <embed> instruction that caused the instance to be created. The function checks if the target for the first Saphe transaction (indicated by "saphe_url=") is present and secured (must be HTTPS). It creates a new Saphe plugin instance
  • NS_DestroyPluginInstance - called whenever a plugin instance is destroyed. It frees the Saphe plugin class instance

The dialog box

The dialog box is the means through which the plugin interacts with the user. These are some relevant functions:

  • ShowError - pops an error message box
  • ShowPhishingAlert - pops a Phishing-report message box
  • DisableDialog - disables the dialog box whenever a transaction is in progress
  • EnableDialog - enables the dialog box whenever user interaction is required
  • PluginDialogProc - the main dialog box callback function. It responds to Windows Messages sent by the plugin instance, which instructs it what to do. There are four stages:
    • Initialize
    • Ask for the real IP
    • Get Saphe data
    • Report Saphe data parsing (either error or continuing the login process)

Saphe methods of the plugin class

These are general Saphe-related methods of the Saphe plugin calss:

  • SetSapheURL - copy the URL used for the first Saphe transaction to the plugin instance
  • ReportPhishingAttemptToServer - send a Phishing report to the given URL, if the URL is valid. The report includes the user's real IP address and the original URL that was requested (the same one that was included in the <embedĀ» tag). Does not verify that the reports URL is secure
  • AskForRealIP - sends an HTTP GET request to the currently selected server which returns the user's IP address in a secure connection. It instructs the browser to return the response to the plugin instance and creates an identifying StreamInfo instance
  • AskForSapheData - sends an HTTP POST request to the URL that was specified in the <embed> tag. This message includes the user name and a randomly generated client-challenge. It instructs the browser to return the response to the plugin instance and creates an identifying StreamInfo instance which includes the user name, password and client-challenge, so that they can by used later on by the response handler

Handling responses by the plugin instance

These functions handle responses to requests sent by the plugin instance. Note that responses are handled ONLY if an identifying 'notify data' is given. In which case it is converted to a StreamInfo class.

  • HandleRealIPResponse - attempt to extract the real user's IP address from the given raw HTML data by calling ExtractIPAddress
  • HandleSapheDataResponse - this is the heart of the Saphe plugin. It decrypts and parses the SapheData returned by the server, thus authenticating the server and proving that the connection is tamper-proof. First it verifies the Saphe magic ("SAPH") and checks the status code. It converts the SapheData from hex to binary, and then decrypts and parses the data using DecryptEncryptedPart. If an error is returned - the user is notified and in the case of a suspected Phishing attempt, a Phishing report is sent to the given Phishing-report URL. If the server and the connection were authenticated and the given login URL is secure - another HTTP POST message is sent to the server, this time containing the user name and password. The browser is instructed to handle the response by itself, thus completing the login process

Source code

Back to Saphe implementation page

Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-NonCommercial-ShareAlike 3.0 License