svn commit: r1640346 - /wicket/common/site/trunk/_site/guide/guide/src/docs/guide/security/security_4.gdoc

[mg...@apache.org]

Author: mgrigorov
Date: Tue Nov 18 13:53:52 2014
New Revision: 1640346

URL: http://svn.apache.org/r1640346
Log:
Update the documentation about CryptoMapper and KeyInSessionSunJceCryptFactory.


Modified:
    wicket/common/site/trunk/_site/guide/guide/src/docs/guide/security/security_4.gdoc

Modified: wicket/common/site/trunk/_site/guide/guide/src/docs/guide/security/security_4.gdoc
URL: http://svn.apache.org/viewvc/wicket/common/site/trunk/_site/guide/guide/src/docs/guide/security/security_4.gdoc?rev=1640346&r1=1640345&r2=1640346&view=diff
==============================================================================
--- wicket/common/site/trunk/_site/guide/guide/src/docs/guide/security/security_4.gdoc (original)
+++ wicket/common/site/trunk/_site/guide/guide/src/docs/guide/security/security_4.gdoc Tue Nov 18 13:53:52 2014
@@ -1,4 +1,4 @@
-In chapter [10.6|guide:urls_6] we have seen how to use encryted URLs using mapper @CryptoMapper@. To encrypt/decrypt page URLs @CryptoMapper@ uses an instance of interface @org.apache.wicket.util.crypt.ICrypt@:
+In chapter [10.6|guide:urls_6] we have seen how to encrypt URLs using @CryptoMapper@ request mapper. To encrypt/decrypt page URLs @CryptoMapper@ uses an instance of @org.apache.wicket.util.crypt.ICrypt@ interface:
 
 {code}
 public interface ICrypt
@@ -6,14 +6,24 @@ public interface ICrypt
 	String encryptUrlSafe(final String plainText);
 
 	String decryptUrlSafe(final String encryptedText);
+
+	...
 }
 {code}
 
-The default implementation for this interface is class @org.apache.wicket.util.crypt.SunJceCrypt@ which provides password-based cryptography and is adopted by @CryptoMapper@ when we use its constructor @CryptoMapper(IRequestMapper wrappedMapper, Application application)@. As we hinted at the end of chapter [10.6|guide:urls_6], this constructor alone might not provide enough security for our application. To strengthen the cryptography mechanism used by @CryptoMapper@ we have two possible options.
-The first (and more obvious) is to use constructor @CryptoMapper(IRequestMapper wrappedMapper, IProvider<ICrypt> cryptProvider)@ and give it an implementation of @org.apache.wicket.util.IProvider@ that returns a custom @org.apache.wicket.util.crypt.ICrypt@. 
+The default implementation for this interface is class @org.apache.wicket.util.crypt.SunJceCrypt@. It provides password-based cryptography using @PBEWithMD5AndDES@ algorithm coming with the standard security providers in the Java Runtime Environment.
+
+{note}
+For better security it is recommended to install Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction [Policy Files|http://www.oracle.com/technetwork/java/javase/downloads/jce-7-download-432124.html] for your version of JDK/JRE and use stronger algorithms. See this [example|https://github.com/apache/wicket/blob/42ce1faa57d3617ccaa443045537306fabf4d71a/wicket-util/src/test/java/org/apache/wicket/util/crypt/UnlimitedStrengthJurisdictionPolicyTest.java#L67] of a custom @ICrypt@ implementation for inspiration.
+{note}
+
+By using @CryptoMapper(IRequestMapper wrappedMapper, Application application)@ constructor the mapper will use the configured @org.apache.wicket.util.crypt.ICryptFactory@ from @org.apache.wicket.settings.ISecuritySettings#getCryptFactory()@. To use a stronger cryptography mechanism there are the following options:
+
+* The first option is to use constructor @CryptoMapper(IRequestMapper wrappedMapper, IProvider<ICrypt> cryptProvider)@ and give it an implementation of @org.apache.wicket.util.IProvider@ that returns a custom @org.apache.wicket.util.crypt.ICrypt@. 
 
 {note}
 @org.apache.wicket.util.IProvider@ is a single-method interface that acts as object supplier:
+{note}
 
 {code}
 public interface IProvider<T>
@@ -22,19 +32,23 @@ public interface IProvider<T>
 }
 {code}
 
-{note}
-
-The second option we have to strengthen URLs encryption is to register a cipher factory at application level with method @setCryptFactory(ICryptFactory cryptFactory)@ of interface @ISecuritySettings@:
+* The second option is to register a cipher factory at application level with method @setCryptFactory(ICryptFactory cryptFactory)@ of interface @ISecuritySettings@:
 
 {code}
 @Override
 public void init() {
 	super.init();
-	getSecuritySettings().setCryptFactory(new KeyInSessionSunJceCryptFactory());
+	getSecuritySettings().setCryptFactory(new SomeCryptFactory());
 	setRootRequestMapper(new CryptoMapper(getRootRequestMapper(), this));
 }
 {code}
 
 
-This cipher factory is used by @CryptoMapper@ when we instantiate it with the first contructor we have seen. Cipher factories are implementations of interface @org.apache.wicket.util.crypt.ICryptFactory@.
-Class @org.apache.wicket.core.util.crypt.KeyInSessionSunJceCryptFactory@ is a built-in cipher factory that generates a separate key for each user and stores it in the HTTP session. This factory offers a stronger URLs encryption and can help to protect our application against [CSRF|https://www.owasp.org/index.php/Cross-Site_Request_Forgery_(CSRF)] attacks.  
+Since version 6.19.0 Wicket uses @org.apache.wicket.core.util.crypt.KeyInSessionSunJceCryptFactory@ as a default factory for @ICrypt@ objects. This factory generates a unique key for each user that is stored in her HTTP 
+session. This way it helps to protect the application against [CSRF|https://www.owasp.org/index.php/Cross-Site_Request_Forgery_(CSRF)] attacks - the <form> action url will be encrypted in such way that it will be unique
+for each user of the application. The url itself serves as [encrypted token|https://www.owasp.org/index.php/Cross-Site_Request_Forgery_(CSRF)_Prevention_Cheat_Sheet#Encrypted_Token_Pattern].
+
+{warning}
+@org.apache.wicket.core.util.crypt.KeyInSessionSunJceCryptFactory@ binds the http session if it is not already bound! If the application needs to run in stateless mode then the application will have to provide a custom 
+implementation of @ICryptFactory@ that stores the user specific keys by other means.
+{warning}