Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Plack::Middleware::CroUseriContributed Perl DPlack::Middleware::CrossOrigin(3)

NAME
       Plack::Middleware::CrossOrigin -	Adds headers to	allow Cross-Origin
       Resource	Sharing

SYNOPSIS
	   # Allow any WebDAV or standard HTTP request from any	location.
	   builder {
	       enable 'CrossOrigin', origins =>	'*';
	       $app;
	   };

	   # Allow GET and POST	requests from any location, cache results for 30 days.
	   builder {
	       enable 'CrossOrigin',
		   origins => '*', methods => ['GET', 'POST'], max_age => 60*60*24*30;
	       $app;
	   };

DESCRIPTION
       Adds Cross Origin Request Sharing headers used by modern	browsers to
       allow "XMLHttpRequest" to work across domains.  This module will	also
       help protect against CSRF attacks in some browsers.

       This module attempts to fully conform to	the CORS spec, while allowing
       additional flexibility in the values specified for the of the headers.

       The module also ensures that the	response contains a "Vary: Origin"
       header to avoid potential issues	with caches.

CORS REQUESTS IN BRIEF
       There are two types of CORS requests.  Simple requests, and preflighted
       requests.

   Simple Requests
       A simple	request	is one that could be generated by a standard HTML
       form.  Either a "GET" or	"POST" request,	with no	additional headers.
       For these requests, the server processes	the request as normal, and
       attaches	the correct CORS headers in the	response.  The browser then
       decides based on	those headers whether to allow the client script
       access to the response.

   Preflighted Requests
       If additional headers are specified, or a method	other than "GET" or
       "POST" is used, the request must	be preflighted.	 This means that the
       browser will first send a special request to the	server to check	if
       access is allowed.  If the server allows	it by responding with the
       correct headers,	the actual request is then performed.

CSRF Protection
       Some browsers will also provide same headers with cross domain "POST"
       requests	from HTML forms.  These	requests will also be checked against
       the allowed origins and rejected	before they reach the rest of your
       Plack application.

CONFIGURATION
       origins A list of allowed origins.  Origins should be formatted as a
	       URL scheme and host, with no path information.
	       ("http://www.example.com") '"*"'	can be specified to allow
	       access from any location.  Wildcards ("*") can also be included
	       in in the host to match any part	of a host name (e.g.
	       "https://*.example.com").  At least one origin must bust	be
	       specified for this middleware to	have any effect.  This will be
	       matched against the "Origin" request header, and	will control
	       the "Access-Control-Allow-Origin" response header.  If the
	       origin does not match, the request is aborted.

       headers A list of allowed request headers.  '"*"' can be	specified to
	       allow any headers.  Controls the	"Access-Control-Allow-Headers"
	       response	header.	 Includes a set	of headers by default to
	       simplify	working	with WebDAV and	AJAX frameworks:

	       o   "Cache-Control"

	       o   "Depth"

	       o   "If-Modified-Since"

	       o   "User-Agent"

	       o   "X-File-Name"

	       o   "X-File-Size"

	       o   "X-Prototype-Version"

	       o   "X-Requested-With"

       methods A list of allowed methods.  '"*"' can be	specified to allow any
	       methods.	 Controls the "Access-Control-Allow-Methods" response
	       header.	Defaults to all	of the standard	HTTP and WebDAV
	       methods.

       max_age The max length in seconds to cache the response data for.
	       Controls	the "Access-Control-Max-Age" response header.  If not
	       specified, the web browser will decide how long to use.

       expose_headers
	       A list of allowed headers to expose to the client. '"*"'	can be
	       specified to allow the browser to see all of the	response
	       headers.	 Controls the "Access-Control-Expose-Headers" response
	       header.

       credentials
	       Whether the resource will be allowed with user credentials
	       (cookies, HTTP authentication, and client-side SSL
	       certificates) supplied.	Controls the
	       "Access-Control-Allow-Credentials" response header.

       continue_on_failure
	       Normally, simple	requests with an Origin	that hasn't been
	       allowed will be stopped before they continue to the main	app.
	       If this option is set, the request will be allowed to continue,
	       but no CORS headers will	be added to the	response.  This
	       matches how non-allowed requests	would be handled if this
	       module was not used at all.

	       This disables the CSRF protection and is	not recommended.  It
	       could be	needed for applications	that need to allow cross-
	       origin HTML form	"POST"s	without	whitelisting domains.

