Package com.oorian.security

Class UrlSecurity

java.lang.Object
com.oorian.security.UrlSecurity
public class UrlSecurity extends Object
Provides URL signing and encryption utilities for tamper prevention.

UrlSecurity supports two protection strategies:

  • HMAC Signing (UrlSecurityMode.SIGNED) — appends a cryptographic signature parameter (_sig) to the URL. The URL path remains human-readable but any modification invalidates the signature.
  • AES-GCM Encryption (UrlSecurityMode.ENCRYPTED) — encrypts the entire URL path into an opaque Base64URL token, preventing users from seeing or guessing the underlying resource identifiers.

The secret key must be configured via setKey(String) before any signing or encryption operations. The key is derived using SHA-256 to ensure a consistent 256-bit key length regardless of the input key string.

Usage:


 // In Application.initialize():
 setUrlSecurityKey("my-application-secret-key");

 // HMAC signing
 String signed = UrlSecurity.sign("/users/123");
 // Result: "/users/123?_sig=abc123..."
 boolean valid = UrlSecurity.verify("/users/123?_sig=abc123...");

 // AES encryption
 String encrypted = UrlSecurity.encrypt("/users/123");
 // Result: "aBcDeFgHiJkL..."  (opaque Base64URL token)
 String original = UrlSecurity.decrypt(encrypted);
 // Result: "/users/123"
Since:
2.1
Version:
1.0
Author:
Marvin P. Warble Jr.
See Also:

  • Field Details

    • SIGNATURE_PARAM

      public static final String SIGNATURE_PARAM
      Query parameter name for the HMAC signature.
      See Also:

  • Method Details

    • isConfigured

      public static boolean isConfigured()
      Returns whether a URL security key has been configured.
      Returns:
      true if a key is set

    • sign

      public static String sign(String url)
      Signs a URL path by appending an HMAC-SHA256 signature as a query parameter.

      The signature covers the path portion of the URL (everything before the query string, if any). Existing query parameters are preserved.

      Parameters:
      url - the URL path to sign (e.g., "/users/123" or "/users/123?tab=orders")
      Returns:
      the signed URL with _sig parameter appended
      Throws:
      IllegalStateException - if no key has been configured

    • verify

      public static boolean verify(String url)
      Verifies the HMAC signature on a signed URL.

      Extracts the _sig parameter, recomputes the HMAC over the path portion, and compares using a constant-time comparison to prevent timing attacks.

      Parameters:
      url - the signed URL to verify
      Returns:
      true if the signature is valid, false if missing or invalid
      Throws:
      IllegalStateException - if no key has been configured

    • encrypt

      public static String encrypt(String url)
      Encrypts a URL path using AES-256-GCM.

      The path is encrypted with a random initialization vector (IV) and the result is returned as a Base64URL-encoded string containing the IV, ciphertext, and GCM authentication tag.

      Parameters:
      url - the URL path to encrypt (e.g., "/users/123")
      Returns:
      the Base64URL-encoded encrypted token
      Throws:
      IllegalStateException - if no key has been configured or encryption fails

    • decrypt

      public static String decrypt(String token)
      Decrypts a Base64URL-encoded token back to the original URL path.
      Parameters:
      token - the encrypted token produced by encrypt(String)
      Returns:
      the original URL path, or null if decryption fails (tampered or invalid)
      Throws:
      IllegalStateException - if no key has been configured