OpenVPN
Data Structures | Macros
Reliability Layer module

The Reliability Layer is part of OpenVPN's control channel. More...

Data Structures

struct  reliable_ack
 The acknowledgment structure in which packet IDs are stored for later acknowledgment. More...
 
struct  reliable_entry
 The structure in which the reliability layer stores a single incoming or outgoing packet. More...
 
struct  reliable
 The reliability layer storage structure for one VPN tunnel's control channel in one direction. More...
 

Macros

#define EXPONENTIAL_BACKOFF
 
#define RELIABLE_ACK_SIZE   8
 The maximum number of packet IDs waiting to be acknowledged which can be stored in one reliable_ack structure. More...
 
#define RELIABLE_CAPACITY   8
 The maximum number of packets that the reliability layer for one VPN tunnel in one direction can store. More...
 

Functions for processing incoming acknowledgments

bool reliable_ack_read (struct reliable_ack *ack, struct buffer *buf, const struct session_id *sid)
 Read an acknowledgment record from a received packet. More...
 
void reliable_send_purge (struct reliable *rel, struct reliable_ack *ack)
 Remove acknowledged packets from a reliable structure. More...
 

Functions for processing outgoing acknowledgments

static bool reliable_ack_empty (struct reliable_ack *ack)
 Check whether an acknowledgment structure contains any packet IDs to be acknowledged. More...
 
bool reliable_ack_write (struct reliable_ack *ack, struct buffer *buf, const struct session_id *sid, int max, bool prepend)
 Write a packet ID acknowledgment record to a buffer. More...
 

Functions for initialization and cleanup

void reliable_init (struct reliable *rel, int buf_size, int offset, int array_size, bool hold)
 Initialize a reliable structure. More...
 
void reliable_free (struct reliable *rel)
 Free allocated memory associated with a reliable structure. More...
 
void reliable_ack_adjust_frame_parameters (struct frame *frame, int max)
 

Functions for inserting incoming packets

bool reliable_can_get (const struct reliable *rel)
 Check whether a reliable structure has any free buffers available for use. More...
 
bool reliable_not_replay (const struct reliable *rel, packet_id_type id)
 Check that a received packet's ID is not a replay. More...
 
bool reliable_wont_break_sequentiality (const struct reliable *rel, packet_id_type id)
 Check that a received packet's ID can safely be stored in the reliable structure's processing window. More...
 
bool reliable_ack_read_packet_id (struct buffer *buf, packet_id_type *pid)
 Read the packet ID of a received packet. More...
 
struct bufferreliable_get_buf (struct reliable *rel)
 Get the buffer of a free reliable entry in which to store a packet. More...
 
void reliable_mark_active_incoming (struct reliable *rel, struct buffer *buf, packet_id_type pid, int opcode)
 Mark the reliable entry associated with the given buffer as active incoming. More...
 
bool reliable_ack_acknowledge_packet_id (struct reliable_ack *ack, packet_id_type pid)
 Record a packet ID for later acknowledgment. More...
 

Functions for extracting incoming packets

struct bufferreliable_get_buf_sequenced (struct reliable *rel)
 Get the buffer of the next sequential and active entry. More...
 
void reliable_mark_deleted (struct reliable *rel, struct buffer *buf, bool inc_pid)
 Remove an entry from a reliable structure. More...
 

Functions for inserting outgoing packets

struct bufferreliable_get_buf_output_sequenced (struct reliable *rel)
 Get the buffer of free reliable entry and check whether the outgoing acknowledgment sequence is still okay. More...
 
void reliable_mark_active_outgoing (struct reliable *rel, struct buffer *buf, int opcode)
 Mark the reliable entry associated with the given buffer as active outgoing. More...
 

Functions for extracting outgoing packets

bool reliable_can_send (const struct reliable *rel)
 Check whether a reliable structure has any active entries ready to be (re)sent. More...
 
struct bufferreliable_send (struct reliable *rel, int *opcode)
 Get the next packet to send to the remote peer. More...
 

Miscellaneous functions

bool reliable_empty (const struct reliable *rel)
 Check whether a reliable structure is empty. More...
 
interval_t reliable_send_timeout (const struct reliable *rel)
 Determined how many seconds until the earliest resend should be attempted. More...
 
void reliable_schedule_now (struct reliable *rel)
 Reschedule all entries of a reliable structure to be ready for (re)sending immediately. More...
 
