Package io.github.mahmoudimus.quic

Class StatelessResetToken

java.lang.Object
io.github.mahmoudimus.quic.StatelessResetToken
public final class StatelessResetToken extends Object
A 16-byte stateless reset token (RFC 9000 section 10.3), as carried in NEW_CONNECTION_ID frames, the stateless_reset_token transport parameter and the tail of a Stateless Reset.

equals(Object) and matches(ByteBuffer) compare in constant time (MessageDigest.isEqual(byte[], byte[])), so a peer cannot learn a token byte by byte from timing. Instances are immutable and thread-safe.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    LENGTH
    The token length in bytes.
    static final int
    MIN_RESET_DATAGRAM
    The smallest datagram that can be a Stateless Reset: 5 bytes that look like a short header plus the token (RFC 9000 section 10.3).

  • Method Summary

    Modifier and Type
    Method
    Description
    static StatelessResetToken
    derive(byte[] staticKey, ConnectionId connectionId)
    Derives the token for a connection ID from a static key, as quinn does: the first 16 bytes of HMAC-SHA256(key, connection ID).
    boolean
    equals(Object o)
    Compares in constant time.
    int
    hashCode()
     
    boolean
    matches(ByteBuffer datagram)
    Whether a received datagram ends in this token, which identifies it as a Stateless Reset (RFC 9000 section 10.3.1).
    static StatelessResetToken
    of(byte[] bytes)
    A token with a copy of some bytes.
    static StatelessResetToken
    read(ByteBuffer in)
    Reads a token at the buffer's position.
    byte[]
    toByteArray()
    A copy of the bytes.
    String
    toString()
    The token in lowercase hexadecimal.
    void
    writeTo(ByteBuffer out)
    Writes the token.

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait

  • Field Details

    • LENGTH

      public static final int LENGTH
      The token length in bytes.
      See Also:

    • MIN_RESET_DATAGRAM

      public static final int MIN_RESET_DATAGRAM
      The smallest datagram that can be a Stateless Reset: 5 bytes that look like a short header plus the token (RFC 9000 section 10.3).
      See Also:

  • Method Details

    • of

      public static StatelessResetToken of(byte[] bytes)
      A token with a copy of some bytes.
      Parameters:
      bytes - exactly LENGTH bytes
      Returns:
      the token
      Throws:
      IllegalArgumentException - if the length is not 16

    • read

      public static StatelessResetToken read(ByteBuffer in)
      Reads a token at the buffer's position.
      Parameters:
      in - the buffer; its position moves past the token
      Returns:
      the token
      Throws:
      BufferUnderflowException - if fewer than 16 bytes remain

    • derive

      public static StatelessResetToken derive(byte[] staticKey, ConnectionId connectionId)
      Derives the token for a connection ID from a static key, as quinn does: the first 16 bytes of HMAC-SHA256(key, connection ID). An endpoint that keeps the key can then reset connections it has forgotten (RFC 9000 section 10.3.2).
      Parameters:
      staticKey - a secret key of at least 32 random bytes
      connectionId - the connection ID the token belongs to
      Returns:
      the token

    • toByteArray

      public byte[] toByteArray()
      A copy of the bytes.
      Returns:
      a new 16-byte array

    • writeTo

      public void writeTo(ByteBuffer out)
      Writes the token.
      Parameters:
      out - the buffer, written at its position

    • matches

      public boolean matches(ByteBuffer datagram)
      Whether a received datagram ends in this token, which identifies it as a Stateless Reset (RFC 9000 section 10.3.1). Datagrams shorter than MIN_RESET_DATAGRAM never match. The comparison takes the same time wherever the bytes differ.
      Parameters:
      datagram - the datagram between its position and limit; the buffer is not changed
      Returns:
      true if the last 16 bytes equal the token

    • equals

      public boolean equals(Object o)
      Compares in constant time.
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      The token in lowercase hexadecimal.
      Overrides:
      toString in class Object