CryptoMapper (Wicket Parent 8.15.0-SNAPSHOT API)

java.lang.Object
- org.apache.wicket.core.request.mapper.CryptoMapper

All Implemented Interfaces:

IRequestMapper, IRequestMapperDelegate
```
public class CryptoMapper
extends Object
implements IRequestMapperDelegate
```
A request mapper that encrypts URLs generated by another mapper. This mapper encrypts the segments and query parameters of URLs starting with IMapperContext.getNamespace(), and just the PageComponentInfo parameter for mounted URLs.

Important: for better security it is recommended to use CryptoMapper(IRequestMapper, Supplier) constructor with ICrypt implementation that generates a separate key for each user. KeyInSessionSunJceCryptFactory provides such an implementation that stores the key in the HTTP session.

This mapper can be mounted before or after mounting other pages, but will only encrypt URLs for pages mounted before the CryptoMapper. If required, multiple CryptoMappers may be installed in an Application.

When encrypting URLs in the Wicket namespace (starting with IMapperContext.getNamespace()), the entire URL, including segments and parameters, is encrypted, with the encrypted form stored in the first segment of the encrypted URL.

To be able to handle relative URLs, like for image URLs in a CSS file, checksum segments are appended to the encrypted URL until the encrypted URL has the same number of segments as the original URL had. Each checksum segment has a precise 5 character value, calculated using a checksum. This helps in calculating the relative distance from the original URL. When a URL is returned by the browser, we iterate through these checksummed placeholder URL segments. If the segment matches the expected checksum, then the segment is deemed to be the corresponding segment in the original URL. If the segment does not match the expected checksum, then the segment is deemed a plain text sibling of the corresponding segment in the original URL, and all subsequent segments are considered plain text children of the current segment.

When encrypting mounted URLs, we look for the PageComponentInfo parameter, and encrypt only that parameter.

CryptoMapper can be configured to mark encrypted URLs as encrypted, and throw a PageExpiredException exception if a encrypted URL cannot be decrypted. This can occur when using KeyInSessionSunJceCryptFactory, and the session has expired.

Author:

igor.vaynberg, Jesse Long, svenmeier

See Also:

SecuritySettings.setCryptFactory(org.apache.wicket.util.crypt.ICryptFactory), KeyInSessionSunJceCryptFactory, SunJceCrypt

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class CryptoMapper.HashedSegmentGenerator
A generator of hashed segments.

Nested Classes
Modifier and Type	Class and Description
`static class`	`CryptoMapper.HashedSegmentGenerator` A generator of hashed segments.

Constructor Summary

Constructors
Constructor and Description
`CryptoMapper(IRequestMapper wrappedMapper, Application application)` Encrypt with `SecuritySettings.getCryptFactory()`.
`CryptoMapper(IRequestMapper wrappedMapper, Supplier<ICrypt> cryptProvider)` Construct.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`protected Url`	`decryptEntireUrl(Request request, Url encryptedUrl)` Decrypts an entire URL, which was previously encrypted by `encryptEntireUrl(org.apache.wicket.request.Url)`.
`protected Url`	`decryptRequestListenerParameter(Request request, Url encryptedUrl)` Decrypts a URL which may contain an encrypted `PageComponentInfo` query parameter.
`protected Url`	`decryptUrl(Request request, Url encryptedUrl)` Decrypts a `Url`.
`protected Url`	`encryptEntireUrl(Url url)` Encrypts an entire URL, segments and query parameters.
`protected Url`	`encryptRequestListenerParameter(Url url)` Encrypts the `PageComponentInfo` query parameter in the URL, if any is found.
`protected Url`	`encryptUrl(Url url)` Encrypts a URL.
`int`	`getCompatibilityScore(Request request)` Returns the score representing how compatible this request mapper is to processing the given request.
`protected IMapperContext`	`getContext()` Returns the applications `IMapperContext`.
`protected ICrypt`	`getCrypt()`
`IRequestMapper`	`getDelegateMapper()` Returns the delegate `IRequestMapper`.
`boolean`	`getMarkEncryptedUrls()` Whether or not to mark encrypted URLs as encrypted.
`Url`	`mapHandler(IRequestHandler requestHandler)` Returns the `Url` for given `IRequestHandler` or `null` if the request handler is not recognized.
`IRequestHandler`	`mapRequest(Request request)` Returns `IRequestHandler` for the request or `null` if the `Url` is not recognized.
`CryptoMapper`	`setMarkEncryptedUrls(boolean markEncryptedUrls)` Sets whether or not to mark encrypted URLs as encrypted.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - CryptoMapper
```
public CryptoMapper(IRequestMapper wrappedMapper,
                    Application application)
```
    Encrypt with SecuritySettings.getCryptFactory().
    Important: Encryption is done with SecuritySettings.DEFAULT_ENCRYPTION_KEY if you haven't configured an alternative ICryptFactory. For better security it is recommended to use CryptoMapper(IRequestMapper, Supplier) with a specific ICrypt implementation that generates a separate key for each user. KeyInSessionSunJceCryptFactory provides such an implementation that stores the key in the HTTP session.
    
    Parameters:
    
    wrappedMapper - the non-crypted request mapper
    
    application - the current application
    
    See Also:
    
    SunJceCrypt
  - CryptoMapper
```
public CryptoMapper(IRequestMapper wrappedMapper,
                    Supplier<ICrypt> cryptProvider)
```
    Construct.
    
    Parameters:
    
    wrappedMapper - the non-crypted request mapper
    
    cryptProvider - the custom crypt provider
