Setup

Hdiv configuration is based on Spring and uses its XML and JavaConfig files.

In XML mode, Hdiv has a custom schema that contains all configuration options. First of all, we need an XML file which is commonly named hdiv-config.xml.

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:hdiv="http://www.hdiv.org/schema/hdiv"
       xsi:schemaLocation="http://www.springframework.org/schema/beans
                           http://www.springframework.org/schema/beans/spring-beans.xsd
                           http://www.hdiv.org/schema/hdiv http://www.hdiv.org/schema/hdiv/hdiv.xsd"/>

From Hdiv version 2.1.7, it is possible to configure Hdiv in Java instead of XML.

Example configuration:

@Configuration_
@EnableHdivWebSecurity_
public class HdivSecurityConfig extends HdivWebSecurityConfigurerAdapter {

    @Override
    public void configure(SecurityConfigBuilder builder) {
        // Configuration options
    }

}

For an example application showing this feature click here

In the case of Grails framework, the configuration is realized through Config.groovy file updating Hdiv plugin configuration options.

Configuration options

Start Pages

By default, the Hdiv filter does not allow any request that has not been registered previously. However, when a user accesses for the first time, it is not possible to register the resource (url) requested by the user, so in this case Hdiv uses the concept of startpages - URLs to which Hdiv makes no validation. We can see a startpage as the homepage of a website.

Note that Hdiv is usually applied only to authenticated parts of the webpage.

This example shows the configuration code to define a startpage to access the homepage of a website.

<hdiv:config>
    <hdiv:startPages>/home.html</hdiv:startPages>
</hdiv:config>

In JavaConfig mode:

@Configuration
@EnableHdivWebSecurity
public class HdivSecurityConfig extends HdivWebSecurityConfigurerAdapter {

    @Override
    public void addExclusions(ExclusionRegistry registry) {
        registry.addUrlExclusions("/home.html").method("GET");
    }

}

For Grails users update Config.groovy file:

grails {
    plugin {
        hdiv {
            config {
                startPages = [GET: '/home.html']
            }
        }
    }
}

Text fields validation

Hdiv offers a generic validation feature, applying validation rules to all data generated in text fields data sent by the client. This includes information that comes from web form fields such as textbox and textarea.

Hdiv includes a default group of validation rules that try to avoid the most common risks such as XSS and SQL Injection.

In order to activate Hdiv text fields validation (also know as Editable validation) with the default configuration, it is necessary to add the code below to your Spring configuration:

<hdiv:editableValidations registerDefaults="true">
</hdiv:editableValidations>

In addition to the default validations, it is possible to create your own custom validations. First, it is necessary to create a validation entity, which could contain two kinds of patterns:

  • AcceptedPattern : the parameter value must match the pattern (whitelist), otherwise Hdiv generates an error message that is visible within the original form. It is also possible to redirect the user to Hdiv's generic error page. For this option add showErrorPageOnEditableValidation="true" to Hdiv config.

  • RejectedPattern if the parameter value matches the defined pattern (blacklist), Hdiv generates an error that is visible within the original form or the Hdiv generic error page.

In order to create a validation it is necessary to create a validation entity within Hdiv config file:

<hdiv:validation id="customValidation" componentType="text">
    <hdiv:acceptedPattern><![CDATA[^[a-zA-Z0-9@.\-_]*$]]></hdiv:acceptedPattern>
    <hdiv:rejectedPattern><![CDATA[(\s|\S)*(--)(\s|\S)*]]></hdiv:rejectedPattern>
</hdiv:validation>

Once validation has been defined, an additional step is needed to activate it. To do this, add a validation rule to the editableValidations entity. The validation rule is applied to a specific url pattern. Here is an example to apply the validation as defined above:

<hdiv:editableValidations registerDefaults="true">
    <hdiv:validationRule url=".*" enableDefaults="true">customValidation</hdiv:validationRule>
</hdiv:editableValidations>

All text fields are validated by default. It is possible to refine the configuration to apply selected rules to only some fields. In the next example the customValidation rule is applied only to name and description fields:

<hdiv:editableValidations registerDefaults="true">
    <hdiv:validationRule url="/example/form.html" parameters="name, description">customValidation</hdiv:validationRule>
</hdiv:editableValidations>

In JavaConfig mode:

@Configuration
@EnableHdivWebSecurity
public class HdivSecurityConfig extends HdivWebSecurityConfigurerAdapter {

