Commits

James Bennett committed 2941af9

Expand documentation.

Comments (0)

Files changed (3)

 "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`_, served from the URL ``/crossdomain.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
 Views provided by this application
 ==================================
 
-At present, two views are defined, both in ``flashpolicies.views``:
+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``
 **Optional arguments:**
 
 None.
-
+    
 ``flashpolicies.views.no_access``
 ---------------------------------
 
-A Flash cross-domain policy which permits no access of any kind.
+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.
 
+``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
 ========================
 
-A very simple policy-file generator, supporting a minimal set of
-features, is in ``flashpolicies.policies``. For the present moment it
-is undocumented, as its API is likely to change significantly as this
-application's functionality is fleshed out and stabilized. If you're
-interested in generating policy files beyond what the two provided
-views can handle, however, you might want to have a look at it.
+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
+==================
+``Policy`` objects
+==================
+
+
+Internally, all policy files generated by this application come from
+instances of ``flashpolicies.policies.Policy``, which knows how to
+handle the various permitted options in policy files, and can generate
+the correct XML. This document covers ``Policy`` objects and their
+API, but is not and should not be taken to be documentation on the
+format and options for cross-domain policy files; `Adobe's
+cross-domain policy specification`_ is the canonical source for that
+information.
+
+.. _Adobe's cross-domain policy specification: http://www.adobe.com/devnet/articles/crossdomain_policy_file_spec.html
+
+
+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 is
+required; this serializes the ``Document`` to a string in a particular
+encoding, suitable for writing to file or serving via 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>
+
+.. _the xml.dom.minidom module in the Python standard library: http://docs.python.org/library/xml.dom.minidom.html
+
+
+Methods of ``Policy`` objects
+=============================
+
+The following methods are available on ``Policy`` objects to allow
+finer-grained control of the various policy options. For explanations
+of what these options mean, please consult the cross-domain policy
+specification from Adobe.
+
+
+``allow_domain(domain, to_ports=None, secure=True)``
+----------------------------------------------------
+
+Allow access from ``domain``, which may be either a full domain name,
+or a wildcard (e.g., ``*.example.com``, or simply ``*``). Due to
+security concerns, it is strongly recommended that you use explicit
+domains rather than wildcards.
+
+For socket policy files, pass a list of ports or port ranges as the
+keyword argument ``to_ports``. As with ``domain``, a wildcard value --
+``*`` -- will allow all ports.
+
+To disable Flash's requirement of security matching (e.g., retrieving
+a policy via HTTPS will require that SWFs also be retrieved via
+HTTPS), pass ``secure=False``. Due to security concerns, it is
+strongly recommended that you not disable this.
+
+``metapolicy(permitted)``
+-------------------------
+
+Set meta-policy information (only applicable to master policy
+files). Acceptable values correspond to those listed in Section
+3(b)(i) of the crossdomain.xml specification, and are also available
+as a set of constants defined in this module.
+
+By default, Flash assumes a value of ``master-only``, so if this is
+desired (and, for security, it typically is), this method does not
+need to be called.
+
+``allow_headers(domain, headers, secure=True)``
+-----------------------------------------------
+
+Allow ``domain`` to push data via the HTTP headers named in
+``headers``.
+
+As with ``allow_domain``, ``domain`` may be either a full domain name
+or a wildcard. Again, use of wildcards is discouraged for security
+reasons.
+
+The value for ``headers`` should be a list of header names.
+        
+To disable Flash's requirement of security matching (e.g., retrieving
+a policy via HTTPS will require that SWFs also be retrieved via
+HTTPS), pass ``secure=False``. Due to security concerns, it is
+strongly recommended that you not disable this.
+

flashpolicies/views.py

 def no_access(request):
     """
     A Flash cross-domain access policy which permits no access of any
-    kind, via a meta-policy disallowing all policy files.
+    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