void reliable_debug_print (const struct reliable *rel, char *desc)
 
static void reliable_set_timeout (struct reliable *rel, interval_t timeout)
 
const char * reliable_ack_print (struct buffer *buf, bool verbose, struct gc_arena *gc)
 
void reliable_ack_debug_print (const struct reliable_ack *ack, char *desc)
 

Detailed Description

The Reliability Layer is part of OpenVPN's control channel.

It provides a reliable and sequential transport mechanism for control channel messages between OpenVPN peers. This module forms the interface between the External Multiplexer and the Control Channel TLS module.

UDP or TCP as VPN tunnel transport

This is especially important when OpenVPN is configured to communicate over UDP, because UDP does not offer a reliable and sequential transport. OpenVPN endpoints can also communicate over TCP which does provide a reliable and sequential transport. In both cases, using UDP or TCP as an external transport, the internal Reliability Layer is active.

Macro Definition Documentation

◆ EXPONENTIAL_BACKOFF

#define EXPONENTIAL_BACKOFF

Definition at line 46 of file reliable.h.

◆ RELIABLE_ACK_SIZE

#define RELIABLE_ACK_SIZE   8

The maximum number of packet IDs waiting to be acknowledged which can be stored in one reliable_ack structure.

Definition at line 48 of file reliable.h.

Referenced by reliable_ack_acknowledge_packet_id(), reliable_ack_read(), and tls_process().

◆ RELIABLE_CAPACITY

#define RELIABLE_CAPACITY   8

The maximum number of packets that the reliability layer for one VPN tunnel in one direction can store.

Definition at line 56 of file reliable.h.

Referenced by reliable_init().

Function Documentation

◆ reliable_ack_acknowledge_packet_id()

bool reliable_ack_acknowledge_packet_id ( struct reliable_ack ack,
packet_id_type  pid 
)

Record a packet ID for later acknowledgment.

Parameters
ackThe acknowledgment structure which stores this VPN tunnel's packet IDs for later acknowledgment.
pidThe packet ID of the received packet which should be acknowledged.
Returns
  • True, if the packet ID was added to ack.
  • False, if the packet ID was already present in ack or ack has no free space to store any more packet IDs.

Definition at line 143 of file reliable.c.

References D_REL_DEBUG, D_REL_LOW, dmsg, reliable_ack::len, reliable_ack::packet_id, packet_id_format, reliable_ack_packet_id_present(), and RELIABLE_ACK_SIZE.

Referenced by tls_pre_decrypt().

◆ reliable_ack_adjust_frame_parameters()

void reliable_ack_adjust_frame_parameters ( struct frame frame,
int  max 
)

Definition at line 260 of file reliable.c.

References ACK_SIZE, and frame_add_to_extra_frame().

Referenced by tls_init_control_channel_frame_parameters().

◆ reliable_ack_debug_print()

void reliable_ack_debug_print ( const struct reliable_ack ack,
char *  desc 
)

Referenced by reliable_mark_deleted().

◆ reliable_ack_empty()

static bool reliable_ack_empty ( struct reliable_ack ack)
inlinestatic

Check whether an acknowledgment structure contains any packet IDs to be acknowledged.

Parameters
ackThe acknowledgment structure to check.
Returns
  • True, if the acknowledgment structure is empty.
  • False, if there are packet IDs to be acknowledged.

Definition at line 153 of file reliable.h.

Referenced by tls_process().

◆ reliable_ack_print()

const char* reliable_ack_print ( struct buffer buf,
bool  verbose,
struct gc_arena gc 
)

◆ reliable_ack_read()

bool reliable_ack_read ( struct reliable_ack ack,
struct buffer buf,
const struct session_id sid 
)

Read an acknowledgment record from a received packet.

This function reads the packet ID acknowledgment record from the packet contained in buf. If the record contains acknowledgments, these are stored in ack. This function also compares the packet's session ID with the expected session ID sid, which should be equal.

Parameters
ackThe acknowledgment structure in which received acknowledgments are to be stored.
bufThe buffer containing the packet.
sidThe expected session ID to compare to the session ID in the packet.
Returns
  • True, if processing was successful.
  • False, if an error occurs during processing.

Definition at line 160 of file reliable.c.

References buf_read(), D_REL_LOW, dmsg, gc_free(), gc_new(), reliable_ack::len, ntohpid, reliable_ack::packet_id, RELIABLE_ACK_SIZE, session_id_defined(), session_id_equal(), session_id_print(), and session_id_read().

