<?xml version="1.0"?>
<document>

<properties>
  <title>Profiles</title>
  <author email="m.b.taylor@bristol.ac.uk">Mark Taylor</author>
</properties>

<body>

<section name="Profiles">

<p>The SAMP protocol is defined in two parts, as an abstract API and
as transport-specific Profiles.
One or more Profiles may be offered by a SAMP hub to allow clients
to communicate with it.
At present, JSAMP offers two basic profiles, the Standard Profile,
intended for normal desktop-based clients, 
and the Web Profile, intended for browser-based clients 
(some variants of these are also possible).
These are described below.
</p>

<p>By default, the hub is configured with both Standard and Web profiles
running.
You can turn them on and off while the hub is running using
the <b>Profiles</b> menu.
You can configure which profiles are run on startup using the
<code>-profiles</code> and <code>-extraprofiles</code> 
<a href="commands.html#Hub">hub flags</a> or the
<code>jsamp.hub.profiles</code> and <code>jsamp.hub.profiles.extra</code>
<a href="sysprops.html">system properties</a>,
or if you're writing code with one of the methods in the
<a target="samp-javadoc"
   href="apidocs/org/astrogrid/samp/hub/Hub.html"
                                       >Hub</a> class.
</p>

<p>The <b>Profiles</b> menu in the hub window looks something like this:
</p>
<img src="images/ProfileMenu.png"
     alt="Screenshot of Profiles menu in the hub GUI window"/>
<p>and from the system tray icon something like this:
</p>
<img src="images/SystrayMenu.png"
     alt="Screenshot of Profiles menu in the system tray window"/>
<p>Checking one of the checkboxes has the effect of turning the 
profile in question on, and unchecking it turns it off.
When a profile is turned off, any clients registered using that profile
are forcibly ejected from the hub.
</p>

<subsection name="Standard Profile">

<p>The Standard Profile is intended for use by normal desktop tools.
Clients discover the location of the hub by looking in a file named
<code>.samp</code> in the user's home directory.
The fact that this file is normally only readable by the user running
the hub means that connections cannot be made by other users.
</p>

</subsection>

<subsection name="Web Profile">

<p>The Web Profile is intended for use by web applications, that is,
programs or web pages running inside a web browser.
Web applications can find the hub at a well-known port.
When a web application wants to register, the hub will ask the user,
by popping up a dialogue window, whether the application should be
allowed to run.
The dialogue window will look something like this:
</p>
<img src="images/WebProfilePopup.png"
     alt="Web Profile popup dialogue screenshot"/>

<p>There are a number of configuration options available for the Web Profile
hub, connected with security.
They may be set on the 
<a href="commands.html#Hub">hub command line</a>,
with the various <code>-web:*</code> options,
or using the <b>Profiles|Web Profile Configuration</b> menu.
The options are as follows:
</p>
<dl>
<dt><b>CORS cross-domain access:</b></dt>
<dd>Whether to allow access using the Cross-Origin Resource Sharing standard.
    this is believed to be the safest mode of browser/hub communication,
    so it should usually be switched on.
    </dd>
<dt><b>Flash cross-domain access:</b></dt>
<dd>Whether to allow access using the Adobe Flash-based 
    <code>crossdomain.xml</code> mechanism.
    This may be less secure than CORS, but is required for
    some browser/web application combinations.
    If you use a browser that supports CORS
    (thought to be: Chrome v2.0+, Firefox v3.5+, Safari v4.0+, IE v8+),
    and only use JavaScript-based web SAMP applications, you may be able
    to leave this switched off and thereby improve security.
    </dd>
<dt><b>Silverlight cross-domain access</b></dt>
<dd>Whether to allow access using the Microsoft Silverlight-based
    <code>clientaccesspolicy.xml</code> mechanism.
    Silverlight is believed to support the Flash mechanism, so you can and
    should probably leave this switched off.
    </dd>
<dt><b>URL Controls:</b></dt>
<dd>Whether web clients are restricted from accessing sensitive resources,
    like local files, if they have not previously been mentioned in earlier
    SAMP messages.  This option is experimental, but it is probably a good
    idea to leave it on for security reasons.
    </dd>
<dt><b>MType Restrictions:</b></dt>
<dd>Whether the messages web clients are permitted to send are restricted.
    If this option is selected, only MTypes matching a well-known list
    of harmless ones are permitted - this includes all the common MTypes
    to exchange tables, images, spectra etc.
    This option is experimental, and you may need to switch it off if
    a web client has to send messages with unusual MTypes, but otherwise
    if is a good idea to leave it on for security reasons.
    </dd>