    @Override
    public void addRules(RuleRegistry registry) {
        registry.addRule("customValidation").acceptedPattern("^[a-zA-Z0-9@.\\-_]*$");
    }

    @Override
    public void configureEditableValidation(ValidationConfigurer validationConfigurer) {
        validationConfigurer.addValidation(".*").rules("customValidation");
    }

}

For Grails framework, this configuration must be included within Config.groovy file. The following code shows the validations defined within the Hdiv and Grails reference application:

grails {
    plugin {
        hdiv {

            config { ...
            }

            validations = [[id: 'safeText', acceptedPattern: '^[a-zA-Z0-9@.\\-_]*$']]

            editableValidations = [
                [id: 'editableParametersValidations', registerDefaults: true,
                 validationRules: [[url: '/secure/.*', enableDefaults: true,  validationIds: 'safeText'],
                                   [url: '/safetext/.*', enableDefaults: false, validationIds: 'safeText']]
                ]
            ]
        }
    }
}

Start Parameters

By default, the Hdiv filter does not allow any request parameter which has not been registered previously. In some cases, parameters are not created on the server side or they have a random value, in which case they are incorporated as parameter names, for which Hdiv makes no kind of validation.

The following shows the configuration code to define a start parameter.

<hdiv:config>
    <hdiv:startParameters>paramName</hdiv:startParameters>
</hdiv:config>

In JavaConfig mode:

@Configuration
@EnableHdivWebSecurity
public class HdivSecurityConfig extends HdivWebSecurityConfigurerAdapter {

    @Override
    public void addExclusions(ExclusionRegistry registry) {
        registry.addParamExclusions("paramName");
    }

}

In the examples above, the parameter is not validated throughout the application. If we want to prevent validation in only some pages, there is another configuration option.

<hdiv:config>
    <hdiv:paramsWithoutValidation>
        <hdiv:mapping url="/section/.*" parameters="paramName"/>
    </hdiv:paramsWithoutValidation>
</hdiv:config>

In JavaConfig mode:

@Configuration
@EnableHdivWebSecurity
public class HdivSecurityConfig extends HdivWebSecurityConfigurerAdapter {

    @Override
    public void addExclusions(ExclusionRegistry registry) {
        registry.addParamExclusions("paramName").forUrls("/section/.*");;
    }

}

Session expiration

When a user makes a request to an expired web session, Hdiv adds the option of redirecting the user to the loginPage instead of showing Hdiv error pages.

If the web session has not expired but the page's state has been removed from the session, the user is redirected to the homePage to continue browsing without showing the error page.

In this case the following can be used:

<hdiv:sessionExpired loginPage="/login.html" homePage="/"/>

In JavaConfig mode:

@Configuration
@EnableHdivWebSecurity
public class HdivSecurityConfig extends HdivWebSecurityConfigurerAdapter {

    @Override
    public void configure(SecurityConfigBuilder builder) {
        builder.sessionExpired().homePage("/").loginPage("/login.html");
    }

}

Execution strategy

Hdiv has only one strategy:

  • Memory : All the states of the page are stored in the user's HttpSession. To be able to associate user requests with the state stored in the session, an extra parameter _HDIV_STATE_ is added to each request. This parameter contains the identifier which allows access to the state from the HttpSession. In this strategy, non-editable values are hidden to guarantee confidentiality.

Confidentiality

Hdiv guarantees the confidentiality of data. Usually data sent to the client has key information for attackers, such as database registry identifiers, column or table names, web directories, etc. All these values are hidden by Hdiv to avoid their malicious use.

For example, a link of this type, http://www.host.com?data1=34 is replaced by http://www.host.com?data1=0 , guaranteeing confidentiality of the values representing database identifiers.

By default, confidentiality is activated (true value), but can be switched off in the configuration file:

<hdiv:config confidentiality="false">
</hdiv:config>

In JavaConfig mode:

@Configuration
@EnableHdivWebSecurity
public class HdivSecurityConfig extends HdivWebSecurityConfigurerAdapter {

    @Override
    public void configure(SecurityConfigBuilder builder) {

        builder.confidentiality(false);
    }

}

If you are a Grails user, configuration is implemented within plugin configuration:

grails {
    plugin {
        hdiv {
            config {
                confidentiality='false'
            }
        }
    }
}

