Cross-domain Policy File Specification

Note: This version of the spec is out of date. For the most up to date version, see http://adobe.com/go/policyfiles.

Updates:

March 22, 2008

  • Added Sockets flowchart

March 24, 2008

  • Removed www from master policy file URL examples
  • Small spelling/plural/etc. edits

March 28, 2008

  • Added #IMPLIED to to-ports in inline DTD
  • Included question TODO on last domain matching example

Version

[ Document version 0.2. Last updated 28 Mar 2008 ]

Contents

  1. Introduction
  2. Schemas
  3. XML Element Definitions
    1. cross-domain-policy
    2. site-control
      1. permitted-cross-domain-policies
    3. allow-access-from
      1. domain
      2. to-ports
      3. secure
    4. allow-http-request-headers-from
      1. headers
      2. domain
      3. secure
    5. policy-file-request
  4. Deployment
    1. Serving policy files
    2. Master policy files
  5. Appendix
    1. Domain matching
    2. Flash Player support by version
  6. Additional Resources

Introduction

A cross-domain policy file is a XML document that grants a web client, such as Adobe Flash Player, permission to handle data across multiple domains. When a client hosts a content from a particular source domain and that content makes requests directed towards a domain other than its own, the remote domain would need to host a cross-domain policy file that would grant access to the source domain allowing the client to continue with the transaction. Policy files grant read access to data as well as permit a client to include custom headers in cross-domain requests.

Policy files are also used with sockets to grant permissions for socket-based connections. For a socket connection a policy file can be used for both same domain connections as well as connections made across domains.