Referenced by tls_pre_decrypt().

◆ reliable_ack_read_packet_id()

bool reliable_ack_read_packet_id ( struct buffer buf,
packet_id_type pid 
)

Read the packet ID of a received packet.

Parameters
bufThe buffer containing the received packet.
pidA pointer where the packet's packet ID will be written.
Returns
  • True, if processing was successful.
  • False, if an error occurs during processing.

Definition at line 125 of file reliable.c.

References buf_read(), D_REL_DEBUG, D_REL_LOW, dmsg, buffer::len, ntohpid, and packet_id_format.

Referenced by tls_pre_decrypt().

◆ reliable_ack_write()

bool reliable_ack_write ( struct reliable_ack ack,
struct buffer buf,
const struct session_id sid,
int  max,
bool  prepend 
)

Write a packet ID acknowledgment record to a buffer.

Parameters
ackThe acknowledgment structure containing packet IDs to be acknowledged.
bufThe buffer into which the acknowledgment record will be written.
sidThe session ID of the VPN tunnel associated with the packet IDs to be acknowledged.
maxThe maximum number of acknowledgments to be written in the record.
prependIf true, prepend the acknowledgment record in the buffer; if false, write into the buffer's current position.
Returns
  • True, if processing was successful.
  • False, if an error occurs during processing.

Definition at line 215 of file reliable.c.

References ACK_SIZE, ASSERT, BDEF, buf_sub(), buf_write(), D_REL_DEBUG, dmsg, htonpid, reliable_ack::len, reliable_ack::packet_id, packet_id_format, session_id_defined(), and session_id_write().

Referenced by write_control_auth().

◆ reliable_can_get()

bool reliable_can_get ( const struct reliable rel)

Check whether a reliable structure has any free buffers available for use.

Parameters
relThe reliable structure to check.
Returns
  • True, if at least one buffer is available for use.
  • False, if all the buffers are active.

Definition at line 409 of file reliable.c.

References reliable_entry::active, array, D_REL_LOW, dmsg, gc_free(), gc_new(), reliable_print_ids(), and size.

Referenced by tls_pre_decrypt().

◆ reliable_can_send()

bool reliable_can_send ( const struct reliable rel)

Check whether a reliable structure has any active entries ready to be (re)sent.

Parameters
relThe reliable structure to check.
Returns
  • True, if there are active entries ready to be (re)sent president.
  • False, if there are no active entries, or the active entries are not yet ready for resending.

Definition at line 544 of file reliable.c.

References reliable_entry::active, array, D_REL_DEBUG, dmsg, gc_free(), gc_new(), hold, reliable_entry::next_try, now, reliable_print_ids(), and size.

Referenced by tls_process().

◆ reliable_debug_print()

void reliable_debug_print ( const struct reliable rel,
char *  desc 
)

Referenced by reliable_mark_deleted().

◆ reliable_empty()

bool reliable_empty ( const struct reliable rel)

Check whether a reliable structure is empty.

Parameters
relThe reliable structure to check.
Returns
  • True, if there are no active entries in the given reliable structure.
  • False, if there is at least one active entry present.

Definition at line 341 of file reliable.c.

References reliable_entry::active, array, and size.

◆ reliable_free()

void reliable_free ( struct reliable rel)

Free allocated memory associated with a reliable structure.

Parameters
relThe reliable structured to clean up.

Definition at line 329 of file reliable.c.

References array, reliable_entry::buf, free_buf(), and size.

Referenced by key_state_free().

◆ reliable_get_buf()

struct buffer* reliable_get_buf ( struct reliable rel)

Get the buffer of a free reliable entry in which to store a packet.

Parameters
relThe reliable structure in which to search for a free entry.
Returns
A pointer to a buffer of a free entry in the rel reliable structure. If there are no free entries available, this function returns NULL.

Definition at line 475 of file reliable.c.

References reliable_entry::active, array, ASSERT, reliable_entry::buf, buf_init, offset, and size.

Referenced by reliable_get_buf_output_sequenced(), and tls_pre_decrypt().

◆ reliable_get_buf_output_sequenced()

struct buffer* reliable_get_buf_output_sequenced ( struct reliable rel)

Get the buffer of free reliable entry and check whether the outgoing acknowledgment sequence is still okay.