Error page

When Hdiv detects a malicious request, it redirects the user to the error page.

It is important to note that when the possible attack is related only to text fields related data (editable validation feature), the user is not redirected to the error page and the error is displayed within the original form.

For Hdiv 2.1.7 and later versions, custom error page configuration is not mandatory. If it is not configured, a default error page is shown.

In the code below we see the explicit definition of an error page:

<hdiv:config errorPage="/error.jsp">
</hdiv:config>

In JavaConfig mode:

@Configuration
@EnableHdivWebSecurity
public class HdivSecurityConfig extends HdivWebSecurityConfigurerAdapter {

    @Override
    public void configure(SecurityConfigBuilder builder) {

        builder.errorPage("/errorPage.html");
    }

}

For Grails users, update the Config.groovy file:

 grails {
    plugin {
        hdiv {
            config {
                errorPage = '/error.jsp'
            }
        }
    }
}

Cache configuration

When Hdiv is executing using the memory strategy, the amount of memory stored within the HttpSession should be limited. By default, the cache size is 5, so Hdiv stores all the data related to the last 5 pages visited by the user. This means that if the user accesses one of the previous 5 pages, and uses a link or button, it is a valid request for Hdiv.

If it is necessary to reduce the memory consumption to improve the app scalability, it is good practice to reduce the default value. But if you need to increase back button support to more than 5 pages, increase the default value.

It is possible to overwrite this attribute within Hdiv config:

<hdiv:config maxPagesPerSession="10">
</hdiv:config>

In JavaConfig mode:

@Configuration
@EnableHdivWebSecurity
public class HdivSecurityConfig extends HdivWebSecurityConfigurerAdapter {

    @Override
    public void configure(SecurityConfigBuilder builder) {

        builder.maxPagesPerSession(10);
    }

}

If you are a Grails user, configuration is implemented within plugin configuration:

grails {
    plugin {
        hdiv {
            config {
                maxPagesPerSession='10'
            }
        }
    }
}

Cookies

By default, Hdiv validates cookie integrity and confidentiality. It is possible to disable these features within Hdiv configuration.

This is the required code to disable these features:

<hdiv:config avoidCookiesIntegrity="true" avoidCookiesConfidentiality="true">
</hdiv:config>

In JavaConfig mode:

@Configuration
@EnableHdivWebSecurity
public class HdivSecurityConfig extends HdivWebSecurityConfigurerAdapter {

    @Override
    public void configure(SecurityConfigBuilder builder) {

        builder.cookiesConfidentiality(false).cookiesIntegrity(false);
    }

}

For Grails users using Hdiv plugin:

grails {
    plugin {
        Hdiv {
            config {
                avoidCookiesIntegrity='true'
                avoidCookiesConfidentiality='true'
            }
        }
    }
}

Protected and excluded url extensions

In addition to startpages configuration and the url mapping defined by Hdiv Filter, Hdiv allows validation exclusion of some extensions. Equally, it is possible to include other extensions.

<hdiv:config excludedExtensions="css,png" protectedExtensions=".*,aaa">
</hdiv:config>

For Grails users using Hdiv plugin:

grails {
    plugin {
        hdiv {
            config {
                excludedExtensions='css,png'
                protectedExtensions='.*,aaa'
            }
        }
    }
}

Debug mode

A debug execution mode is offered in order to apply Hdiv in production environments without any functional or integration problems. In other words, Hdiv processes and validates all the requests but does not change the original request execution, only logging the possible attack but without stopping it.

It is possible to configure this option from Hdiv configuration:

<hdiv:config debugMode="true">
</hdiv:config>

In JavaConfig mode:

@Configuration
@EnableHdivWebSecurity
public class HdivSecurityConfig extends HdivWebSecurityConfigurerAdapter {

    @Override
    public void configure(SecurityConfigBuilder builder) {

        builder.debugMode(true);
    }

}

If you are a Grails user, configuration is implemented within plugin configuration:

grails {
    plugin {
        hdiv {
            config {
                debugMode='true'
            }
        }
    }
}

Logger

Hdiv has a logger that records all attacks detected in a file, helping system administrators to check all attacks on the application. Hdiv uses the Simple Logging Facade for Java (SLF4J), which can be configured to work with an underlaying log system, for example, Log4j or Java Logging.

