django-flashpolicies 1.6¶

Normal installation¶

The preferred method of installing django-flashpolicies is via pip, the standard Python package-installation tool. If you don’t have pip, instructions are available for how to obtain and install it.

Once you have pip, simply type:

pip install django-flashpolicies

Manual installation¶

It’s also possible to install django-flashpolicies manually. To do so, obtain the latest packaged version from the listing on the Python Package Index. Unpack the .tar.gz file, and run:

python setup.py install

Once you’ve installed django-flashpolicies, you can verify successful installation by opening a Python interpreter and typing import flashpolicies.

If the installation was successful, you’ll simply get a fresh Python prompt. If you instead see an ImportError, check the configuration of your install tools and your Python import path to ensure django-flashpolicies installed into a location Python can import from.

Installing from a source checkout¶

The development repository for django-flashpolicies is at <https://github.com/ubernostrum/django-flashpolicies>. Presuming you have git installed, you can obtain a copy of the repository by typing:

git clone https://github.com/ubernostrum/django-flashpolicies.git

From there, you can use normal git commands to check out the specific revision you want, and install it using python setup.py install.

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.

Serializing Policy objects¶

There are two similar but different ways to serialize the underlying XML. One is simply to use str() on a Policy instance, like so:

>>> from flashpolicies import policies
>>> my_policy = policies.Policy('media.example.com', 'api.example.com')
>>> print(str(my_policy))
<?xml version="1.0" ?>
<!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>

The other is to call the serialize() method. The difference between these options is:

1. str() will, as is required by Python’s semantics, produce a result of type str. Which, on Python 3, is a Unicode string; this means the output is not in any particular encoding, and will omit the encoding declaration of the XML prolog.
2. serialize() will, on the other hand, always return a sequence of UTF-8-encoded bytes. This is the type str on Python 2, and the type bytes on Python 3. In accordance with this, the output of serialize() will include an encoding declaration in its XML prolog.

In general, str() should be used to inspect a Policy for debugging or educational purposes, while serialize() should be used any time the output will actually be treated as a policy file (i.e., if writing your own policy-serving view, or if serializing the policy to a file). The built-in serve() view uses serialize().

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 when initializing. 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.

serialize()¶

Serialize this policy to a UTF-8-encoded byte string (i.e., str on Python 2, bytes on Python 3), suitable for serving over HTTP or writing to a file.

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.

allow_identity(fingerprint)¶

Allow access from digitally-signed documents.

Parameters:	fingerprint – The fingerprint of the signing key to allow.

The XML resulting from use of this method will include both the key fingerprint and the name of an algorithm used to calculate the fingerprint. At the moment, "sha-1" is the only value defined in the cross-domain policy specification for the fingerprint-algorithm attribute of the certificate element (which is the element produced by this method), and so an argument for this is omitted; if additional algorithms are added to the specification, support will be added in a backwards-compatible fashion (likely through an argument defaulting to SHA-1).

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.

Why do I need a cross-domain policy file?¶

Much like JavaScript, the Adobe Flash player by default has a same-origin policy; a Flash player instance on one domain cannot load data from another domain.

A cross-domain policy file allows you, as the owner of a domain, to specify exceptions to this, allowing loading of data from another domain (for example, if you have data hosted on a CDN).

In order to prevent security issues caused by loading data from untrusted domains, your cross-domain policy file should permit only those domains you know are trustworthy (i.e., because those domains are under your control, and you can prevent malicious content from being placed on them).

What versions of Django are supported?¶

As of django-flashpolicies 1.6, Django 1.7 and 1.8 are supported.

Older versions of Django may work, but are not supported. In particular, the behavior of the APPEND_SLASH setting in some old Django versions may be problematic: on very old versions of Django, APPEND_SLASH always adds a trailing slash even if the URL would match without it. This makes it impossible to serve a master policy file, which must have exactly the URL /crossdomain.xml, with no trailing slash.

What versions of Python are supported?¶

On Django 1.7 or Django 1.8, django-flashpolicies 1.6 supports Python 2.7, 3.3 or 3.4.

Why are the elements in a different order each time I serialize my policy?¶

Internally, a Policy stores information about permitted domains and headers in dictionaries, keyed by domain names. The resulting XML is generated by iterating over these dictionaries.

In older versions of Python, iteration over a dictionary would produce the same order of keys each time provided the set of keys was identical. Newer versions of Python include a feature, for security purposes, known as hash randomization; this means that two dictionaries with the same set of keys can and will at times iterate over those keys in different orders.

Hash randomization is enabled by default on Python 3.3, and can be enabled on older releases. If you are seeing inconsistent ordering for allow-access-from and allow-http-request-headers-from elements, it is due to hash randomization being enabled.

Since this does not affect the well-formedness or validity of the resulting XML document, it is not a bug, and you should not attempt to disable hash randomization in Python.

Why shouldn’t I use wild-card (i.e., ‘*’) domains in my policy?¶

Use of wild-card entries in a policy effectively negates much of the security gain that comes from explicitly specifying the permitted domains. Unless you can and do vigilantly control all possible domains/subdomains matching a wild-card entry, use of one will expose you to the possibility of loading malicious content.

How am I allowed to use this module?¶

django-flashpolicies is distributed under a three-clause BSD license. This is an open-source license which grants you broad freedom to use, redistribute, modify and distribute modified versions of django-flashpolicies. For details, see the file LICENSE in the source distribution of django-flashpolicies.

I found a bug or want to make an improvement!¶

The canonical development repository for django-flashpolicies is online at <https://github.com/ubernostrum/django-flashpolicies>. Issues and pull requests can both be filed there.