The most common location for a policy file on a server is in the root directory of a domain with the file name crossdomain.xml (e.g. http://example.com/crossdomain.xml) -- the default location that clients check when a policy file is required. Policy files saved this way are known as master policy files. The following is an example of a typical, permissive URL (i.e. non-socket) master policy file.

<?xml version="1.0"?>
<!DOCTYPE cross-domain-policy SYSTEM
"http://www.adobe.com/xml/dtds/cross-domain-policy.dtd">

<cross-domain-policy>
	<site-control permitted-cross-domain-policies="master-only"/>
	<allow-access-from domain="*"/>
	<allow-http-request-headers-from domain="*" headers="SOAPAction"/>
</cross-domain-policy>

The site-control element here specifies that only this master policy file should be considered valid on this domain. Below that, the allow-access-from element specifies that content from any other domain can access any data within the current domain (the domain in which this policy file has been saved). Finally, the allow-http-request-headers-from element indicates that a SOAPAction header is also allowed to be sent with requests made to this domain.

Schemas

[TODO: Confirm updated for full 9.4 release; make sure to-ports is included]

Schemas describe the structure of a document. The cross-domain policy file schema is available as DTD (Document Type Definition) or XSD (XML Schema Definition). The DTD is as follows:

<?xml version="1.0" encoding="ISO-8859-1"?>
	<!-- Adobe DTD for cross-domain policy files -->
	<!-- Copyright (c) 2008, Adobe Systems Inc. -->

<!ELEMENT cross-domain-policy
	(site-control?,allow-access-from*,allow-http-request-headers-from*)>

<!ELEMENT site-control EMPTY>
<!ATTLIST site-control permitted-cross-domain-policies
	(none|master-only|by-content-type|by-ftp-filename|all) "none" #REQUIRED>

<!ELEMENT allow-access-from EMPTY>
<!ATTLIST allow-access-from domain CDATA #REQUIRED>
<!ATTLIST allow-access-from to-ports CDATA #IMPLIED>
<!ATTLIST allow-access-from secure (true|false) "true">

<!ELEMENT allow-http-request-headers-from EMPTY>
<!ATTLIST allow-http-request-headers-from domain CDATA #REQUIRED>
<!ATTLIST allow-http-request-headers-from headers CDATA #REQUIRED>
<!ATTLIST allow-http-request-headers-from secure (true|false) "true">

<!-- End of file. -->

XSDs are available to define the generic policy file schema as well as each different type of policy file, either HTTP, HTTPS, FTP, or Socket as policy files hosted in each of those contexts are slightly different. Links to all available schema for policy files can be found in table 2.1.

Schema URL
Generic DTD http://www.adobe.com/xml/dtds/cross-domain-policy.dtd
Generic XSD http://www.adobe.com/xml/schemas/PolicyFile.xsd
HTTP XSD http://www.adobe.com/xml/schemas/PolicyFileHttp.xsd
HTTPS XSD http://www.adobe.com/xml/schemas/PolicyFileHttps.xsd
FTP XSD http://www.adobe.com/xml/schemas/PolicyFileFtp.xsd
Socket XSD http://www.adobe.com/xml/schemas/PolicyFileSocket.xsd

Table 2.1: Schema links

XML Element Definitions

Cross-domain policy files are comprised of four different XML elements, cross-domain-policy, site-control, allow-access-from, and allow-http-request-headers-from. The cross-domain-policy element is the root node of a policy file document with the other elements making up its children. Details concerning each element are covered in more detail throughout this section.

cross-domain-policy

The cross-domain-policy element is the root element for cross-domain policy files. It acts as a container for policy file definitions and has no attributes of its own to define cross-domain policies.

Attributes:

Child of:

Child elements:

Examples:

<?xml version="1.0"?>
<!DOCTYPE cross-domain-policy SYSTEM
"http://www.adobe.com/xml/dtds/cross-domain-policy.dtd">

<cross-domain-policy>
	<site-control permitted-cross-domain-policies="none"/>
</cross-domain-policy>

This is the least permissive master policy file definition. It enforces a meta-policy that restricts any policy file, including this one, from granting permissions of any type to any domain.

<?xml version="1.0"?>
<!DOCTYPE cross-domain-policy SYSTEM
"http://www.adobe.com/xml/dtds/cross-domain-policy.dtd">

<cross-domain-policy>
	<site-control permitted-cross-domain-policies="all"/>
	<allow-access-from domain="*" secure="false"/>
	<allow-http-request-headers-from domain="*" headers="*" secure="false"/>
</cross-domain-policy>

This is the most permissive master policy file definition (not recommended). It allows any policy file defined on the server of this domain to grant permissions, allows access to any file on the server, and permits any header to be sent to the server - all of this possible even through HTTPS despite the source being HTTP.

<?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="*.example.com" to-ports="1100,1200,1212"/>
</cross-domain-policy>

This policy file is an example of a socket-based policy that would be served to a client through a socket connection. It allows socket connections from the domain example.com, including subdomains, to ports 1100, 1200, and 1212.

site-control

[Master policy file only] The site-control element defines the meta-policy for the current domain. A meta-policy decides what policy files on a domain are acceptable in the case that a client needs to use a policy file other than the domain's master policy file -- the policy file located in the domain's root under the name crossdomain.xml. The site-control element is specific to master policy files; if used within a policy file that is not the master policy file, the site-control element will be ignored.

If a client is instructed to use a policy file in a location other than that of the master policy file, the client must first check meta-policy of the master policy file to determine if the original policy file is allowed.

Meta-policies flowchart

Figure 3.1: Master policy files are checked for a meta-policy
(click image for full-size view)

Attributes:

permitted-cross-domain-policies
Specifies the meta-policy. This should contain any one of the following values:
  • none: No policy files are allowed at all, anywhere on the server, including this master policy file
  • master-only: Only this master policy file is allowed
  • by-content-type: [HTTP/HTTPS only] Only policy files served with Content-Type: text/x-cross-domain-policy are allowed
  • by-ftp-filename: [FTP only] Only policy files whose file names are crossdomain.xml (i.e. with URLs ending in /crossdomain.xml) are allowed
  • all: All policy files on this domain are allowed
The default value is none.

Child of:

Child elements:

Examples:

<?xml version="1.0"?>
<!DOCTYPE cross-domain-policy SYSTEM
"http://www.adobe.com/xml/dtds/cross-domain-policy.dtd">

<cross-domain-policy>
	<site-control permitted-cross-domain-policies="all"/>
</cross-domain-policy>

Though this policy file does not allow data access for this domain, it defined a meta-policy that allows other policy files within this domain to determine how access will be handled. A client will need to load a policy file other than the master for permissions related to this domain.

<?xml version="1.0"?>
<!DOCTYPE cross-domain-policy SYSTEM
"http://www.adobe.com/xml/dtds/cross-domain-policy.dtd">

<cross-domain-policy>
	<site-control permitted-cross-domain-policies="master-only"/>
	<allow-access-from domain="*.example.com"/>
</cross-domain-policy>

This defines a meta-policy that only allows this master policy file to function for this domain. It allows access to data on example.com and all of its subdomains.

allow-access-from

The allow-access-from element grants another domain access to read data from the current domain. For each individual domain given permission, a new allow-access-from element is required, though multiple domains can be given access with one allow-access-from element through the use of a wildcard (*).

Clients may choose to handle cross-domain data differently depending on the format of that data. For text, or other non-visual data, a policy file may be used to determine if the client is allowed to load the data from the remote domain.

Policy file load flowchart

Figure 3.2: Policy files required to load data
(click image for full-size view)

Alternatively, some data, such as images or other visual data, may be loaded from a remote domain without permission from a policy file as long as the information specific to that data never reaches the source content. Should that content request information about the remote data, the policy file would then be checked to allow or disallow that action.

Policy file access flowchart

Figure 3.3: Policy files required to access data
(click image for full-size view)

Attributes:

domain
Specifies a domain to be granted access. Both named domains and IP addresses are acceptable values. Subdomains are considered different domains. A wildcard (*) can be used to match all domains when used alone, or multiple domains (subdomains) when used as a prefix for an explicit second-level domain name separated with a dot (.). Specific, individual domains require separate allow-access-from elements. For more information, refer to Appendix a: Domain matching.
to-ports
[Sockets only] A comma-separated list of ports or range of ports a socket connection is allowed to connect. A range of ports is specified through a dash (-) between two port numbers. Ranges can be used with individual ports when separated with a comma. A single wildcard (*) can be used to allow all ports.
secure
[HTTPS and Sockets only, optional] When false, allows a HTTPS policy file to grant access to a request coming from a HTTP source. The default for URL policy files is true, providing only HTTPS sources permission. Socket policy files use a default of false.

Child of:

Child elements:

Note: An allow-access-from element in a non-master policy file can only grant another domain access to data within the directory in which it is defined and that directory's subdirectories.

Examples:

<?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="*" secure="false"/>
</cross-domain-policy>

This policy file demonstrates the most permissive use of allow-access-from granting any other domain access to the files on this domain, even if an HTTP source is accessing data on this domain through HTTPS.

<?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="example.com"/>
	<allow-access-from domain="www.example.com"/>
</cross-domain-policy>

Here, the policy file allows access to example.com in both uses of the root domain, with and without the www subdomain.

<?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="*.example.com" to-ports="507,516-523"/>
</cross-domain-policy>

This example is of a socket policy file. This XML should be served to a client through a socket connection when requested with policy-file-request. It permits access to content from example.com or any of its subdomains through ports 507 and any port between 516 and 523 inclusive.

allow-http-request-headers-from

The allow-http-request-headers-from element grants a client hosting content from another domain to send user-defined headers to the current domain. Whereas the allow-access-from element grants permission to pull data from the current domain, this tag grants permission to push data - data in the form of headers.

Policy file allow headers flowchart

Figure 3.4: Policy files required to send headers
(click image for full-size view)

Attributes:

domain
Specifies a domain to be granted access. Both named domains and IP addresses are acceptable values. Subdomains are considered different domains. A wildcard (*) can be used to match all domains when used alone, or multiple domains (subdomains) when used as a prefix for an explicit second-level domain name separated with a dot (.). Specific, individual domains require separate allow-access-from elements. For more information, refer to Appendix a: Domain matching.
headers
A comma-separated list of headers the allowed domain is permitted to send. A wildcard character (*) can be used to allow all headers or for header suffixes, allowing for headers that start with the same characters but end with different characters.
secure
[HTTPS only, optional] When false, allows a HTTPS policy file to grant access to a request coming from a HTTP source. The default is true, providing only HTTPS sources permission.

Child of:

Child elements:

Note: An allow-http-request-headers-from element in a non-master policy file can only allow headers to be sent to pages within the directory in which the policy file is defined and that directory's subdirectories.

Examples:

<?xml version="1.0"?>
<!DOCTYPE cross-domain-policy SYSTEM
"http://www.adobe.com/xml/dtds/cross-domain-policy.dtd">

<cross-domain-policy>
	<allow-http-request-headers-from domain="*" headers="SOAPAction"/>
</cross-domain-policy>

Here, any domain is allowed to send the SOAPAction header to this domain.

<?xml version="1.0"?>
<!DOCTYPE cross-domain-policy SYSTEM
"http://www.adobe.com/xml/dtds/cross-domain-policy.dtd">

<cross-domain-policy>
	<allow-http-request-headers-from domain="www.example.com" headers="Authorization,X-Foo*"/>
	<allow-http-request-headers-from domain="foo.example.com" headers="X-Foo*"/>
</cross-domain-policy>

This policy file allows the Authorization header and any header beginning with the characters X-Foo from www.example.com to be sent to this domain. If a request is coming from foo.example.com, only headers beginning with the characters X-Foo are allowed, not Authorization.

policy-file-request

The policy-file-request element is not specific to policy file documents. Rather, policy-file-request is the root element of a single-node XML document used by a client to request policy file information from a socket server. Upon reception of this document, a socket server should provide the client with the necessary policy file so that the client can continue with the connection or close it if the policy file does not permit it.

<policy-file-request/>

A socket connection receiving this data should respond with a policy file. That policy file definition then determines if the connection is allowed.

Socket policy file flowchart

Figure 3.5: Policy files through socket connections
(click image for full-size view)

Deployment

Serving policy files

All URL policy files should be served with Content-Type: text/x-cross-domain-policy. This is the same content type the by-content-type value of the permitted-cross-domain-policies attribute uses to determine validity of a policy file.

Instead of relying entirely on master policy files for meta-policies, clients may also decide to check for a X-Permitted-Cross-Domain-Policies header in documents to specify a meta-policy. In addition to the values acceptable in permitted-cross-domain-policies, this header may also use a value of none-this-response to indicate that the current document should not be used as a policy file despite other headers or its content.

Master policy files

Master policy files are policy files located in root of a domain with the file name crossdomain.xml (e.g. http://example.com/crossdomain.xml). When clients require a policy file, this is the default location for the policy file they should check. A domain should always host a master policy file to enforce the its intended meta-policy.

If a client is instructed to load a policy file other than the master policy file, the master policy file will still need to be checked by the client to ensure the meta-policy defined by the master policy file (via the site-control element) permits the use of the originally requested policy file. Without a master policy file, it is left to the client to enforce the default behavior.

Non-master policy files can only grant access to data within their own directory or within that directory's subdirectories.

Appendix

Domain matching

The following rules are used in determining if a value in the domain attribute of the allow-access-from or allow-http-request-headers-from elements matches an actual domain name:

Examples:

domain value Will match Will not match
www.example.com http://www.example.com http://example.com
http://www.example.net
http://www.adobe.com
*.example.com http://example.com
http://www.example.com
http://subdomain.example.com
http://www.example.net
http://www.adobe.com
127.0.0.1 http://127.0.0.1 http://localhost
http://127.0.0
http://127.0.0.2
www.example.* No matches, invalid domain
[TODO: is this correct?]
-

Table 5.1: Domain matching examples

Flash Player support by version

The Adobe Flash Player has supported the use of cross-domain policy files since Flash Player 6. Certain policy file features weren't implemented until later versions of the player. The details of this support is outlined in Table 5.2:

Flash Player Version Feature
Future
9,0,124,0
9,0,115,0
7,0,19,0
7,0,14,0
  • Exact domain matching where subdomains are considered separate domains
  • allow-access-from's secure attribute and a separation of HTTPS from HTTP
6,0,21,0
  • Basic cross-domain policy file support with allow-access-from element (domain and to-ports attributes) [TODO: to-ports in first release of 6?]
  • Policy files for sockets were hosted through HTTP only (URL policy files)

Table 5.2: Flash Player policy file support

[TODO: anything for 8? other versions?]

Additional Resources

[TODO: More resources. Is there anything not FPlayer specific?]