Developer Connection Article

Cross-domain policy file specification

This document serves as a reference for the structure and use of cross-domain policy files. This information can be used by developers and content providers to make sure their applications and servers conform to the rules set forth by policy files defined in this manner.

Contents

Introduction

A cross-domain policy file is an XML document that grants a web client—such as Adobe Flash Player (though not necessarily limited to it)—permission to handle data across multiple domains. When a client hosts 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 grants 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 filename 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

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) since policy files hosted in each of those contexts are slightly different. Table 1 lists all available schemas for policy files.

Table 1. Policy file schemas

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

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; the other elements make 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:

• (None)

Child of:

• (None; cross-domain-policy is the root node)

Child elements:

• site-control
• allow-access-from
• allow-http-request-headers-from

Examples:

The following 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="none"/>
</cross-domain-policy>

The following is the most permissive master policy file definition (strongly 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>
	<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>

The following 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:

<?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>

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 the meta-policy of the master policy file to determine if the original policy file is allowed (see Figure 1).

Figure 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 filenames are crossdomain.xml (i.e. URLs ending in /crossdomain.xml) are allowed
• all: All policy files on this domain are allowed

The default value is master-only for all policy files except socket policy files, where the default is all.

Child of:

• cross-domain-policy

Child elements:

• (None)

Examples:

Though the following 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="all"/>
</cross-domain-policy>

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

<?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>

allow-access-from

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

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

Figure 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 (see Figure 3).

Figure 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 that a socket connection is allowed to connect to. 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 an HTTPS policy file to grant access to a request coming from an HTTP source. The default for URL policy files is true, providing only HTTPS sources permission. Using false is not recommended. Socket policy files use a default of false.

Child of:

• cross-domain-policy

Child elements:

• (None)

Note: An allow-access-from element in a non-master policy file can only grant another domain access to data within its own directory and subdirectories, not a directory in a higher level of that domain.

Examples:

The following 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="*" secure="false"/>
</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"/>
	<allow-access-from domain="www.example.com"/>
</cross-domain-policy>

The following is a socket policy file example. 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:

<?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>

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 (see Figure 4). 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.

Figure 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 that 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 an HTTPS policy file to grant access to a request coming from an HTTP source. The default is true, providing only HTTPS sources permission. Using false is not recommended.

Child of:

• cross-domain-policy

Child elements:

• (None)

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:

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="*" headers="SOAPAction"/>
</cross-domain-policy>

The following 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:

<?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>

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 (see Figure 5).

Figure 5. Policy files through socket connections
(click image for full-size view)

Policy files for sockets should always be socket-based. URL policy files from an HTTP source should not be used to provide permissions to socket connections.

Note: Adobe Flash Player allowed HTTP policy files to work for socket connections prior to version 9,0,124,0.

Deployment

Serving policy files

Ideally, all URL policy files should be served with Content-Type: text/x-cross-domain-policy. This is the same content type that the by-content-type value of the permitted-cross-domain-policies attribute uses to determine validity of a policy file. The following content types are also permissible:

• text/*
• application/xml
• application/xhtml+xml

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 filename 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 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 that 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.

Appendixes

Appendix A: 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:

• For named domains, top-level domain names (i.e. com in www.example.com) should match
• For named domains, second-level domain names (i.e. example in www.example.com) should match
• Subdomains of a second-level domain (i.e. www in www.example.com), as well as the domain used without a subdomain, are considered separate domains
• When a wildcard character (*) is used as a subdomain, it also matches the domain without a subdomain
• If a wildcard is not used alone or in place of a subdomain, the domain is invalid
• IP addresses do not match named domains even if they refer to the same host
• Cross-domain redirects are not allowed and, if used, a domain is considered invalid

See Table 2 for a list of domain matching examples.

Table 2. Domain matching 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	—

Appendix B. Flash Player support by version

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 (see Table 3).

Table 3. Flash Player policy file support

Flash Player version	Feature
Future	site-control's permitted-cross-domain-policies default for non-socket policy files is master-only
9,0,124,0 (8,0,42,0)	allow-http-request-headers-from element
9,0,115,0	site-control element (permitted-cross-domain-policies default is "all")
7,0,19,0	Socket-based policy files Use of policy-file-request
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) Policy files for sockets were hosted through HTTP only (URL policy files)

Where to go from here

More information is available regarding Adobe Flash Player and its use of cross-domain policy files. The following resources help describe best practices and provide details for debugging policy file-related issues when working with Flash Player:

• Cross-domain policy file usage recommendations for Flash Player
• Policy file changes in Flash Player 9
• Setting up a socket policy file server
• External data not accessible outside a Flash movie's domain (Flash Player TechNote)
• Arbitrary headers are not sent from Flash Player to a remote domain (Flash Player TechNote)

About the author