</dl>
<p>Note that the configuration options may only be changed when the
Web Profile itself is not running.
</p>

<p>You may be able to find some web profile clients in the
   <a href="http://astrojs.github.com/sampjs/">sampjs</a> project.
</p>

</subsection>

<subsection name="Web Profile Security">

<p>The JSAMP 1.3 Recommendation discusses security in relation to the 
Web Profile, but notes that there remain some
security concerns, and that experimentation will continue in hub
implementations around this issue.
</p>

<p>The security measures taken by the JSAMP Web Profile implementation
relating to the Web Profile are:
</p>
<ul>
<li>The HTTP server on which the Web Profile runs
    will normally reject any access
    attempts from hosts other than the local host, as recommended by
    the SAMP 1.3 document.
    However, access by additional trusted hosts may be enabled if
    they are explicitly named using the
    <a href="sysprops.html#jsamp_web_extrahosts"
                    ><code>jsamp.web.extrahosts</code></a>
    system property.
    </li>
<li>The Web Profile URL translation service (Section 5.2.6 of SAMP 1.3)
    is, by default, selective about what URLs it will proxy.
    URL translation is only performed for a URL which has previously
    been mentioned (for instance as the value of a Message or Response
    argument or a declared Metadata map) in a SAMP communication
    from a trusted (non-Web Profile) client.
    Translation requests which do not meet this criterion are met
    witha 403 Forbidden response.
    This means for instance that a Web Profile client cannot simply
    request, e.g., the content of <code>file:///etc/passwd</code>.
    This policy is on by default, but can be switched off and on using
    the <b>Profiles|Web Profile Configuration|URL Controls</b> menu item from
    the hub GUI, or with the <code>-web:[no]urlcontrol</code> hub
    command-line switch.
    </li>
<li>The MTypes which a web client is permitted to send is, by default,
    restricted.
    In this way, web clients can be restricted to sending messages known
    to have harmless semantics, and blocked, for instance, from sending
    messages which cause scripts to be executed on desktop clients,
    which have more potential for dangerous effects.
    By default, only MTypes matching a "whitelist"  of wildcards 
    are allowed; this includes <code>samp.app.*</code>, <code>table.*</code>,
    <code>image.*</code>, and others which are used for the normal
    exchange of data.  This restriction can be switched off and on using
    the <b>Profiles|Web Profile Configuration|MType Restrictions</b>
    menu item from the hub GUI, or with the
    <code>-web:[no]restrictmtypes</code> hub command-line switch.
    There are ways from both the hub and the (non-Web) client side of
    achieving finer control.
    In particular non-Web clients may annotate their MType subscriptions list
    using the key "<code>x-samp.mostly-harmless</code>";
    setting this to 1 or 0 adds the MType to or removes it from the whitelist
    for that particular subscribing client.
    See the documentation of the
    <a target="samp-javadoc"
       href="apidocs/org/astrogrid/samp/web/ListMessageRestriction.html"
                                           >ListMessageRestriction</a> class
    for more detail.
    </li>
<li>The Web Profile may be switched off.  Users can switch it on and off
    during hub operation using the <b>Profiles</b>
    menu from the hub GUI (if present).
    Since version 1.3-1 it is switched on in the default configuration.
    </li>
<li>If the Web Profile is switched off during operation using
    the <b>Profiles|Web Profile</b> menu item in the hub GUI,
    any clients registered through the Web Profile will be 
    disconnected immediately.  A user can therefore eject Web Profile clients
    if there are suspicions about their behaviour.  Single clients can
    be ejected as well using the <b>Clients|Disconnect Selected Client</b>
    menu item.
    </li>
<li>The details of which cross-domain workarounds are used can be controlled
    from the <b>Profiles|Web Profile Configuration</b> menu or from the
    hub command line.  The different workarounds can be switched on and off
    independently, though only while the Web Profile is not running.
    By default CORS and Flash are switched on, and Silverlight is switched off.
    </li>
</ul>

<p>The upshot of all this is that in the default configuration, even if a
hostile web application connects to the hub, it is most unlikely to
be able to do anything worse than, for instance, send unwanted FITS
images to your image viewer.  If such a hostile client is oberved, it
can be forcibly disconnected, either individually or by shutting down
the Web Profile (or the Hub itself).  Such a hostile (or indeed friendly)
client can of course only ever connect to the Hub following explicit
authorisation by the user (clicking "Yes" on the registration popup dialogue).
</p>

</subsection>

</section>
</body>
</document>
