Class EmailVerificationLink

java.lang.Object
com.iizix.server.security.EmailVerificationLink
public final class EmailVerificationLink extends Object
The token of an email verification link, and its verification.

A link carries one query parameter, PARAM, whose value is the address, the user ID, the purpose and the expiry time of the link, sealed with the server's own key through ISensitiveParameterHandler.encodeParameter(String) - in the server that is ServerSecurityManager: AES-256-GCM under a key generated once per installation, persisted in the server keys file, rotated with the old keys retained, and tagged with the key's fingerprint so that a link survives a rotation. The GCM authentication tag is the keyed MAC of the link; the JDK verifies it before a byte of the content is returned. Nothing in the URL lets a link be forged, be altered, or be replayed for another address or user, because every one of those values is inside the sealed content and the key never leaves the server.

Before CC-SEC-FIX S2 the link carried v=base64(SHA-256(seed, email, q, uid)) with the seed, the address, q and the user ID all in the URL as well, so anyone could compute v for any address of any user; and a link never expired.

Author:
Christopher Mindus

  • Field Details

    • PATH

      public static final String PATH
      The path of the verification route, without the leading slash: "iizi-email-verification".
      See Also:

    • PARAM

      public static final String PARAM
      The query parameter carrying the token: "v".
      See Also:

    • VALIDITY_MS

      public static final long VALIDITY_MS
      How long a link is valid from the moment it is built: 72 hours.
      See Also:

  • Method Details

    • buildQuery

      public static String buildQuery(ISensitiveParameterHandler keys, String email, long userID, long expiresAt) throws GeneralSecurityException
      Builds the query string of a link: v=token.
      Parameters:
      keys - The server's sealing keys.
      email - The address to verify.
      userID - The user ID the address belongs to.
      expiresAt - The expiry time, milliseconds since the epoch.
      Returns:
      The query string, URL-safe.
      Throws:
      GeneralSecurityException - If the content cannot be sealed.
      NullPointerException - If keys or email is null.
      IllegalArgumentException - If the address contains a line break.

    • verify

      public static EmailVerificationLink.Result verify(ISensitiveParameterHandler keys, String token, long now)
      Verifies a token.

      The token is opened with the server's keys, which fails for a token sealed by another server, for one altered anywhere and for anything that is not a token at all; the content must then carry the purpose; and the expiry time must not have passed. Nothing is thrown for a bad token: a verification route is unauthenticated by design and answers every caller the same way.

      Parameters:
      keys - The server's sealing keys.
      token - The token from the link, null or empty for none.
      now - The current time, milliseconds since the epoch.
      Returns:
      The result, never null.