#
# Configuration for a rolling log file ("hdiv.log").
#
log4j.appender.R=org.apache.log4j.DailyRollingFileAppender
log4j.appender.R.DatePattern='.'yyyy-MM-dd
#
# Edit the next line to point to your logs directory.
# The last part of the name is the log file name.
#
log4j.appender.R.File=hdiv.log
log4j.appender.R.layout=org.apache.log4j.PatternLayout
#
# Print the date in ISO 8601 format
#
log4j.appender.R.layout.ConversionPattern=%d [%t] %-5p - %m%n
#
# Application logging options
#
log4j.logger.org.hdiv.logs=INFO,R

The configuration above logs attack information in the hdiv.log file, following the format defined in the log4j.appender.R.layout.ConversionPattern property:

  • %d : Date of the log event

  • [%t] : Name of the thread that generated the log event

  • %-5p : Priority of the event that generated the logging

  • %m : Message associated with the logging event

  • %n : New line character

Log4j documentation can be checked for different log message formats. Log messages written by Hdiv have the following format:

[attack type];[url];[parameterName];[parameterValue];[originalParameterValue];[userLocalIP];[IP];[userId];[validationRuleName]

  • [attack type]: Type of attack detected by Hdiv. Possible values are:

    • INVALID_ACTION : The action or url received in the request does not match the one expected.

    • INVALID_PARAMETER_NAME : The parameter received in the request does not exist in the expected request.

    • NOT_RECEIVED_ALL_REQUIRED_PARAMETERS : All the required parameters for the request have not been received.

    • INVALID_PARAMETER_VALUE : Incorrect parameter value.

    • NOT_RECEIVED_ALL_PARAMETER_VALUES : For a certain parameter, the expected number of values have not been received.

    • REPEATED_VALUES_FOR_PARAMETER : Repeated values have been received for the same parameter.

    • INVALID_CONFIDENTIAL_VALUE : Incorrect parameter value received if confidentiality is activated.

    • HDIV_PARAMETER_DOES_NOT_EXIST : The Hdiv parameter has not been received in the request.

    • INVALID_HDIV_PARAMETER_VALUE : The Hdiv parameter has an incorrect value.

    • INVALID_PAGE_ID : The Hdiv parameter has an incorrect page identifier.

    • INVALID_EDITABLE_VALUE : Error in the editable parameter validation.

    • INVALID_COOKIE : The cookie received in the request has an incorrect value.

  • [url]: the url or action name of the HTTP request.

  • [parameterName]: the parameter in the HTTP request.

  • [parameterValue]: parameter value submitted by the user.

  • [originalParameterValue]: original parameter value if it has been manipulated by the user.

  • [userLocalIP]: IP address if the request has been made through a Proxy.

  • [IP]: IP address the request was made from.

  • [userId]: User identifier. Each web application gets user ID in a different way. This is why the IUserData interface has been created to allow implementation of specific systems to get user ID.

  • [validationRuleName]: If the log is related to an editable value, this field contains the validation rule that has stopped the request.

Some examples of attacks detected by Hdiv:

 INFO – INVALID_ACTION;action1;param1;value1;188.15.1.25;201.166.24.12;45652146M
 INFO – INVALID_CONFIDENTIAL_VALUE;action3;param2;value3;188.15.1.25;201.166.24.12;15235687G
 INFO – NOT_RECEIVED_ALL_REQUIRED_PARAMETERS;action5;param1;value1;188.15.1.25;201.166.24.12;152356
 INFO – INVALID_PARAMETER_NAME;action1;param5;value2;188.15.1.25;201.166.24.12;45652146M

Finally, Hdiv includes user ID within the log files. To modify the default setting it is possible to create a class that implements the org.hdiv.logs.IUserData interface. This can be enabled in the Hdiv config file defining the name of the bean that implements the IUserData interface:

<hdiv:config userData="testUserData">
</hdiv:config>

If you are a Grails user, it is enabled within plugin configuration:

grails {
    plugin {
        hdiv {
            config {
                userData='testUserData'
            }
        }
    }
}

Avoid validation in urls without parameters

Hdiv provides a configuration option to disable protection of those urls without parameters, delegating this task to Spring Security or another access protection system.

This option can be enabled in the Hdiv config file:

<hdiv:config avoidValidationInUrlsWithoutParams="true">
</hdiv:config>

In JavaConfig mode:

@Configuration
@EnableHdivWebSecurity
public class HdivSecurityConfig extends HdivWebSecurityConfigurerAdapter {

    @Override
    public void configure(SecurityConfigBuilder builder) {

        builder.validateUrlsWithoutParams(false);
    }

}

If you are a Grails user, it is enabled within plugin configuration:

grails {
    plugin {
        hdiv {
            config {
                avoidValidationInUrlsWithoutParams='true'
            }
        }
    }
}

Long-living pages

Pages whose links and forms never expire. When the page is rendered, the states created for links and forms are marked never to expire.

There is a scope attribute to configure if the states are stored in user session (user-session scope) or servlet context (app scope). In the second case, the states are shared by all users of the application.

It is possible to configure this option in the Hdiv config file:

<hdiv:config>
    <hdiv:longLivingPages>/home.html</hdiv:longLivingPages>
</hdiv:config>

In JavaConfig mode:

@Configuration
@EnableHdivWebSecurity
public class HdivSecurityConfig extends HdivWebSecurityConfigurerAdapter {

    @Override
    public void addLongLivingPages(LongLivingPagesRegistry registry) {

        registry.addLongLivingPages("/home.html");
    }

}

If you are a Grails user, within plugin configuration:

grails {
    plugin {
        hdiv {
            config {
                avoidValidationInUrlsWithoutParams='true'
            }
        }
    }
}

Random name Hdiv parameter

HDIV_STATE is the default name of the Hdiv parameter.

There is a configuration option to enable the subtitution of the constant parameter name with a random one. In this case, a per user random string is generated and used as the parameter name.

This option is configured in the Hdiv config file:

<hdiv:config randomName="true">
</hdiv:config>

In JavaConfig mode:

@Configuration
@EnableHdivWebSecurity
public class HdivSecurityConfig extends HdivWebSecurityConfigurerAdapter {

    @Override
    public void configure(SecurityConfigBuilder builder) {

        builder.randomName(true);
    }

}

If you are a Grails user, within plugin configuration:

grails {
    plugin {
        hdiv {
            config {
                randomName='true'
            }
        }
    }
}

Reuse existing page in Ajax request

If this option is enabled, Ajax requests do not create a new page in session (in Memory strategy). New form and link states are stored in the current page.

This option is recommended when Ajax is used to show dialog or tab content and to prevent Hdiv state expiration.

To detect if a request is an Ajax request, X-Requested-With header is used. It is submitted by all major JavaScript libraries.

If you want to avoid this feature in a specific request, you can send X-HDIV-EXCLUDE-PAGE-REUSE header in the Ajax request, and it will disable page reusing for that request.

Configure this option in Hdiv config file:

<hdiv:config reuseExistingPageInAjaxRequest="true">
</hdiv:config>

In JavaConfig mode:

@Configuration
@EnableHdivWebSecurity
public class HdivSecurityConfig extends HdivWebSecurityConfigurerAdapter {

    @Override
    public void configure(SecurityConfigBuilder builder) {

        builder.reuseExistingPageInAjaxRequest(true);
    }

}

If you are a Grails user, within plugin configuration:

grails {
    plugin {
        hdiv {
            config {
                reuseExistingPageInAjaxRequest='true'
            }
        }
    }
}

Show error page on editable validation error

By default, editable validation errors are shown as general validation errors, integrated into the framework form validation system.

If this option is enabled, the user is redirected to the error page and the request is not executed.

It is possible to configure this option in Hdiv config file:

<hdiv:config showErrorPageOnEditableValidation="true">
</hdiv:config>

In JavaConfig mode:

@Configuration
@EnableHdivWebSecurity
public class HdivSecurityConfig extends HdivWebSecurityConfigurerAdapter {

    @Override
    public void configure(SecurityConfigBuilder builder) {

        builder.showErrorPageOnEditableValidation(true);
    }

}

If you are a Grails user, within plugin configuration:

grails {
    plugin {
        hdiv {
            config {
                showErrorPageOnEditableValidation='true'
            }
        }
    }
}

Ajax

Hdiv also offers support for Ajax applications, securing these asynchronous requests as with all other requests.

spring-mvc-showcase shows an example of using Ajax with Hdiv.

There are different ways of using Ajax in an application.

Ajax with HTML output

This type of request has HTML as output and this HTML code is embedded in the DOM of the current page.

