Module de.cuioss.http
Package de.cuioss.http.security.config

Class SecurityConfigurationBuilder

java.lang.Object
de.cuioss.http.security.config.SecurityConfigurationBuilder
public class SecurityConfigurationBuilder extends Object
Builder class for constructing SecurityConfiguration instances with fluent API.

This builder provides a convenient way to construct SecurityConfiguration objects with sensible defaults while allowing fine-grained control over all security settings. The builder follows the standard builder pattern with method chaining.

Design Principles

  • Fluent API - All setter methods return the builder for chaining
  • Sensible Defaults - Pre-configured with reasonable security defaults
  • Validation - Input validation on all parameters
  • Immutability - Produces immutable SecurityConfiguration instances

Usage Examples

 // Basic configuration with defaults
 SecurityConfiguration config = SecurityConfiguration.builder().build();

 // Custom configuration
 SecurityConfiguration custom = SecurityConfiguration.builder()
     .maxPathLength(2048)
     .allowPathTraversal(false)
     .maxParameterCount(50)
     .requireSecureCookies(true)
     .addBlockedHeaderName("X-Debug")
     .addAllowedContentType("application/json")
     .addAllowedContentType("text/plain")
     .build();

 // Chain multiple settings
 SecurityConfiguration strict = SecurityConfiguration.builder()
     .pathSecurity(1024, false)
     .cookieSecurity(true, true, 10, 64, 512)
     .bodySecurity(1024 * 1024, Set.of("application/json"))
     .encoding(false, false, false, true)
     .policies(true, true, true)
     .build();

Default Values

The builder is initialized with balanced default values that provide reasonable security without being overly restrictive:

  • Path length: 4096 characters
  • Parameter count: 100
  • Header count: 50
  • Cookie count: 20
  • Body size: 5MB
  • Path traversal: disabled
  • Cookie security flags: recommended but not required
