django-flashpolicies 1.3¶

Installing django-flashpolicies¶

There are several ways to install django-flashpolicies:

• Automatically, via a Python package installer.
• Manually, by downloading a copy of the release package and installing it yourself.
• Manually, by performing a Mercurial checkout of the latest code.

It is also highly recommended that you learn to use virtualenv for development and deployment of Python software; virtualenv provides isolated Python environments into which collections of software (e.g., a copy of Django, and the necessary settings and applications for deploying a site) can be installed, without conflicting with other installed software. This makes installation, testing, management and deployment far simpler than traditional site-wide installation of Python packages.

easy_install django-flashpolicies

pip install django-flashpolicies

python setup.py install

hg clone http://bitbucket.org/ubernostrum/django-flashpolicies/

Basic configuration and use¶

Once installed, you can take advantage of django-flashpolicies on any Django-based site you’re developing. Simply add flashpolicies to your INSTALLED_APPS setting (django-flashpolicies provides no models, so running manage.py syncdb is not required), and then configure one or more appropriate URL patterns to serve your cross-domain policy (or policies).

For most cases, you’ll simply need a single pattern, in your root URLConf, pointing the URL /crossdomain.xml (the standard location for a cross-domain policy) to the view flashpolicies.views.simple(), passing a list of domains from which you’d like to allow access. For example, to enable access for Flash content served from the domains media.example.com and api.example.com, the following URL pattern in your root URLConf would suffice:

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

URL configuration and interaction with APPEND_SLASH¶

Your master policy file – the only policy file on your domain, in most cases – must be served from exactly the URL /crossdomain.xml. So if your site is at example.com, the master policy file must be served from http://example.com/crossdomain.xml.

As such, the Django instance in which django-flashpolicies is used must be serving from the root of the domain. If this is not possible, you will need to find an alternate method of serving your domain’s cross-domain policy; one option is to manually create a Policy instance, and serialize it (via its xml_dom attribute), writing the result to a file which can be handled normally by your web server.

If you are using Django with the CommonMiddleware enabled and the APPEND_SLASH setting set to True (by default, this is the case for any newly-created Django project), you will need to be careful in defining the URL patterns used for serving cross-domain policies. In particular, you’ll want to use the regular expression ^crossdomain.xml$ – without trailing slash – for the URL. Django’s CommonMiddleware (as of Django 1.0) will not attempt to append a slash when an existing URL pattern matches without the trailing slash.

Note that the current behavior of APPEND_SLASH was new in Django 1.0; previous releases of Django will always attempt to append a slash, regardless of whether an existing pattern matches without it. If you are using an older release of Django, this may pose problems when attempting to serve a master policy file.

Simple interaction with Policy objects¶

For most cases, simply instantiating a Policy object with one or more domains will accomplish the desired effect. The property xml_dom will yield an xml.dom.minidom.Document object representing the policy’s XML; for information on working with these objects, consult the documentation for the xml.dom.minidom module in the Python standard library. In general, however, the toprettyxml() method of the Document will be all that’s required; this serializes the Document to a string in a particular encoding, suitable for writing to a file or serving over HTTP.

For example:

>>> from flashpolicies import policies
>>> my_policy = policies.Policy('media.example.com', 'api.example.com')
>>> print my_policy.xml_dom.toprettyxml(encoding='utf-8')
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE cross-domain-policy
  SYSTEM 'http://www.adobe.com/xml/dtds/cross-domain-policy.dtd'>
<cross-domain-policy>
        <allow-access-from domain="media.example.com"/>
        <allow-access-from domain="api.example.com"/>
</cross-domain-policy>

API reference¶

class flashpolicies.policies.Policy¶

Wrapper object for creating and manipulating a Flash cross-domain policy.

In the simplest case – specifying one or more domains from which to allow access – simply pass the domains to the constructor. For example:

my_policy = Policy('media.example.com', 'api.example.com')

xml_dom¶

A read-only property which returns an XML representation of this policy, as an xml.dom.minidom.Document object.

allow_domain(domain, to_ports=None, secure=True)¶

Allow access for Flash content served from a particular domain.

Parameters:

domain – The domain from which to allow access. May be either a full domain name (e.g., example.com) or a wildcard (e.g., *.example.com). Due to serious potential security concerns, it is strongly recommended that you avoid wildcard domain values. to_ports – (only for socket policy files) A list of ports the domain will be permitted to access. Each value in the list may be either a port number (e.g., 80), a range of ports (e.g., "80-120") or the wildcard value "*", which will permit all ports. secure – If True, will require the security level of the HTTP protocol for Flash content to match that of this policy file; for example, if the policy file was retrieved via HTTPS, Flash content from domain must also be retrieved via HTTPS. If False, this matching of security levels will be disabled. It is strongly recommended that you not disable the matching of security levels.

allow_headers(domain, headers, secure=True)¶

Allow Flash content from a particular domain to push data via HTTP headers.

Parameters:

domain – The domain from which to allow access. May be either a full domain name (e.g., example.com) or a wildcard (e.g., *.example.com). Due to serious potential security concerns, it is strongly recommended that you avoid wildcard domain values. headers – A list of HTTP header names in which data may be submitted. secure – If True, will require the security level of the HTTP protocol for Flash content to match that of this policy file; for example, if the policy file was retrieved via HTTPS, Flash content from domain must also be retrieved via HTTPS. If False, this matching of security levels will be disabled. It is strongly recommended that you not disable the matching of security levels.

metapolicy(permitted)¶

Set metapolicy information (only applicable to master policy files), determining which other policy files may be used on the same domain.

Parameters:	permitted – The metapolicy to use. Acceptable values are those listed in the cross-domain policy specification, and are also available as a set of constants defined in this module. Passing an invalid value will raise TypeError.

By default, Flash assumes a default metapolicy of master-only (except for socket policies, which assume a default of all), so if this is the desired metapolicy (and, for security reasons, it often is), this method does not need to be called.

Note that a metapolicy of none forbids all access, even if one or more domains have previously been specified as allowed. As such, setting the metapolicy to none will remove all access previously granted by allow_domain() or allow_headers(). Additionally, attempting to grant access via allow_domain() or allow_headers() will, when the metapolicy is none, raise TypeError.

Available constants¶

For ease of working with metapolicies, the following constants are defined, and correspond to the acceptable values for metapolicies as defined in the cross-domain policy specification.

flashpolicies.policies.SITE_CONTROL_ALL¶

All policy files available on the current domain are permitted. Actual value is the string "all".

flashpolicies.policies.SITE_CONTROL_BY_CONTENT_TYPE¶

Only policy files served from the current domain with an HTTP Content-Type of text/x-cross-domain-policy are permitted. Actual value is the string "by-content-type".

flashpolicies.policies.SITE_CONTROL_BY_FTP_FILENAME¶

Only policy files served from the current domain as files named crossdomain.xml are permitted. Actual value is the string "by-ftp-filename".

flashpolicies.policies.SITE_CONTROL_MASTER_ONLY¶

Only the master policy file for this domain – the policy served from the URL /crossdomain.xml – is permitted. Actual value is the string "master-only".

flashpolicies.policies.SITE_CONTROL_NONE¶

No policy files are permitted, including the master policy file. Actual value is the string "none".

flashpolicies.policies.VALID_SITE_CONTROL¶

A tuple containing the above constants, for convenient validation of metapolicy values.