An example of this type of navigation can be seen in the spring-mvc-showcase application tab navigation. These tabs (implemented using JQuery and UI tabs) update a page's body using the html output of Ajax requests.

As the urls for Ajax requests are generated using <c:url> or <spring:url> tags they are already secured by Hdiv. See the example code.

Ajax with Json output

Hdiv uses Jsp tags in order to get values for non-editable fields. This is performed by integrating the taglibs from web frameworks. But if the output is rendered with Json then this information cannot be obtained from the taglib because it is not executed. For this reason, the developer has to tell Hdiv which values are in the Json output.

The developer uses IDataComposer interface for this purpose:

IDataComposer dataComposer = HDIVUtil.getDataComposer(request);
String confidentialValue = dataComposer.compose("suggestType", value, false);

A practical example is shown in this controller.

In future versions of Hdiv this work will be done by the Json generator.

Partial update of the form

When using Ajax requests in order to update part of a form already rendered by the browser, for example, to add a new input field, it is necessary to send an extra parameter in the Ajax request:

_MODIFY_HDIV_STATE_

This parameter must contain the state identifier of the form that is going to be updated.

Hdiv provides this value as a request attribute called hdivFormStateId, so it is very simple to add:

<!-- 'hdivFormStateId' is a request scoped attribute with the state id of last form.
     It is automatically created by 'form:form' tag. -->
<c:url var="suggestTypeUrl" value="/partialform/suggest.json">
    <c:param name="_MODIFY_HDIV_STATE_" value="${hdivFormStateId}" />
</c:url>

In order to test this feature, see this page.

This parameter tells Hdiv that a new state must not be created for the form. Instead, the existing one has to be updated.

RandomName

If randomName configuration property is activated in Hdiv configuration, MODIFY_HDIV_STATE parameter name is random too. The random value is stored in modifyHDIVStateParameter attribute.

An example:

<c:url var="suggestTypeUrl" value="/partialform/suggest.json">
    <c:param name="${modifyHDIVStateParameter}" value="${hdivFormStateId}" />
</c:url>

Text fields validation integration

Hdiv text fields validation detects insecure or not allowed input texts and generates an attack report consequently.

How the attack is detected and reported to the user depends in the integrated Hdiv components and their configuration.

There are three different working modes to select using the textFieldIntegration configuration attribute.

  • LIBRARY_ONLY: Text field validation is managed by the Hdiv library. No integration with the agent will be performed. Depending on the library configuration the message will be integrated into the form or an error page will be showed.
  • AGENT_IF_AVAILABLE: If the Hdiv agent is available and configured in protection mode, attack detection is delegated to the agent and an error page will be generated if it is detected as an attack.
  • AGENT_INTEGRATED: If the Hdiv agent is available and configured in protection mode, attack detection is delegated to the agent but the error message is showed in the library. This mode enables to show the validation message integrated in the application page while the validation is done by the agent.

It is possible to configure this option in Hdiv config file:

<hdiv:config textFieldIntegration="LIBRARY_ONLY">
</hdiv:config>

In JavaConfig mode:

@Configuration
@EnableHdivWebSecurity
public class HdivSecurityConfig extends HdivWebSecurityConfigurerAdapter {

    @Override
    public void configure(SecurityConfigBuilder builder) {

        builder.textFieldIntegration(TextFieldIntegration.LIBRARY_ONLY);
    }

}

Advanced Scalability

Hdiv supports scalability and high performance by providing a versatile framework for configuring the persistence of whitelist data. The framework is designed as a chain of caches which can be configured and selected to suit the requirements of each application.

Depending on the client’s requirements, the number of Hdiv enabled applications and the hardware available, different approaches can be taken by configuring faster options or others that could be more memory-optimized

More details can be found here

Connect to the Hdiv Console

Applications and servers using Hdiv can communicate with the Hdiv Console to send detected vulnerabilities and attacks to it and retrieve configuration options.

It is necessary to add some properties to enable communication between the applications and the console.

Add the following system properties to the server in the same place the Hdiv Agent is configured.

-Dhdiv.console.url=http://${console-host}:8089/hdiv-console-services
-Dhdiv.server.name=Server-Name
-Dhdiv.console.token=04db250da579302ca273a958
  • hdiv.console.url: The location of the Hdiv Console REST API. Replace ${console-host} variable with the hostname or IP address where the Hdiv Console is installed
  • hdiv.server.name: Unique name that identifies the server where the agent is installed.
  • hdiv.console.token: Authentication token used to invoke the REST API in the console. The actual value of the token for your console installation is in the Settings section of the console. Access the console and copy the value of the token to this property.