Parameters
relThe reliable structure in which to search for a free entry.
Returns
A pointer to a buffer of a free entry in the rel reliable structure. If there are no free entries available, this function returns NULL. If the outgoing acknowledgment sequence is broken, this function also returns NULL.

Definition at line 492 of file reliable.c.

References reliable_entry::active, array, D_REL_LOW, dmsg, gc_free(), gc_new(), reliable_entry::packet_id, packet_id, reliable_get_buf(), reliable_pid_in_range1(), reliable_pid_min(), reliable_print_ids(), and size.

Referenced by tls_process().

◆ reliable_get_buf_sequenced()

struct buffer* reliable_get_buf_sequenced ( struct reliable rel)

Get the buffer of the next sequential and active entry.

Parameters
relThe reliable structure from which to retrieve the buffer.
Returns
A pointer to the buffer of the entry with the next sequential key ID. If no such entry is present, this function returns NULL.

Definition at line 528 of file reliable.c.

References reliable_entry::active, array, reliable_entry::buf, reliable_entry::packet_id, packet_id, and size.

Referenced by tls_process().

◆ reliable_init()

void reliable_init ( struct reliable rel,
int  buf_size,
int  offset,
int  array_size,
bool  hold 
)

Initialize a reliable structure.

Parameters
relThe reliable structure to initialize.
buf_sizeThe size of the buffers in which packets will be stored.
offsetThe size of reserved space at the beginning of the buffers to allow efficient header prepending.
array_sizeThe number of packets that this reliable structure can store simultaneously.
holddescription

Definition at line 311 of file reliable.c.

References alloc_buf(), array, ASSERT, reliable_entry::buf, buf_init, CLEAR, hold, buffer::offset, offset, RELIABLE_CAPACITY, and size.

Referenced by key_state_init().

◆ reliable_mark_active_incoming()

void reliable_mark_active_incoming ( struct reliable rel,
struct buffer buf,
packet_id_type  pid,
int  opcode 
)

Mark the reliable entry associated with the given buffer as active incoming.

Parameters
relThe reliable structure associated with this packet.
bufThe buffer into which the packet has been copied.
pidThe packet's packet ID.
opcodeThe packet's opcode.

Definition at line 690 of file reliable.c.

References reliable_entry::active, array, ASSERT, reliable_entry::buf, D_REL_DEBUG, dmsg, reliable_entry::next_try, reliable_entry::opcode, reliable_entry::packet_id, packet_id, packet_id_format, reliable_pid_min(), size, and reliable_entry::timeout.

Referenced by tls_pre_decrypt().

◆ reliable_mark_active_outgoing()

void reliable_mark_active_outgoing ( struct reliable rel,
struct buffer buf,
int  opcode 
)

Mark the reliable entry associated with the given buffer as active outgoing.

Parameters
relThe reliable structure for handling this VPN tunnel's outgoing packets.
bufThe buffer previously returned by reliable_get_buf_output_sequenced() into which the packet has been copied.
opcodeThe packet's opcode.

Definition at line 722 of file reliable.c.

References reliable_entry::active, array, ASSERT, reliable_entry::buf, buf_write_prepend(), D_REL_DEBUG, dmsg, htonpid, initial_timeout, reliable_entry::next_try, reliable_entry::opcode, reliable_entry::packet_id, packet_id, packet_id_format, size, and reliable_entry::timeout.

Referenced by tls_process().

◆ reliable_mark_deleted()

void reliable_mark_deleted ( struct reliable rel,
struct buffer buf,
bool  inc_pid 
)

Remove an entry from a reliable structure.

Parameters
relThe reliable structure associated with the given buffer.
bufThe buffer of the reliable entry which is to be removed.
inc_pidIf true, the reliable structure's packet ID counter will be incremented.

Definition at line 749 of file reliable.c.

References reliable_entry::active, array, ASSERT, reliable_entry::buf, dummy(), initial_timeout, buffer::len, reliable_ack::len, reliable_entry::next_try, now, reliable_ack::packet_id, reliable_entry::packet_id, packet_id, packet_id_format, reliable_ack_debug_print(), reliable_debug_print(), size, and update_time().

Referenced by tls_process().

◆ reliable_not_replay()

bool reliable_not_replay ( const struct reliable rel,
packet_id_type  id 
)

Check that a received packet's ID is not a replay.

Parameters
relThe reliable structure for handling this VPN tunnel's received packets.
idThe packet ID of the received packet.
Returns
  • True, if the packet ID is not a replay.
  • False, if the packet ID is a replay.