- Method Detail
  - getMarkEncryptedUrls
```
public boolean getMarkEncryptedUrls()
```
    Whether or not to mark encrypted URLs as encrypted. If set, a PageExpiredException is thrown when a encrypted URL can no longer be decrypted.
    
    Returns:
    
    whether or not to mark encrypted URLs as encrypted.
  - setMarkEncryptedUrls
```
public CryptoMapper setMarkEncryptedUrls(boolean markEncryptedUrls)
```
    Sets whether or not to mark encrypted URLs as encrypted. If set, a PageExpiredException is thrown when a encrypted URL can no longer be decrypted.
    
    Parameters:
    
    markEncryptedUrls - whether or not to mark encrypted URLs as encrypted.
    
    Returns:
    
    this, for chaining.
  - getCompatibilityScore
```
public int getCompatibilityScore(Request request)
```
    Returns the score representing how compatible this request mapper is to processing the given request. When a request comes in all mappers are scored and are tried in order from highest score to lowest.
    A good criteria for calculating the score is the number of matched url segments. For example when there are two mappers for a mounted page, one mapped to /foo another to /foo/bar and the incoming request URL is /foo/bar/baz, the mapping to /foo/bar should probably handle the request first as it has matching segments count of 2 while the first one has only matching segments count of 1.
    Note that the method can return value greater then zero even if the mapper does not recognize the request.
    This implementation decrypts the URL and passes the decrypted URL to the wrapped mapper.
    
    Specified by:
    
    getCompatibilityScore in interface IRequestMapper
    
    Parameters:
    
    request - The request for which to get a compatibility score.
    
    Returns:
    
    The compatibility score.
  - mapHandler
```
public Url mapHandler(IRequestHandler requestHandler)
```
    Description copied from interface: IRequestMapper
    
    Returns the Url for given IRequestHandler or null if the request handler is not recognized.
    
    Specified by:
    
    mapHandler in interface IRequestMapper
    
    Returns:
    
    Url instance or null.
  - mapRequest
```
public IRequestHandler mapRequest(Request request)
```
    Description copied from interface: IRequestMapper
    
    Returns IRequestHandler for the request or null if the Url is not recognized.
    
    Specified by:
    
    mapRequest in interface IRequestMapper
    
    Parameters:
    
    request - provides access to request data (i.e. Url and Parameters)
    
    Returns:
    
    RequestHandler instance or null
  - getCrypt
```
protected final ICrypt getCrypt()
```
    Returns:
    
    the ICrypt implementation that may be used to encrypt/decrypt Url's segments and/or query string
  - getDelegateMapper
```
public final IRequestMapper getDelegateMapper()
```
    Description copied from interface: IRequestMapperDelegate
    
    Returns the delegate IRequestMapper.
    
    Specified by:
    
    getDelegateMapper in interface IRequestMapperDelegate
    
    Returns:
    
    the wrapped root request mapper
  - getContext
```
protected IMapperContext getContext()
```
    Returns the applications IMapperContext.
    
    Returns:
    
    The applications IMapperContext.
  - encryptUrl
```
protected Url encryptUrl(Url url)
```
    Encrypts a URL. This method should return a new, encrypted instance of the URL. If the URL starts with /wicket/, the entire URL is encrypted.
    
    Parameters:
    
    url - The URL to encrypt.
    
    Returns:
    
    A new, encrypted version of the URL.
  - encryptEntireUrl
```
protected Url encryptEntireUrl(Url url)
```
    Encrypts an entire URL, segments and query parameters.
    
    Parameters:
    
    url - The URL to encrypt.
    
    Returns:
    
    An encrypted form of the URL.
  - encryptRequestListenerParameter
```
protected Url encryptRequestListenerParameter(Url url)
```
    Encrypts the PageComponentInfo query parameter in the URL, if any is found.
    
    Parameters:
    
    url - The URL to encrypt.
    
    Returns:
    
    An encrypted form of the URL.
  - decryptUrl
```
protected Url decryptUrl(Request request,
                         Url encryptedUrl)
```
    Decrypts a Url. This method should return null if the URL is not decryptable, or if the URL should have been encrypted but was not. Returning null results in a 404 error.
    
    Parameters:
    
    request - The Request.
    
    encryptedUrl - The encrypted Url.
    
    Returns:
    
    Returns a decrypted Url.
  - decryptEntireUrl
```
protected Url decryptEntireUrl(Request request,
                               Url encryptedUrl)
```
    Decrypts an entire URL, which was previously encrypted by encryptEntireUrl(org.apache.wicket.request.Url). This method should return null if the URL is not decryptable.
    
    Parameters:
    
    request - The request that was made.
    
    encryptedUrl - The encrypted URL.
    
    Returns:
    
    A decrypted form of the URL, or null if the URL is not decryptable.
  - decryptRequestListenerParameter
```
protected Url decryptRequestListenerParameter(Request request,
                                              Url encryptedUrl)
```
    Decrypts a URL which may contain an encrypted PageComponentInfo query parameter.
    
    Parameters:
    
    request - The request that was made.
    
    encryptedUrl - The (potentially) encrypted URL.
    
    Returns:
    
    A decrypted form of the URL.

Class CryptoMapper

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

CryptoMapper

CryptoMapper

Method Detail

getMarkEncryptedUrls

setMarkEncryptedUrls

getCompatibilityScore

mapHandler

mapRequest

getCrypt

getDelegateMapper

getContext

encryptUrl

encryptEntireUrl

encryptRequestListenerParameter

decryptUrl

decryptEntireUrl

decryptRequestListenerParameter