No Data Loss. Connectivity Fault Recovery

Hdiv agent is designed to allow connectivity errors without losing any data when console connection is not available. Hdiv stores pending information in the fileystem (with a maximun size limit) and it send that information when the console is available again.

Analytics

Hdiv collects analytics information related to performance and protected data. This is the collected data:

  • Hdiv request validation time compared to application response time.
  • Memory consumption for state management.
  • Number of parameters that Hdiv validates and total of received parameters.
  • Number of active sessions.

This information is sent to the console and shown in the dashboard and performance tab.

This feature is activated by default but can be disabled in the configuration file.

<hdiv:config analyticsActivated="false">
</hdiv:config>

In JavaConfig mode:

@Configuration
@EnableHdivWebSecurity
public class HdivSecurityConfig extends HdivWebSecurityConfigurerAdapter {

    @Override
    public void configure(SecurityConfigBuilder builder) {

        builder.analyticsActivated(false);
    }

}

URL Processing Level

Hdiv processes all urls (in links and forms) in the application in order to add the _HDIV_STATE_ parameter if it is necessary. The most usual reason to avoid addition of the state parameter is that a url or parameter is explicitly excluded by the developer in the configuration file.

This is the default behaviour, but it is possible to configure Hdiv to include the state id in all urls. In this way, excluded urls and parameters are used only in validation time, but not in render time.

In this situation more state objects will be generated (more memory consumption) but url processing will be faster (less cpu usage).

This feature is configurable changing urlProcessingLevel property value to low.

<hdiv:config urlProcessingLevel="low">
</hdiv:config>

In JavaConfig mode:

@Configuration
@EnableHdivWebSecurity
public class HdivSecurityConfig extends HdivWebSecurityConfigurerAdapter {

    @Override
    public void configure(SecurityConfigBuilder builder) {

        builder.urlProcessingLevel(UrlProcessingLevelType.LOW);
    }

}

Create Region Per Controller Mapping

This configuration option is only useful if reuseExistingPageInAjaxRequest configuration option is enabled and the application is built in Spring MVC.

In this case, the mapping of the controller is used as region name instead of using the generic _HDIV_REGION_parameter.

For example, in the controller below, /user/{userId} is used as region name.

@RequestMapping(value = "/user/{userId}")
public String detail(@PathVariable("userId") final long userId) {
    ...
    return "detail";
}

This feature is enabled by default but can be disabled in the configuration file.

<hdiv:config createARegionPerControllerMapping="false">
</hdiv:config>

In JavaConfig mode:

@Configuration
@EnableHdivWebSecurity
public class HdivSecurityConfig extends HdivWebSecurityConfigurerAdapter {

    @Override
    public void configure(SecurityConfigBuilder builder) {

        builder.createARegionPerControllerMapping(false);
    }

}

Brute Force Login Protection

Hdiv provides a built-in feature to prevent brute force login. The protection can be activated if a login page is defined. If so, configuring the protection can be done in this way

builder.bruteForceLoginProtection().enabled(true).banIpTimeInSeconds(20)
    .whenAttempsNumber(5).withinTimeInMillis(60000);

In this case, the IP that causes brute force login will be banned for 20 seconds if more than 5 login attempts are made within a 60 second period.

Session Configuration

Hdiv is able to work in environments with or without HTTPSession. There are different ways in which Hdiv can be configured depending on the requirements of the application:

  • SESSION: In default mode, Hdiv will store some additional information in HTTP session provided by the application server.
  • COOKIE: All necessary information is stored in cookies that the client saves and sends back in each request.
  • STATELESS: No information is stored and the URL is used to extract the required data.
  • CUSTOM: It is possible to configure Hdiv with a custom implementation of CustomSession for cases where none of the available options are adequate. Examples of this could be APIs that are using JWTs or similar tools to maintain session control
builder.sessionType(SessionType.CUSTOM).customSession(new CustomSession() {

        @Override
        public void setAttribute(String name, String value) {
            JWT.setAttribute(name, value);
        }

        @Override
        public String getAttribute(String name) {
            return JWT.getAttribute(name);
        }
});