Implements: Task C2 from HTTP verification specification
Since:
1.0
See Also:

  • Method Details

    • maxPathLength

      public SecurityConfigurationBuilder maxPathLength(int maxLength)
      Sets the maximum allowed path length.
      Parameters:
      maxLength - Maximum path length in characters (must be positive)
      Returns:
      This builder for method chaining
      Throws:
      IllegalArgumentException - if maxLength is not positive

    • allowPathTraversal

      public SecurityConfigurationBuilder allowPathTraversal(boolean allow)
      Sets whether path traversal patterns (../) are allowed.
      Parameters:
      allow - true to allow path traversal, false to block it
      Returns:
      This builder for method chaining

    • allowDoubleEncoding

      public SecurityConfigurationBuilder allowDoubleEncoding(boolean allow)
      Sets whether double URL encoding is allowed.
      Parameters:
      allow - true to allow double encoding, false to block it
      Returns:
      This builder for method chaining

    • pathSecurity

      public SecurityConfigurationBuilder pathSecurity(int maxLength, boolean allowTraversal)
      Configures path security settings in one call.
      Parameters:
      maxLength - Maximum path length
      allowTraversal - Whether to allow path traversal
      Returns:
      This builder for method chaining

    • maxParameterCount

      public SecurityConfigurationBuilder maxParameterCount(int maxCount)
      Sets the maximum number of query parameters allowed.
      Parameters:
      maxCount - Maximum parameter count (must be non-negative)
      Returns:
      This builder for method chaining
      Throws:
      IllegalArgumentException - if maxCount is negative

    • maxParameterNameLength

      public SecurityConfigurationBuilder maxParameterNameLength(int maxLength)
      Sets the maximum length for parameter names.
      Parameters:
      maxLength - Maximum name length (must be positive)
      Returns:
      This builder for method chaining
      Throws:
      IllegalArgumentException - if maxLength is not positive

    • maxParameterValueLength

      public SecurityConfigurationBuilder maxParameterValueLength(int maxLength)
      Sets the maximum length for parameter values.
      Parameters:
      maxLength - Maximum value length (must be positive)
      Returns:
      This builder for method chaining
      Throws:
      IllegalArgumentException - if maxLength is not positive

    • parameterSecurity

      public SecurityConfigurationBuilder parameterSecurity(int maxCount, int maxNameLength, int maxValueLength)
      Configures parameter security settings in one call.
      Parameters:
      maxCount - Maximum parameter count
      maxNameLength - Maximum parameter name length
      maxValueLength - Maximum parameter value length
      Returns:
      This builder for method chaining

    • maxHeaderCount

      public SecurityConfigurationBuilder maxHeaderCount(int maxCount)
      Sets the maximum number of HTTP headers allowed.
      Parameters:
      maxCount - Maximum header count (must be non-negative)
      Returns:
      This builder for method chaining
      Throws:
      IllegalArgumentException - if maxCount is negative

    • maxHeaderNameLength

      public SecurityConfigurationBuilder maxHeaderNameLength(int maxLength)
      Sets the maximum length for header names.
      Parameters:
      maxLength - Maximum name length (must be positive)
      Returns:
      This builder for method chaining
      Throws:
      IllegalArgumentException - if maxLength is not positive

    • maxHeaderValueLength

      public SecurityConfigurationBuilder maxHeaderValueLength(int maxLength)
      Sets the maximum length for header values.
      Parameters:
      maxLength - Maximum value length (must be positive)
      Returns:
      This builder for method chaining
      Throws:
      IllegalArgumentException - if maxLength is not positive

    • addAllowedHeaderName

      public SecurityConfigurationBuilder addAllowedHeaderName(String headerName)
      Adds a header name to the allowed list. If the allowed list is null, this method initializes it with the given header name.
      Parameters:
      headerName - Header name to allow (must not be null)
      Returns:
      This builder for method chaining
      Throws:
      NullPointerException - if headerName is null

    • allowedHeaderNames

      public SecurityConfigurationBuilder allowedHeaderNames(@Nullable Set<String> headerNames)
      Sets the complete list of allowed header names.
      Parameters:
      headerNames - Set of allowed header names (null means all allowed)
      Returns:
      This builder for method chaining

    • addBlockedHeaderName

      public SecurityConfigurationBuilder addBlockedHeaderName(String headerName)
      Adds a header name to the blocked list.
      Parameters:
      headerName - Header name to block (must not be null)
      Returns:
      This builder for method chaining
      Throws:
      NullPointerException - if headerName is null

    • blockedHeaderNames

      public SecurityConfigurationBuilder blockedHeaderNames(Set<String> headerNames)
      Sets the complete list of blocked header names.
      Parameters:
      headerNames - Set of blocked header names (must not be null)
      Returns:
      This builder for method chaining
      Throws:
      NullPointerException - if headerNames is null

    • headerSecurity

      public SecurityConfigurationBuilder headerSecurity(int maxCount, int maxNameLength, int maxValueLength)
      Configures header security settings in one call.
      Parameters:
      maxCount - Maximum header count
      maxNameLength - Maximum header name length
      maxValueLength - Maximum header value length
      Returns:
      This builder for method chaining

    • maxCookieCount

      public SecurityConfigurationBuilder maxCookieCount(int maxCount)
      Sets the maximum number of cookies allowed.
      Parameters:
      maxCount - Maximum cookie count (must be non-negative)
      Returns:
      This builder for method chaining
      Throws:
      IllegalArgumentException - if maxCount is negative

    • maxCookieNameLength

      public SecurityConfigurationBuilder maxCookieNameLength(int maxLength)
      Sets the maximum length for cookie names.
      Parameters:
      maxLength - Maximum name length (must be positive)
      Returns:
      This builder for method chaining
      Throws:
      IllegalArgumentException - if maxLength is not positive

    • maxCookieValueLength

      public SecurityConfigurationBuilder maxCookieValueLength(int maxLength)
      Sets the maximum length for cookie values.
      Parameters:
      maxLength - Maximum value length (must be positive)
      Returns:
      This builder for method chaining
      Throws:
      IllegalArgumentException - if maxLength is not positive

    • requireSecureCookies

      public SecurityConfigurationBuilder requireSecureCookies(boolean require)
      Sets whether all cookies must have the Secure flag.
      Parameters:
      require - true to require Secure flag on all cookies
      Returns:
      This builder for method chaining

    • requireHttpOnlyCookies

      public SecurityConfigurationBuilder requireHttpOnlyCookies(boolean require)
      Sets whether all cookies must have the HttpOnly flag.
      Parameters:
      require - true to require HttpOnly flag on all cookies
      Returns:
      This builder for method chaining

    • cookieSecurity

      public SecurityConfigurationBuilder cookieSecurity(boolean requireSecure, boolean requireHttpOnly, int maxCount, int maxNameLength, int maxValueLength)
      Configures cookie security settings in one call.
      Parameters:
      requireSecure - Whether to require Secure flag
      requireHttpOnly - Whether to require HttpOnly flag
      maxCount - Maximum cookie count
      maxNameLength - Maximum cookie name length
      maxValueLength - Maximum cookie value length
      Returns:
      This builder for method chaining

    • maxBodySize

      public SecurityConfigurationBuilder maxBodySize(long maxSize)
      Sets the maximum body size in bytes.
      Parameters:
      maxSize - Maximum body size (must be non-negative)
      Returns:
      This builder for method chaining
      Throws:
      IllegalArgumentException - if maxSize is negative

    • addAllowedContentType

      public SecurityConfigurationBuilder addAllowedContentType(String contentType)
      Adds a content type to the allowed list. If the allowed list is null, this method initializes it with the given content type.
      Parameters:
      contentType - Content type to allow (must not be null)
      Returns:
      This builder for method chaining
      Throws:
      NullPointerException - if contentType is null

    • allowedContentTypes

      public SecurityConfigurationBuilder allowedContentTypes(@Nullable Set<String> contentTypes)
      Sets the complete list of allowed content types.
      Parameters:
      contentTypes - Set of allowed content types (null means all allowed)
      Returns:
      This builder for method chaining

    • addBlockedContentType

      public SecurityConfigurationBuilder addBlockedContentType(String contentType)
      Adds a content type to the blocked list.
      Parameters:
      contentType - Content type to block (must not be null)
      Returns:
      This builder for method chaining
      Throws:
      NullPointerException - if contentType is null

    • blockedContentTypes

      public SecurityConfigurationBuilder blockedContentTypes(Set<String> contentTypes)
      Sets the complete list of blocked content types.
      Parameters:
      contentTypes - Set of blocked content types (must not be null)
      Returns:
      This builder for method chaining
      Throws:
      NullPointerException - if contentTypes is null

    • bodySecurity

      public SecurityConfigurationBuilder bodySecurity(long maxSize, @Nullable Set<String> allowedTypes)
      Configures body security settings in one call.
      Parameters:
      maxSize - Maximum body size
      allowedTypes - Set of allowed content types (null = all allowed)
      Returns:
      This builder for method chaining

    • allowNullBytes

      public SecurityConfigurationBuilder allowNullBytes(boolean allow)
      Sets whether null bytes are allowed in content.
      Parameters:
      allow - true to allow null bytes, false to block them
      Returns:
      This builder for method chaining

    • allowControlCharacters

      public SecurityConfigurationBuilder allowControlCharacters(boolean allow)
      Sets whether control characters are allowed in content.
      Parameters:
      allow - true to allow control characters, false to block them
      Returns:
      This builder for method chaining

    • allowExtendedAscii

      public SecurityConfigurationBuilder allowExtendedAscii(boolean allow)
      Sets whether extended ASCII characters (128-255) are allowed in content. For URL paths and parameters, this only affects characters 128-255. For headers and body content, this also enables Unicode support.
      Parameters:
      allow - true to allow extended ASCII and applicable Unicode characters, false to block them
      Returns:
      This builder for method chaining

    • normalizeUnicode

      public SecurityConfigurationBuilder normalizeUnicode(boolean normalize)
      Sets whether Unicode normalization should be performed.
      Parameters:
      normalize - true to normalize Unicode, false to leave as-is
      Returns:
      This builder for method chaining

    • encoding

      public SecurityConfigurationBuilder encoding(boolean allowNulls, boolean allowControls, boolean allowHighBit, boolean normalizeUni)
      Configures encoding security settings in one call.
      Parameters:
      allowNulls - Whether to allow null bytes
      allowControls - Whether to allow control characters
      allowHighBit - Whether to allow high-bit characters
      normalizeUni - Whether to normalize Unicode
      Returns:
      This builder for method chaining

    • caseSensitiveComparison

      public SecurityConfigurationBuilder caseSensitiveComparison(boolean caseSensitive)
      Sets whether string comparisons should be case-sensitive.
      Parameters:
      caseSensitive - true for case-sensitive comparisons
      Returns:
      This builder for method chaining

    • failOnSuspiciousPatterns

      public SecurityConfigurationBuilder failOnSuspiciousPatterns(boolean fail)
      Sets whether to fail on detection of suspicious patterns.
      Parameters:
      fail - true to fail on suspicious patterns, false to log only
      Returns:
      This builder for method chaining

    • logSecurityViolations

      public SecurityConfigurationBuilder logSecurityViolations(boolean log)
      Sets whether to log security violations.
      Parameters:
      log - true to enable logging, false to disable
      Returns:
      This builder for method chaining

    • policies

      public SecurityConfigurationBuilder policies(boolean caseSensitive, boolean failOnSuspicious, boolean logViolations)
      Configures general policy settings in one call.
      Parameters:
      caseSensitive - Whether comparisons are case-sensitive
      failOnSuspicious - Whether to fail on suspicious patterns
      logViolations - Whether to log security violations
      Returns:
      This builder for method chaining

    • build

      public SecurityConfiguration build()
      Builds the SecurityConfiguration with the current settings.
      Returns:
      A new immutable SecurityConfiguration instance
      Throws:
      IllegalArgumentException - if any configuration values are invalid