If successful, an {@code IncomingQuicPacket} instance is returned. * The position of the buffer is moved to the first byte following the last * decoded byte. The buffer limit is unchanged. * *
Otherwise, an exception is thrown. The position of the buffer is unspecified, * but is usually set at the place where the error occurred. * * @apiNote If successful, and the limit was not reached, this method should be * called again to decode the next packet contained in the buffer. Otherwise, if * an exception occurs, the remaining bytes in the buffer should be dropped, since * the position of the next packet in the buffer cannot be determined with * certainty. * * @param buffer the buffer with the bytes to be decoded * @param context the decoding context * * @throws IOException if decoding fails for any reason * @throws BufferUnderflowException if buffer does not have enough bytes * @throws QuicTransportException if packet is correctly signed but malformed * * @spec https://www.rfc-editor.org/info/rfc9000 * RFC 9000: QUIC: A UDP-Based Multiplexed and Secure Transport * @spec https://www.rfc-editor.org/info/rfc9001 * RFC 9001: Using TLS to Secure QUIC * @spec https://www.rfc-editor.org/info/rfc9369 * RFC 9369: QUIC Version 2 */ public IncomingQuicPacket decode(ByteBuffer buffer, CodingContext context) throws IOException, QuicKeyUnavailableException, QuicTransportException { Objects.requireNonNull(buffer); assert buffer.order() == ByteOrder.BIG_ENDIAN; PacketType type = peekPacketType(buffer); PacketReader packetReader = new PacketReader(buffer, context, type); QuicTLSEngine.KeySpace keySpace = type.keySpace().orElse(null); if (keySpace != null && !context.getTLSEngine().keysAvailable(keySpace)) { if (debug.on()) { debug.log("QuicPacketDecoder.decode(%s): no keys, skipping", packetReader); } return null; } return switch (type) { case RETRY -> IncomingRetryPacket.decode(packetReader, context); case ONERTT -> IncomingOneRttPacket.decode(packetReader, context); case ZERORTT -> IncomingZeroRttPacket.decode(packetReader, context); case HANDSHAKE -> IncomingHandshakePacket.decode(packetReader, context); case INITIAL -> IncomingInitialPacket.decode(packetReader, context); case VERSIONS -> IncomingVersionNegotiationPacket.decode(packetReader, context); case NONE -> throw new IOException("Unknown type: " + type); // if junk received default -> throw new IOException("Not implemented: " + type); // if has type but not recognised }; } private static QuicConnectionId decodeConnectionID(ByteBuffer buffer) { if (!buffer.hasRemaining()) throw new BufferUnderflowException(); int len = buffer.get() & 0xFF; if (len > buffer.remaining()) { throw new BufferUnderflowException(); } byte[] destinationConnectionID = new byte[len]; // Save buffer position ahead of time to check after read int pos = buffer.position(); buffer.get(destinationConnectionID); // Ensure all bytes have been read correctly assert pos + len == buffer.position(); return new PeerConnectionId(destinationConnectionID); } /** * Peek at the size of the first packet present in the buffer. * The position of the buffer must be at the first byte of the * first packet. This method doesn't advance the buffer position. * @param buffer A byte buffer containing quic packets * @return the size of the first packet present in the buffer. */ public int peekPacketSize(ByteBuffer buffer) { int pos = buffer.position(); int limit = buffer.limit(); int available = limit - pos; assert available >= 0 : available; if (available <= 0) return available; PacketType type = peekPacketType(buffer); return switch (type) { case HANDSHAKE, INITIAL, ZERORTT -> { assert peekVersion(buffer, pos) == quicVersion.versionNumber(); int end = peekPacketEnd(type, buffer); assert end <= limit; yield end - pos; } // ONERTT, RETRY, VERSIONS, NONE: default -> available; }; } /** * Reads the Quic V1 packet type from the given byte. * * @param headerByte the first byte of a quic packet * @return the packet type encoded in the given byte. */ private PacketType packetType(byte headerByte) { int htype = headerByte & 0xC0; int ptype = headerByte & 0xF0; return switch (htype) { case 0xC0 -> switch (quicVersion) { case QUIC_V1 -> switch (ptype) { case 0xC0 -> PacketType.INITIAL; case 0xD0 -> PacketType.ZERORTT; case 0xE0 -> PacketType.HANDSHAKE; case 0xF0 -> PacketType.RETRY; default -> PacketType.NONE; }; case QUIC_V2 -> switch (ptype) { case 0xD0 -> PacketType.INITIAL; case 0xE0 -> PacketType.ZERORTT; case 0xF0 -> PacketType.HANDSHAKE; case 0xC0 -> PacketType.RETRY; default -> PacketType.NONE; }; }; case 0x40 -> PacketType.ONERTT; // may be a stateless reset too default -> PacketType.NONE; }; } public PacketType peekPacketType(ByteBuffer buffer) { int offset = buffer.position(); return peekPacketType(buffer, offset); } public PacketType peekPacketType(ByteBuffer buffer, int offset) { if (offset < 0 || offset >= buffer.limit()) return PacketType.NONE; var headers = buffer.get(offset); var headersType = headersType(headers); if (headersType == QuicPacket.HeadersType.LONG) { if (isVersionNegotiation(buffer, offset)) { return PacketType.VERSIONS; } var version = peekVersion(buffer, offset); if (version != quicVersion.versionNumber()) { return PacketType.NONE; } } return packetType(headers); } /** * Returns the position just after the first packet present in the buffer. * @param type the first packet type. Must be INITIAL, HANDSHAKE, or ZERORTT. * @param buffer the byte buffer containing the packet * @return the position just after the first packet present in the buffer. */ private int peekPacketEnd(PacketType type, ByteBuffer buffer) { // Store initial position to calculate size of packet decoded int initialPosition = buffer.position(); int limit = buffer.limit(); assert buffer.order() == ByteOrder.BIG_ENDIAN; assert type == PacketType.HANDSHAKE || type == PacketType.INITIAL || type == PacketType.ZERORTT : type; // This case should have been handled by the caller assert buffer.getInt(initialPosition + 1) != 0 : "version is 0"; int pos = initialPosition; // header bits pos = pos + 4; // version pos = pos + 1; // dcid length if (pos <= 0 || pos >= limit) return limit; int dcidlen = buffer.get(pos) & 0xFF; pos = pos + dcidlen + 1; // scid length if (pos <= 0 || pos >= limit) return limit; int scidlen = buffer.get(pos) & 0xFF; pos = pos + scidlen + 1; // token length or packet length if (pos <= 0 || pos >= limit) return limit; if (type == PacketType.INITIAL) { int tksize = VariableLengthEncoder.peekEncodedValueSize(buffer, pos); if (tksize <= 0 || tksize > 8) return limit; if (limit - tksize < pos) return limit; long tklen = VariableLengthEncoder.peekEncodedValue(buffer, pos); if (tklen < 0 || tklen > limit - pos) return limit; pos = pos + tksize + (int)tklen; // packet length if (pos <= 0 || pos >= limit) return limit; } int lensize = VariableLengthEncoder.peekEncodedValueSize(buffer, pos); if (lensize <= 0 || lensize > 8) return limit; long len = VariableLengthEncoder.peekEncodedValue(buffer, pos); if (len < 0 || len > limit - pos) return limit; pos = pos + lensize + (int)len; // end of packet if (pos <= 0 || pos >= limit) return limit; return pos; } /** * Find the length of the next packet in the buffer, and return * the next packet bytes as a slice of the original packet. * Advances the original buffer position to after the returned * packet. * @param buffer a buffer containing coalesced packets * @param offset the offset at which the next packet starts * @return the next packet. */ public ByteBuffer nextPacketSlice(ByteBuffer buffer, int offset) { assert offset >= 0; assert offset <= buffer.limit(); int pos = buffer.position(); int limit = buffer.limit(); buffer.position(offset); ByteBuffer next = null; try { int size = peekPacketSize(buffer); if (debug.on()) { debug.log("next packet bytes from %d (%d/%d)", offset, size, buffer.remaining()); } next = buffer.slice(offset, size); buffer.position(offset + size); } catch (Throwable tt) { if (debug.on()) { debug.log("failed to peek packet size: " + tt, tt); debug.log("dropping all remaining bytes (%d)", limit - pos); } buffer.position(limit); next = buffer; } return next; } /** * Advance the bytebuffer position to the end of the packet * @param buffer A byte buffer containing quic packets * @param offset The offset at which the packet starts */ public void skipPacket(ByteBuffer buffer, int offset) { assert offset >= 0; assert offset <= buffer.limit(); int pos = buffer.position(); int limit = buffer.limit(); buffer.position(offset); try { int size = peekPacketSize(buffer); if (debug.on()) { debug.log("dropping packet bytes from %d (%d/%d)", offset, size, buffer.remaining()); } buffer.position(offset + size); } catch (Throwable tt) { if (debug.on()) { debug.log("failed to peek packet size: " + tt, tt); debug.log("dropping all remaining bytes (%d)", limit - pos); } buffer.position(limit); } } /** * Returns a decoder for the given Quic version. * Returns {@code null} if no decoder for that version exists. * * @param quicVersion the Quic protocol version number * @return a decoder for the given Quic version or {@code null} */ public static QuicPacketDecoder of(QuicVersion quicVersion) { return switch (quicVersion) { case QUIC_V1 -> Decoders.QUIC_V1_DECODER; case QUIC_V2 -> Decoders.QUIC_V2_DECODER; default -> throw new IllegalArgumentException("No packet decoder for Quic version " + quicVersion); }; } /** * Returns a {@code QuicPacketDecoder} to decode the packet * starting at the specified offset in the buffer. * This method will attempt to read the quic version in the * packet in order to return the proper decoder. * If the version is 0, then the decoder for Quic Version 1 * is returned. * * @param buffer A buffer containing a Quic packet * @param offset The offset at which the packet starts * @return A {@code QuicPacketDecoder} instance to decode the * packet starting at the given offset. */ public static QuicPacketDecoder of(ByteBuffer buffer, int offset) { var version = peekVersion(buffer, offset); final QuicVersion quicVersion = version == 0 ? QuicVersion.QUIC_V1 : QuicVersion.of(version).orElse(null); if (quicVersion == null) { return null; } return of(quicVersion); } /** * A {@code PacketReader} to read a Quic packet. * A {@code PacketReader} may have version specific code, and therefore * has an implicit pointer to a {@code QuicPacketDecoder} instance. *
* A {@code PacketReader} offers high level helper methods to read * data (such as Connection IDs or Packet Numbers) from a Quic packet. * It has however no or little knowledge of the actual packet structure. * It is driven by the {@code decode} method of the appropriate * {@code IncomingQuicPacket} type. *
* A {@code PacketReader} is stateful: it encapsulates a {@code ByteBuffer}
* (or possibly a list of byte buffers - as a future enhancement) and
* advances the position on the buffer it is reading.
*
*/
class PacketReader {
private static final int PACKET_NUMBER_MASK = 0x03;
final ByteBuffer buffer;
final int offset;
final int initialLimit;
final CodingContext context;
final PacketType packetType;
PacketReader(ByteBuffer buffer, CodingContext context) {
this(buffer, context, peekPacketType(buffer));
}
PacketReader(ByteBuffer buffer, CodingContext context, PacketType packetType) {
assert buffer.order() == ByteOrder.BIG_ENDIAN;
int pos = buffer.position();
int limit = buffer.limit();
this.buffer = buffer;
this.offset = pos;
this.initialLimit = limit;
this.context = context;
this.packetType = packetType;
}
public int offset() {
return offset;
}
public int position() {
return buffer.position();
}
public int remaining() {
return buffer.remaining();
}
public boolean hasRemaining() {
return buffer.hasRemaining();
}
public int bytesRead() {
return position() - offset;
}
public void reset() {
buffer.position(offset);
buffer.limit(initialLimit);
}
public byte headers() {
return buffer.get(offset);
}
public void headers(byte headers) {
buffer.put(offset, headers);
}
public PacketType packetType() {
return packetType;
}
public int packetNumberLength() {
return (headers() & PACKET_NUMBER_MASK) + 1;
}
public byte readHeaders() {
return buffer.get();
}
public int readVersion() {
return buffer.getInt();
}
public int[] readSupportedVersions() {
// Calculate payload length and retrieve payload
final int payloadLen = buffer.remaining();
final int versionsCount = payloadLen >> 2;
int[] versions = new int[versionsCount];
for (int i=0 ; i