Definition at line 428 of file reliable.c.

References reliable_entry::active, array, D_REL_DEBUG, dmsg, gc_free(), gc_new(), reliable_entry::packet_id, packet_id, packet_id_format, reliable_pid_min(), reliable_print_ids(), and size.

Referenced by tls_pre_decrypt().

◆ reliable_schedule_now()

void reliable_schedule_now ( struct reliable rel)

Reschedule all entries of a reliable structure to be ready for (re)sending immediately.

Parameters
relThe reliable structure of which the entries should be modified.

Definition at line 634 of file reliable.c.

References reliable_entry::active, array, D_REL_DEBUG, dmsg, hold, initial_timeout, reliable_entry::next_try, now, size, and reliable_entry::timeout.

Referenced by tls_pre_decrypt().

◆ reliable_send()

struct buffer* reliable_send ( struct reliable rel,
int *  opcode 
)

Get the next packet to send to the remote peer.

This function looks for the active entry ready for (re)sending with the lowest packet ID, and returns the buffer associated with it. This function also resets the timeout after which that entry will become ready for resending again.

Parameters
relThe reliable structure to check.
opcodeA pointer to an integer in which this function will store the opcode of the next packet to be sent.
Returns
A pointer to the buffer of the next entry to be sent, or NULL if there are no entries ready for (re)sending present in the reliable structure. If a valid pointer is returned, then opcode will point to the opcode of that packet.

Definition at line 596 of file reliable.c.

References reliable_entry::active, array, reliable_entry::buf, D_REL_DEBUG, dmsg, buffer::len, reliable_entry::next_try, now, reliable_entry::opcode, reliable_entry::packet_id, packet_id_format, reliable_pid_min(), reliable_unique_retry(), size, and reliable_entry::timeout.

Referenced by tls_process().

◆ reliable_send_purge()

void reliable_send_purge ( struct reliable rel,
struct reliable_ack ack 
)

Remove acknowledged packets from a reliable structure.

Parameters
relThe reliable structure storing sent packets.
ackThe acknowledgment structure containing received acknowledgments.

Definition at line 357 of file reliable.c.

References reliable_entry::active, array, D_REL_DEBUG, dmsg, reliable_ack::len, M_INFO, msg, reliable_entry::next_try, now, reliable_ack::packet_id, reliable_entry::packet_id, packet_id_format, and size.

Referenced by tls_pre_decrypt().

◆ reliable_send_timeout()

interval_t reliable_send_timeout ( const struct reliable rel)

Determined how many seconds until the earliest resend should be attempted.

Parameters
relThe reliable structured to check.
Returns
The interval in seconds until the earliest resend attempt of the outgoing packets stored in the rel reliable structure. If the next time for attempting resending of one or more packets has already passed, this function will return 0.

Definition at line 653 of file reliable.c.

References reliable_entry::active, array, BIG_TIMEOUT, D_REL_DEBUG, dmsg, gc_free(), gc_new(), min_int(), reliable_entry::next_try, now, reliable_print_ids(), and size.

Referenced by tls_process().

◆ reliable_set_timeout()

static void reliable_set_timeout ( struct reliable rel,
interval_t  timeout 
)
inlinestatic

Definition at line 467 of file reliable.h.

Referenced by key_state_init().

◆ reliable_wont_break_sequentiality()

bool reliable_wont_break_sequentiality ( const struct reliable rel,
packet_id_type  id 
)

Check that a received packet's ID can safely be stored in the reliable structure's processing window.

This function checks the difference between the received packet's ID and the lowest non-acknowledged packet ID in the given reliable structure. If that difference is larger than the total number of packets which can be stored, then this packet cannot be stored safely, because the reliable structure could possibly fill up without leaving room for all intervening packets. In that case, this received packet could break the reliable structure's sequentiality, and must therefore be discarded.

Parameters
relThe reliable structure for handling this VPN tunnel's received packets.
idThe packet ID of the received packet.
Returns
  • True, if the packet can safely be stored.
  • False, if the packet does not fit safely in the reliable structure's processing window.

Definition at line 455 of file reliable.c.

References D_REL_DEBUG, D_REL_LOW, dmsg, gc_free(), gc_new(), packet_id, packet_id_format, reliable_pid_in_range2(), reliable_print_ids(), and size.

Referenced by tls_pre_decrypt().