1 /* 2 * Copyright 2023 The OpenSSL Project Authors. All Rights Reserved. 3 * 4 * Licensed under the Apache License 2.0 (the "License"). You may not use 5 * this file except in compliance with the License. You can obtain a copy 6 * in the file LICENSE in the source distribution or at 7 * https://www.openssl.org/source/license.html 8 */ 9 10 #ifndef OSSL_INTERNAL_QUIC_SRTM_H 11 # define OSSL_INTERNAL_QUIC_SRTM_H 12 # pragma once 13 14 # include "internal/e_os.h" 15 # include "internal/time.h" 16 # include "internal/quic_types.h" 17 # include "internal/quic_wire.h" 18 # include "internal/quic_predef.h" 19 20 # ifndef OPENSSL_NO_QUIC 21 22 /* 23 * QUIC Stateless Reset Token Manager 24 * ================================== 25 * 26 * The stateless reset token manager is responsible for mapping stateless reset 27 * tokens to connections. It is used to identify stateless reset tokens in 28 * incoming packets. In this regard it can be considered an alternate "routing" 29 * mechanism for incoming packets, and is somewhat analogous with the LCIDM, 30 * except that it uses SRTs to route rather than DCIDs. 31 * 32 * The SRTM specifically stores a bidirectional mapping of the form 33 * 34 * (opaque pointer, sequence number) [1] <-> [0..n] SRT 35 * 36 * The (opaque pointer, sequence number) tuple is used to refer to an entry (for 37 * example for the purposes of removing it later when it is no longer needed). 38 * Likewise, an entry can be looked up using SRT to get the opaque pointer and 39 * sequence number. 40 * 41 * It is important to note that the same SRT may exist multiple times and map to 42 * multiple (opaque pointer, sequence number) tuples, for example, if we 43 * initiate multiple connections to the same peer using the same local QUIC_PORT 44 * and the peer decides to behave bizarrely and issue the same SRT for both 45 * connections. It should not do this, but we have to be resilient against 46 * byzantine peer behaviour. Thus we are capable of storing multiple identical 47 * SRTs for different (opaque pointer, sequence number) keys. 48 * 49 * The SRTM supports arbitrary insertion, arbitrary deletion of specific keys 50 * identified by a (opaque pointer, sequence number) key, and mass deletion of 51 * all entries under a specific opaque pointer. It supports lookup by SRT to 52 * identify zero or more corresponding (opaque pointer, sequence number) tuples. 53 * 54 * The opaque pointer may be used for any purpose but is intended to represent a 55 * connection identity and must therefore be consistent (usefully comparable). 56 */ 57 58 /* Creates a new empty SRTM instance. */ 59 QUIC_SRTM *ossl_quic_srtm_new(OSSL_LIB_CTX *libctx, const char *propq); 60 61 /* Frees a SRTM instance. No-op if srtm is NULL. */ 62 void ossl_quic_srtm_free(QUIC_SRTM *srtm); 63 64 /* 65 * Add a (opaque, seq_num) -> SRT entry to the SRTM. This operation fails if a 66 * SRT entry already exists with the same (opaque, seq_num) tuple. The token is 67 * copied. Returns 1 on success or 0 on failure. 68 */ 69 int ossl_quic_srtm_add(QUIC_SRTM *srtm, void *opaque, uint64_t seq_num, 70 const QUIC_STATELESS_RESET_TOKEN *token); 71 72 /* 73 * Removes an entry by identifying it via its (opaque, seq_num) tuple. 74 * Returns 1 if the entry was found and removed, and 0 if it was not found. 75 */ 76 int ossl_quic_srtm_remove(QUIC_SRTM *srtm, void *opaque, uint64_t seq_num); 77 78 /* 79 * Removes all entries (opaque, *) with the given opaque pointer. 80 * 81 * Returns 1 on success and 0 on failure. If no entries with the given opaque 82 * pointer were found, this is considered a success condition. 83 */ 84 int ossl_quic_srtm_cull(QUIC_SRTM *strm, void *opaque); 85 86 /* 87 * Looks up a SRT to find the corresponding opaque pointer and sequence number. 88 * An output field pointer can be set to NULL if it is not required. 89 * 90 * This function is designed to avoid exposing timing channels on token values 91 * or the contents of the SRT mapping. 92 * 93 * If there are several identical SRTs, idx can be used to get the nth entry. 94 * Call this function with idx set to 0 first, and keep calling it after 95 * incrementing idx until it returns 0. 96 * 97 * Returns 1 if an entry was found and 0 otherwise. 98 */ 99 int ossl_quic_srtm_lookup(QUIC_SRTM *srtm, 100 const QUIC_STATELESS_RESET_TOKEN *token, 101 size_t idx, 102 void **opaque, uint64_t *seq_num); 103 104 /* Verify internal invariants and assert if they are not met. */ 105 void ossl_quic_srtm_check(const QUIC_SRTM *srtm); 106 107 # endif 108 109 #endif 110