BROWSER	SUPPORT
       Different browsers have different levels	of support for CORS headers.

       Gecko (Firefox, Seamonkey)
	       Initially supported in Gecko 1.9.1 (Firefox 3.5).  Supports the
	       complete	CORS spec for "XMLHttpRequest"s.

	       Does not	yet provide the	"Origin" header	for CSRF protection
	       (Bugzilla #446344
	       <https://bugzilla.mozilla.org/show_bug.cgi?id=446344>).

       WebKit (Safari, Google Chrome)
	       Initially supported in Safari 4 and Chrome 3. Supports the
	       complete	CORS spec.

	       The "expose_headers" feature has	been supported since WebKit
	       v535.18 (Safari 6, Chrome 18). Preflighted requests were	buggy
	       prior to	WebKit v534.19 (Safari 5.1, Chrome 11),	but this
	       module uses a workaround	where possible (using the "Referer"
	       header).

	       Also provides the "Origin" header for CSRF protection starting
	       with WebKit v528.5 (Chrome 2, Safari 4).

       Internet	Explorer
	       Initially supported in IE8.  Not	supported with the standard
	       "XMLHttpRequest"	object.	 A separate object, "XDomainRequest",
	       must be used.  Only "GET" and "POST" methods are	allowed.  No
	       extra headers can be added to the request.  Neither the status
	       code or any headers aside from "Content-Type" can be retrieved
	       from the	response.

	       IE10 supports CORS via the standard "XMLHttpRequest" object.

       Opera   Opera and Opera Mobile support CORS since version 12.

SEE ALSO
   CORS	Resources
       o   W3C Spec for	Cross-Origin Resource Sharing
	   <http://www.w3.org/TR/cors/>

       o   W3C Spec for	Cross-Origin Resource Sharing -	Implementation
	   Considerations <http://www.w3.org/TR/cors/#resource-implementation>

       o   Mozilla Developer Center - HTTP Access Control
	   <https://developer.mozilla.org/En/HTTP_access_control>

       o   Mozilla Developer Center - Server-Side Access Control
	   <https://developer.mozilla.org/En/Server-Side_Access_Control>

       o   Cross browser examples of using CORS	requests
	   <http://www.nczonline.net/blog/2010/05/25/cross-domain-ajax-with-
	   cross-origin-resource-sharing/>

       o   MSDN	- XDomainRequest Object	<http://msdn.microsoft.com/en-
	   us/library/cc288060%28v=vs.85%29.aspx>

       o   XDomainRequest - Restrictions, Limitations and Workarounds
	   <http://blogs.msdn.com/b/ieinternals/archive/2010/05/13/xdomainrequest-
	   restrictions-limitations-and-workarounds.aspx>

       o   Wikipedia - Cross-Origin Resource Sharing
	   <http://en.wikipedia.org/wiki/Cross-Origin_Resource_Sharing>

       o   CORS	advocacy <http://enable-cors.org/>

   CSRF	Resources
       o   Wikipedia - Cross-site request forgery
	   <http://en.wikipedia.org/wiki/Cross-site_request_forgery>

       o   Stanford Web	Security Research - Cross-Site Request Forgery
	   <http://seclab.stanford.edu/websec/csrf/>

       o   WebKit Bugzilla - Add origin	header to POST requests
	   <https://bugs.webkit.org/show_bug.cgi?id=20792>

       o   Mozilla Bugzilla - Implement	Origin header CSRF mitigation
	   <https://bugzilla.mozilla.org/show_bug.cgi?id=446344>

   Related Technologies
       o   Cross-domain	policy file for	Flash
	   <http://www.adobe.com/devnet/articles/crossdomain_policy_file_spec.html>

       o   Wikipedia - JSONP <http://en.wikipedia.org/wiki/JSONP>

AUTHOR
       Graham Knop <haarg@haarg.org>

COPYRIGHT AND LICENSE
       This software is	copyright (c) 2011 by Graham Knop.

       This is free software; you can redistribute it and/or modify it under
       the same	terms as the Perl 5 programming	language system	itself.

AUTHOR
       haarg - Graham Knop (cpan:HAARG)	<haarg@haarg.org>

   CONTRIBUTORS
       None so far.

COPYRIGHT
       Copyright (c) 2011 the Plack::Middleware::CrossOrigin "AUTHOR" and
       "CONTRIBUTORS" as listed	above.

LICENSE
       This library is free software and may be	distributed under the same
       terms as	perl itself.

perl v5.32.0			  2019-03-05 Plack::Middleware::CrossOrigin(3)

NAME | SYNOPSIS | DESCRIPTION | CORS REQUESTS IN BRIEF | CSRF Protection | CONFIGURATION | BROWSER SUPPORT | SEE ALSO | AUTHOR | COPYRIGHT AND LICENSE | AUTHOR | COPYRIGHT | LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Plack::Middleware::CrossOrigin&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help