Author: violetagg
Date: Fri Oct 30 08:59:40 2015
New Revision: 1711434
URL: http://svn.apache.org/viewvc?rev=1711434&view=rev
Log:
Merged revision 1709895 from tomcat/trunk:
Documentation for RestCsrfPreventionFilter
Modified:
tomcat/tc8.0.x/trunk/ (props changed)
tomcat/tc8.0.x/trunk/java/org/apache/catalina/filters/RestCsrfPreventionFilter.java
tomcat/tc8.0.x/trunk/webapps/docs/changelog.xml
tomcat/tc8.0.x/trunk/webapps/docs/config/filter.xml
Propchange: tomcat/tc8.0.x/trunk/
------------------------------------------------------------------------------
--- svn:mergeinfo (original)
+++ svn:mergeinfo Fri Oct 30 08:59:40 2015
@@ -1 +1 @@
-/tomcat/trunk:1636524,1637156,1637176,1637188,1637331,1637684,1637695,1638720-1638725,1639653,1640010,1640083-1640084,1640088,1640275,1640322,1640347,1640361,1640365,1640403,1640410,1640652,1640655-1640658,1640688,1640700-1640883,1640903,1640976,1640978,1641000,1641026,1641038-1641039,1641051-1641052,1641058,1641064,1641300,1641369,1641374,1641380,1641486,1641634,1641656-1641692,1641704,1641707-1641718,1641720-1641722,1641735,1641981,1642233,1642280,1642554,1642564,1642595,1642606,1642668,1642679,1642697,1642699,1642766,1643002,1643045,1643054-1643055,1643066,1643121,1643128,1643206,1643209-1643210,1643216,1643249,1643270,1643283,1643309-1643310,1643323,1643365-1643366,1643370-1643371,1643465,1643474,1643536,1643570,1643634,1643649,1643651,1643654,1643675,1643731,1643733-1643734,1643761,1643766,1643814,1643937,1643963,1644017,1644169,1644201-1644203,1644321,1644323,1644516,1644523,1644529,1644535,1644730,1644768,1644784-1644785,1644790,1644793,1644815,1644884,1644886,1644890,1644892
,1644910,1644924,1644929-1644930,1644935,1644989,1645011,1645247,1645355,1645357-1645358,1645455,1645465,1645469,1645471,1645473,1645475,1645486-1645488,1645626,1645641,1645685,1645743,1645763,1645951-1645953,1645955,1645993,1646098-1646106,1646178,1646220,1646302,1646304,1646420,1646470-1646471,1646476,1646559,1646717-1646723,1646773,1647026,1647042,1647530,1647655,1648304,1648815,1648907,1649973,1650081,1650365,1651116,1651120,1651280,1651470,1652938,1652970,1653041,1653471,1653550,1653574,1653797,1653815-1653816,1653819,1653840,1653857,1653888,1653972,1654013,1654030,1654050,1654123,1654148,1654159,1654513,1654515,1654517,1654522,1654524,1654725,1654735,1654766,1654785,1654851-1654852,1654978,1655122-1655124,1655126-1655127,1655129-1655130,1655132-1655133,1655312,1655351,1655438,1655441,1655454,1655558,1656087,1656299,1656319,1656331,1656345,1656350,1656590,1656648-1656650,1656657,1657041,1657054,1657374,1657492,1657510,1657565,1657580,1657584,1657586,1657589,1657592,1657607,1657
609,1657682,1657907,1658207,1658734,1658781,1658790,1658799,1658802,1658804,1658833,1658840,1658966,1659043,1659053,1659059,1659188-1659189,1659216,1659263,1659293,1659304,1659306-1659307,1659382,1659384,1659428,1659471,1659486,1659505,1659516,1659521,1659524,1659559,1659562,1659803,1659806,1659814,1659833,1659862,1659905,1659919,1659948,1659967,1659983-1659984,1660060,1660074,1660077,1660133,1660168,1660331-1660332,1660353,1660358,1660924,1661386,1661867,1661972,1661990,1662200,1662308-1662309,1662548,1662614,1662736,1662985,1662988-1662989,1663264,1663277,1663298,1663534,1663562,1663676,1663715,1663754,1663768,1663772,1663781,1663893,1663995,1664143,1664163,1664174,1664301,1664317,1664347,1664657,1664659,1664710,1664863-1664864,1664866,1665085,1665292,1665559,1665653,1665661,1665672,1665694,1665697,1665736,1665779,1665976-1665977,1665980-1665981,1665985-1665986,1665989,1665998,1666004,1666008,1666013,1666017,1666024,1666116,1666386-1666387,1666494,1666496,1666552,1666569,1666579,1
666637,1666649,1666757,1666966,1666972,1666985,1666995,1666997,1667292,1667402,1667406,1667546,1667615,1667630,1667636,1667688,1667764,1667871,1668026,1668135,1668193,1668593,1668596,1668630,1668639,1668843,1669353,1669370,1669451,1669800,1669838,1669876,1669882,1670394,1670433,1670591,1670598-1670600,1670610,1670631,1670719,1670724,1670726,1670730,1670940,1671112,1672272,1672284,1673754,1674294,1675461,1675486,1675594,1675830,1676231,1676250-1676251,1676364,1676381,1676393,1676479,1676525,1676552,1676615,1676630,1676634,1676721,1676926,1676943,1677140,1677802,1678011,1678162,1678174,1678339,1678426-1678427,1678694,1678701,1679534,1679708,1679710,1679716,1680034,1680246,1681056,1681123,1681138,1681280,1681283,1681286,1681450,1681697,1681701,1681729,1681770,1681779,1681793,1681807,1681837-1681838,1681854,1681862,1681958,1682028,1682033,1682311,1682315,1682317,1682320,1682324,1682330,1682842,1684172,1684366,1684383,1684526-1684527,1684549-1684550,1685556,1685591,1685739,1685744,168577
2,1685816,1685826,1685891,1687242,1687261,1687268,1687340,1688563,1688841,1688878,1688885,1688896,1688901,1689345-1689346,1689357,1689656,1689675-1689677,1689679,1689687,1689825,1689856,1689918,1690011,1690021,1690054,1690080,1690209,1691134,1691487,1691813,1692744-1692747,1692849,1693088,1693105,1693429,1693461,1694058,1694111,1694290,1694501,1694548,1694658,1694660,1694788,1694872,1694878,1695006,1695354,1695371,1695379,1695459,1695582,1695706,1695778,1696199,1696272,1696280,1696366-1696368,1696378,1696390,1696392,1696467,1698212,1698220,1700607,1700870,1700896,1700977,1701093,1701123,1701213,1701607,1701666,1701673,1701760-1701761,1701765,1701940,1702092,1702183,1702244,1702246,1702250,1702268,1702313,1702531,1702630-1702635,1702637-1702638,1702640,1702647,1702660,1702662,1702665-1702666,1702668,1702671-1702673,1702675-1702676,1702680,1702722,1702778,1702795,1702862,1702881,1702886,1702910,1702923,1702971,1702984,1703024,1703040,1703044,1703049-1703050,1703143,1703146,1703151,170
3160,1703164,1703167,1703174,1703192,1703287,1703290,1703358,1703408,1703486,1703509,1703523,1703542,1703545,1703554,1703584,1703673,1703676,1703678,1703680,1703763,1703784,1703821,1703842,1703849,1703851,1703853,1703856,1703860,1703865,1703890,1703948,1704149,1704151,1704251,1704278,1704289,1704302,1704305,1704307,1704318,1704331,1704647,1704658,1704689,1704702,1704706,1704711,1704730-1704733,1704735,1704739,1704741-1704742,1704744,1704786,1704867,1705231,1705630,1705635,1705639,1705647,1705650-1705652,1705842,1705848,1705865-1705866,1705942,1706017,1706744-1706745,1706853,1706915,1707052,1707088,1708500-1708501,1708504-1708505,1708570,1708649,1708687,1708745,1708957,1709120,1709266,1709295,1709375,1709663,1710070,1710134,1710341,1710346,1710441,1710445,1710489,1710517,1710523,1710571,1710577,1710632,1710676,1710689,1710753-1710754,1710779,1710924,1711006,1711016,1711022,1711026
+/tomcat/trunk:1636524,1637156,1637176,1637188,1637331,1637684,1637695,1638720-1638725,1639653,1640010,1640083-1640084,1640088,1640275,1640322,1640347,1640361,1640365,1640403,1640410,1640652,1640655-1640658,1640688,1640700-1640883,1640903,1640976,1640978,1641000,1641026,1641038-1641039,1641051-1641052,1641058,1641064,1641300,1641369,1641374,1641380,1641486,1641634,1641656-1641692,1641704,1641707-1641718,1641720-1641722,1641735,1641981,1642233,1642280,1642554,1642564,1642595,1642606,1642668,1642679,1642697,1642699,1642766,1643002,1643045,1643054-1643055,1643066,1643121,1643128,1643206,1643209-1643210,1643216,1643249,1643270,1643283,1643309-1643310,1643323,1643365-1643366,1643370-1643371,1643465,1643474,1643536,1643570,1643634,1643649,1643651,1643654,1643675,1643731,1643733-1643734,1643761,1643766,1643814,1643937,1643963,1644017,1644169,1644201-1644203,1644321,1644323,1644516,1644523,1644529,1644535,1644730,1644768,1644784-1644785,1644790,1644793,1644815,1644884,1644886,1644890,1644892
,1644910,1644924,1644929-1644930,1644935,1644989,1645011,1645247,1645355,1645357-1645358,1645455,1645465,1645469,1645471,1645473,1645475,1645486-1645488,1645626,1645641,1645685,1645743,1645763,1645951-1645953,1645955,1645993,1646098-1646106,1646178,1646220,1646302,1646304,1646420,1646470-1646471,1646476,1646559,1646717-1646723,1646773,1647026,1647042,1647530,1647655,1648304,1648815,1648907,1649973,1650081,1650365,1651116,1651120,1651280,1651470,1652938,1652970,1653041,1653471,1653550,1653574,1653797,1653815-1653816,1653819,1653840,1653857,1653888,1653972,1654013,1654030,1654050,1654123,1654148,1654159,1654513,1654515,1654517,1654522,1654524,1654725,1654735,1654766,1654785,1654851-1654852,1654978,1655122-1655124,1655126-1655127,1655129-1655130,1655132-1655133,1655312,1655351,1655438,1655441,1655454,1655558,1656087,1656299,1656319,1656331,1656345,1656350,1656590,1656648-1656650,1656657,1657041,1657054,1657374,1657492,1657510,1657565,1657580,1657584,1657586,1657589,1657592,1657607,1657
609,1657682,1657907,1658207,1658734,1658781,1658790,1658799,1658802,1658804,1658833,1658840,1658966,1659043,1659053,1659059,1659188-1659189,1659216,1659263,1659293,1659304,1659306-1659307,1659382,1659384,1659428,1659471,1659486,1659505,1659516,1659521,1659524,1659559,1659562,1659803,1659806,1659814,1659833,1659862,1659905,1659919,1659948,1659967,1659983-1659984,1660060,1660074,1660077,1660133,1660168,1660331-1660332,1660353,1660358,1660924,1661386,1661867,1661972,1661990,1662200,1662308-1662309,1662548,1662614,1662736,1662985,1662988-1662989,1663264,1663277,1663298,1663534,1663562,1663676,1663715,1663754,1663768,1663772,1663781,1663893,1663995,1664143,1664163,1664174,1664301,1664317,1664347,1664657,1664659,1664710,1664863-1664864,1664866,1665085,1665292,1665559,1665653,1665661,1665672,1665694,1665697,1665736,1665779,1665976-1665977,1665980-1665981,1665985-1665986,1665989,1665998,1666004,1666008,1666013,1666017,1666024,1666116,1666386-1666387,1666494,1666496,1666552,1666569,1666579,1
666637,1666649,1666757,1666966,1666972,1666985,1666995,1666997,1667292,1667402,1667406,1667546,1667615,1667630,1667636,1667688,1667764,1667871,1668026,1668135,1668193,1668593,1668596,1668630,1668639,1668843,1669353,1669370,1669451,1669800,1669838,1669876,1669882,1670394,1670433,1670591,1670598-1670600,1670610,1670631,1670719,1670724,1670726,1670730,1670940,1671112,1672272,1672284,1673754,1674294,1675461,1675486,1675594,1675830,1676231,1676250-1676251,1676364,1676381,1676393,1676479,1676525,1676552,1676615,1676630,1676634,1676721,1676926,1676943,1677140,1677802,1678011,1678162,1678174,1678339,1678426-1678427,1678694,1678701,1679534,1679708,1679710,1679716,1680034,1680246,1681056,1681123,1681138,1681280,1681283,1681286,1681450,1681697,1681701,1681729,1681770,1681779,1681793,1681807,1681837-1681838,1681854,1681862,1681958,1682028,1682033,1682311,1682315,1682317,1682320,1682324,1682330,1682842,1684172,1684366,1684383,1684526-1684527,1684549-1684550,1685556,1685591,1685739,1685744,168577
2,1685816,1685826,1685891,1687242,1687261,1687268,1687340,1688563,1688841,1688878,1688885,1688896,1688901,1689345-1689346,1689357,1689656,1689675-1689677,1689679,1689687,1689825,1689856,1689918,1690011,1690021,1690054,1690080,1690209,1691134,1691487,1691813,1692744-1692747,1692849,1693088,1693105,1693429,1693461,1694058,1694111,1694290,1694501,1694548,1694658,1694660,1694788,1694872,1694878,1695006,1695354,1695371,1695379,1695459,1695582,1695706,1695778,1696199,1696272,1696280,1696366-1696368,1696378,1696390,1696392,1696467,1698212,1698220,1700607,1700870,1700896,1700977,1701093,1701123,1701213,1701607,1701666,1701673,1701760-1701761,1701765,1701940,1702092,1702183,1702244,1702246,1702250,1702268,1702313,1702531,1702630-1702635,1702637-1702638,1702640,1702647,1702660,1702662,1702665-1702666,1702668,1702671-1702673,1702675-1702676,1702680,1702722,1702778,1702795,1702862,1702881,1702886,1702910,1702923,1702971,1702984,1703024,1703040,1703044,1703049-1703050,1703143,1703146,1703151,170
3160,1703164,1703167,1703174,1703192,1703287,1703290,1703358,1703408,1703486,1703509,1703523,1703542,1703545,1703554,1703584,1703673,1703676,1703678,1703680,1703763,1703784,1703821,1703842,1703849,1703851,1703853,1703856,1703860,1703865,1703890,1703948,1704149,1704151,1704251,1704278,1704289,1704302,1704305,1704307,1704318,1704331,1704647,1704658,1704689,1704702,1704706,1704711,1704730-1704733,1704735,1704739,1704741-1704742,1704744,1704786,1704867,1705231,1705630,1705635,1705639,1705647,1705650-1705652,1705842,1705848,1705865-1705866,1705942,1706017,1706744-1706745,1706853,1706915,1707052,1707088,1708500-1708501,1708504-1708505,1708570,1708649,1708687,1708745,1708957,1709120,1709266,1709295,1709375,1709663,1709895,1710070,1710134,1710341,1710346,1710441,1710445,1710489,1710517,1710523,1710571,1710577,1710632,1710676,1710689,1710753-1710754,1710779,1710924,1711006,1711016,1711022,1711026
Modified:
tomcat/tc8.0.x/trunk/java/org/apache/catalina/filters/RestCsrfPreventionFilter.java
URL:
http://svn.apache.org/viewvc/tomcat/tc8.0.x/trunk/java/org/apache/catalina/filters/RestCsrfPreventionFilter.java?rev=1711434&r1=1711433&r2=1711434&view=diff
==============================================================================
---
tomcat/tc8.0.x/trunk/java/org/apache/catalina/filters/RestCsrfPreventionFilter.java
(original)
+++
tomcat/tc8.0.x/trunk/java/org/apache/catalina/filters/RestCsrfPreventionFilter.java
Fri Oct 30 08:59:40 2015
@@ -213,13 +213,12 @@ public class RestCsrfPreventionFilter ex
}
/**
- * Paths accepting request parameters with nonce information are URLs that
- * can supply nonces via request parameter 'X-CSRF-Token'. For use cases
- * when a nonce information cannot be provided via header, one can provide
- * it via request parameters. If there is a X-CSRF-Token header, it will be
- * taken with preference over any parameter with the same name in the
- * request. Request parameters cannot be used to fetch new nonce, only
- * header.
+ * A comma separated list of URLs that can accept nonces via request
+ * parameter 'X-CSRF-Token'. For use cases when a nonce information cannot
+ * be provided via header, one can provide it via request parameters. If
+ * there is a X-CSRF-Token header, it will be taken with preference over
any
+ * parameter with the same name in the request. Request parameters cannot
be
+ * used to fetch new nonce, only header.
*
* @param pathsList
* Comma separated list of URLs to be configured as paths
Modified: tomcat/tc8.0.x/trunk/webapps/docs/changelog.xml
URL:
http://svn.apache.org/viewvc/tomcat/tc8.0.x/trunk/webapps/docs/changelog.xml?rev=1711434&r1=1711433&r2=1711434&view=diff
==============================================================================
--- tomcat/tc8.0.x/trunk/webapps/docs/changelog.xml (original)
+++ tomcat/tc8.0.x/trunk/webapps/docs/changelog.xml Fri Oct 30 08:59:40 2015
@@ -121,7 +121,11 @@
valves provided by Tomcat. The API is available since Servlet
specification 3.1. (violetagg)
</fix>
- </changelog>
+ <add>
+ Add a new RestCsrfPreventionFilter that provides basic CSRF protection
+ for REST APIs. (violetagg)
+ </add>
+ </changelog>
</subsection>
<subsection name="Coyote">
<changelog>
Modified: tomcat/tc8.0.x/trunk/webapps/docs/config/filter.xml
URL:
http://svn.apache.org/viewvc/tomcat/tc8.0.x/trunk/webapps/docs/config/filter.xml?rev=1711434&r1=1711433&r2=1711434&view=diff
==============================================================================
--- tomcat/tc8.0.x/trunk/webapps/docs/config/filter.xml (original)
+++ tomcat/tc8.0.x/trunk/webapps/docs/config/filter.xml Fri Oct 30 08:59:40 2015
@@ -310,6 +310,161 @@
</section>
+<section name="CSRF Prevention Filter for REST APIs">
+
+ <subsection name="Introduction">
+
+ <p>This filter provides basic CSRF protection for REST APIs. The CSRF
+ protection is applied only for modifying HTTP requests (different from GET,
+ HEAD, OPTIONS) to protected resources. It is based on a custom header
+ <code>X-CSRF-Token</code> that provides a valid nonce.</p>
+
+ <p>CSRF protection mechanism for REST APIs consists of the following steps:
+ <ul>
+ <li>Client asks for a valid nonce. This is performed with a
+ non-modifying "Fetch" request to protected resource.</li>
+ <li>Server responds with a valid nonce mapped to the current user
+ session.</li>
+ <li>Client provides this nonce in the subsequent modifying requests in
+ the frame of the same user session.</li>
+ <li>Server rejects all modifying requests to protected resources that
+ do not contain a valid nonce.</li>
+ </ul>
+ </p>
+
+ </subsection>
+
+ <subsection name="Basic configuration sample">
+
+ <p>On the server side</p>
+
+ <ul>
+ <li>All CSRF protected REST APIs should be protected with an
authentication
+ mechanism.</li>
+ <li>Protect modifying REST APIs with this filter.</li>
+ <li>Provide at least one non-modifying operation.</li>
+ </ul>
+ <source><![CDATA[<filter>
+ <filter-name>RestCSRF</filter-name>
+
<filter-class>org.apache.catalina.filters.RestCsrfPreventionFilter</filter-class>
+</filter>
+<filter-mapping>
+ <filter-name>RestCSRF</filter-name>
+ <!-- Modifying operations -->
+ <url-pattern>/resources/removeResource</url-pattern>
+ <url-pattern>/resources/addResource</url-pattern>
+ <!-- Non-modifying operations -->
+ <url-pattern>/resources/listResources</url-pattern>
+</filter-mapping>]]></source>
+
+ <p>On the client side</p>
+
+ <ul>
+ <li>Make a non-modifying "Fetch" request in order to obtain a valid
nonce.
+ This can be done with sending additional header
+ <code>X-CSRF-Token: Fetch</code></li>
+ <li>Cache the returned session id and nonce in order to provide them in
+ the subsequent modifying requests to protected resources.</li>
+ <li>Modifying requests can be denied and header
+ <code>X-CSRF-Token: Required</code> will be returned in case of
+ invalid or missing nonce, expired session or in case the session
+ id is changed by the server.</li>
+ </ul>
+ <source><![CDATA[Client Request:
+GET /rest/resources/listResources HTTP/1.1
+X-CSRF-Token: Fetch
+Authorization: Basic ...
+Host: localhost:8080
+...
+
+Server Response:
+HTTP/1.1 200 OK
+Set-Cookie: JSESSIONID=...; Path=/rest; HttpOnly
+X-CSRF-Token: ...
+...
+
+Client Request:
+POST /rest/resources/addResource HTTP/1.1
+Cookie: JSESSIONID=...
+X-CSRF-Token: ...
+Authorization: Basic ...
+Host: localhost:8080
+...
+
+Server Response:
+HTTP/1.1 200 OK
+...]]></source>
+
+ </subsection>
+
+ <subsection name="RestCsrfPreventionFilter and HttpServletRequest
parameters">
+
+ <p>When the client is not able to insert custom headers in its calls to
+ REST APIs there is additional capability to configure URLs for which a
+ valid nonce will be accepted as a request parameter.</p>
+
+ <p>Note: If there is a <code>X-CSRF-Token</code> header, it will be taken
+ with preference over any parameter with the same name in the request.
+ Request parameters cannot be used to fetch new nonce, only header can be
+ used to request a new nonce.</p>
+
+ <source><![CDATA[<filter>
+ <filter-name>RestCSRF</filter-name>
+
<filter-class>org.apache.catalina.filters.RestCsrfPreventionFilter</filter-class>
+ <init-param>
+ <param-name>pathsAcceptingParams</param-name>
+ <param-value>/resources/removeResource,/resources/addResource</param-value>
+ </init-param>
+</filter>
+<filter-mapping>
+ <filter-name>RestCSRF</filter-name>
+ <url-pattern>/resources/*</url-pattern>
+</filter-mapping>]]></source>
+
+ </subsection>
+
+ <subsection name="Filter Class Name">
+
+ <p>The filter class name for the CSRF Prevention Filter for REST APIs is
+ <strong><code>org.apache.catalina.filters.RestCsrfPreventionFilter</code>
+ </strong>.</p>
+
+ </subsection>
+
+ <subsection name="Initialisation parameters">
+
+ <p>The CSRF Prevention Filter for REST APIs supports the following
+ initialisation parameters:</p>
+
+ <attributes>
+
+ <attribute name="denyStatus" required="false">
+ <p>HTTP response status code that is used when rejecting denied
+ request. The default value is <code>403</code>.</p>
+ </attribute>
+
+ <attribute name="pathsAcceptingParams" required="false">
+ <p>A comma separated list of URLs that can accept nonces via request
+ parameter <code>X-CSRF-Token</code>. For use cases when a nonce
information cannot
+ be provided via header, one can provide it via request parameters. If
+ there is a <code>X-CSRF-Token</code> header, it will be taken with
preference over
+ any parameter with the same name in the request. Request parameters
+ cannot be used to fetch new nonce, only header can be used to request a
+ new nonce.</p>
+ </attribute>
+
+ <attribute name="randomClass" required="false">
+ <p>The name of the class to use to generate nonces. The class must be
an
+ instance of <code>java.util.Random</code>. If not set, the default
value
+ of <code>java.security.SecureRandom</code> will be used.</p>
+ </attribute>
+
+ </attributes>
+
+ </subsection>
+
+</section>
+
<section name="Expires Filter">
<subsection name="Introduction">
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@tomcat.apache.org
For additional commands, e-mail: dev-h...@tomcat.apache.org
