timers: document conditions for calling

Signed-off-by: Jason A. Donenfeld <Jason@zx2c4.com>

1 files changed, 8 insertions, 0 deletions

diff --git a/src/timers.c b/src/timers.c
index 58b6e64..190cb6e 100644
--- a/src/timers.c
+++ b/src/timers.c
@@ -15,6 +15,7 @@ enum {
  * Timer for sending empty packet if we have received a packet but after have not sent one for `KEEPALIVE` ms
  * Timer for initiating new handshake if we have sent a packet but after have not received one (even empty) for `(KEEPALIVE + REKEY_TIMEOUT)` ms
  * Timer for zeroing out all ephemeral keys after `(REJECT_AFTER_TIME * 3)` ms if no new keys have been received
+ * Timer for, if enabled, sending an empty authenticated packet every user-specified seconds
  */
 
 static void expired_retransmit_handshake(unsigned long ptr)
@@ -86,6 +87,7 @@ static void expired_send_persistent_keepalive(unsigned long ptr)
 	packet_send_keepalive(peer);
 }
 
+/* Should be called after an authenticated data packet is sent. */
 void timers_data_sent(struct wireguard_peer *peer)
 {
 	if (likely(peer->timer_send_keepalive.data))
@@ -95,6 +97,7 @@ void timers_data_sent(struct wireguard_peer *peer)
 		mod_timer(&peer->timer_new_handshake, jiffies + KEEPALIVE + REKEY_TIMEOUT);
 }
 
+/* Should be called after an authenticated data packet is received. */
 void timers_data_received(struct wireguard_peer *peer)
 {
 	if (likely(peer->timer_send_keepalive.data) && !timer_pending(&peer->timer_send_keepalive))
@@ -103,12 +106,14 @@ void timers_data_received(struct wireguard_peer *peer)
 		peer->timer_need_another_keepalive = true;
 }
 
+/* Should be called after any type of authenticated packet is received -- keepalive or data. */
 void timers_any_authenticated_packet_received(struct wireguard_peer *peer)
 {
 	if (likely(peer->timer_new_handshake.data))
 		del_timer(&peer->timer_new_handshake);
 }
 
+/* Should be called after a handshake initiation message is sent. */
 void timers_handshake_initiated(struct wireguard_peer *peer)
 {
 	if (likely(peer->timer_send_keepalive.data))
@@ -117,6 +122,7 @@ void timers_handshake_initiated(struct wireguard_peer *peer)
 		mod_timer(&peer->timer_retransmit_handshake, jiffies + REKEY_TIMEOUT);
 }
 
+/* Should be called after a handshake response message is received and processed. */
 void timers_handshake_complete(struct wireguard_peer *peer)
 {
 	if (likely(peer->timer_retransmit_handshake.data))
@@ -124,6 +130,7 @@ void timers_handshake_complete(struct wireguard_peer *peer)
 	peer->timer_handshake_attempts = 0;
 }
 
+/* Should be called after an ephemeral key is created, which is before sending a handshake response or after receiving a handshake response. */
 void timers_ephemeral_key_created(struct wireguard_peer *peer)
 {
 	if (likely(peer->timer_kill_ephemerals.data))
@@ -131,6 +138,7 @@ void timers_ephemeral_key_created(struct wireguard_peer *peer)
 	do_gettimeofday(&peer->walltime_last_handshake);
 }
 
+/* Should be called before an packet with authentication -- data, keepalive, either handshake -- is sent, or after one is received. */
 void timers_any_authenticated_packet_traversal(struct wireguard_peer *peer)
 {
 	if (peer->persistent_keepalive_interval && likely(peer->timer_persistent_keepalive.data))