============================================
Cross-domain Flash policies for Django sites
============================================


Ordinarily, SWF (Flash) files executing in a browser are restricted by
a "same-origin" policy similar to that which is applied to JavaScript:
by default, Flash may only issue requests to the domain from which the
SWF itself was requested. Unlike JavaScript, however, Flash permits
"cross-domain" requests, provided that the domain to which requests
will be directed provides a policy detailing whether and in what
manner these requests may be issued. This policy consists of `an XML
document`_, typically (though not necessarily) served from the URL
``/crossdomain.xml``.

This application provides a simple implementation of Flash
cross-domain policies for Django-powered sites, suitable for many
common cases, and may expand in the future to support more advanced
uses.

.. _an XML document: http://www.adobe.com/devnet/articles/crossdomain_policy_file_spec.html


Basic use
=========

To enable a cross-domain policy, ensure that this application is
installed somewhere on your Python path (consult the file
``INSTALL.txt`` for details). You do not need to list it in
``INSTALLED_APPS``. Then set up a URL pattern, matching the URL
``/crossdomain.xml``, pointing to the view
``flashpolicies.views.simple`` and passing one keyword argument,
``domains``. This should be a list of domains from which to allow
access.

For example, if you wanted to allow access from the domains
``media.example.com`` and ``api.example.com``, you might use the
following URL pattern::

    url(r'^crossdomain.xml$',
        'flashpolicies.views.simple',
        { 'domains': ['media.example.com', 'api.example.com'] }),

This view will generate the appropriate XML and return it with the
appropriate HTTP ``Content-Type``.

You can also use wildcard values in the domain list. For example, to
allow access from any subdomain of ``example.com``::

    url(r'^crossdomain.xml$',
        'flashpolicies.views.simple',
        { 'domains': ['*.example.com'] }),

However, due to serious potential security issues, it is strongly
recommended that you not use wildcard domain values.

For recommendations concerning security issues and best practices for
cross-domain access policies, consult `Adobe's recommendations`_. It
is also recommended that you read `Google's article on cross-domain
Flash policies`_.

.. _Adobe's recommendations: http://www.adobe.com/devnet/flashplayer/articles/cross_domain_policy.html
.. _Google's article on cross-domain Flash policies: http://code.google.com/p/doctype/wiki/ArticleFlashSecurityCrossDomain


Views provided by this application
==================================

At present, four views are defined, all in
``flashpolicies.views``. Internally, ``flashpolicies.policies.serve``
is used by each of the other three; once they have generated an object
representing the policy, the call the ``serve`` view to serve it.

As such, if you wish to create a custom policy with options not
supported by the other views, you should feel free to create a
``flashpolicies.policies.Policy`` object representing the desired
policy, and use ``serve`` to serve it. For details on the api of
``Policy`` objects, see the file ``policies.txt`` in this directory.

Several of these views apply meta-policy information and must be used
as "master" policy files. If you're unsure what this means, you can
consult Adobe's documentation for cross-domain policy files. In
general, however, you will not need to be concerned with
meta-policies, multiple policy files or master policies; for the
common case of serving a single domain-wide policy from
``/crossdomain.xml``, these views are sufficient and require no
additional knowledge of the intricacies of cross-domain policies.


``flashpolicies.views.simple``
------------------------------

A simple Flash cross-domain access policy.

Note that if this is returned from the URL ``/crossdomain.xml`` on a
domain, it will act as a master policy and will not permit other
policies to exist on that domain. If you need to set meta-policy
information and allow other policies, use the view
``flashpolicies.views.metapolicy`` for the master policy instead.

**Required arguments:**

``domains``
    A list of domains from which to allow access. Each value may be
    either a domain name (e.g., ``example.com``) or a wildcard (e.g.,
    ``*.example.com``). Due to serious potential security issues, it
    is strongly recommended that you not use wildcard domain values.

**Optional arguments:**

None.
    
``flashpolicies.views.no_access``
---------------------------------

A Flash cross-domain access policy which permits no access of any
kind, via a meta-policy declaration disallowing all policy files.
    
Note that this view, if used, must become the master policy for the
domain, and so must be served from the URL ``/crossdomain.xml`` on the
domain -- setting meta-policy information in other policy files is
forbidden by the specification.

**Required arguments:**

None.

**Optional arguments:**

None.

``flashpolicies.views.metapolicy``
----------------------------------

A Flash cross-domain policy which allows other policies to exist
on the same domain.

Note that this view, if used, must become the master policy for the
domain, and so must be served from the URL ``/crossdomain.xml`` on the
domain -- setting meta-policy information in other policy files is
forbidden by the specification.

**Required arguments:**

``site_control``
    A string indicating the extent to which other policies are
    permitted. Value values are defined as constants in
    ``flashpolicies.policies``.

**Optional arguments:**

``domains``
    A list of domains from which to allow access. Each value may be
    either a domain name (e.g., ``example.com``) or a wildcard (e.g.,
    ``*.example.com``). Due to serious potential security issues, it
    is strongly recommended that you not use wildcard domain values.
    
``flashpolicies.views.serve``
-----------------------------

Given a ``flashpolicies.policies.Policy``, serialize it to XML and
serve it.

**Required arguments:**

``policy``
    A ``flashpolicies.policies.Policy`` instance.

**Optional arguments:**

None.


Additional functionality
========================

All policies generated by this application are represented by
instances of ``flashpolicies.policies.Policy``. Consult the file
``policies.txt`` in this directory for information on ``Policy``
objects and their API.


Bug reports
===========

Bugs should be reported in `the bug tracker at Bitbucket`_.

.. _the bug tracker at Bitbucket: http://bitbucket.org/ubernostrum/django-flashpolicies/issues/
