Replace keep-address-family with allocation-default-address-family

ChangeLog

@@ -6,6 +6,8 @@ Version 4.5.3 'dan Eider':
 	- typo fix in prometheus (by fcecagno)
 	- merge PR #687 (by Wuelber Castillo)
 		* Add hash algorithm for hmackey value to redis userdb schema docs
+	- Replace keep-address-family with allocation-default-address-family (keep-address-family deprecated and will be removed!!)
+
 10/01/2021 Oleg Moskalenko <[email protected]> Mihály Mészáros <[email protected]>
 Version 4.5.2 'dan Eider':
 	- fix null pointer dereference in case of out of memory. (thanks to Thomas Moeller for the report)

README.turnserver

@@ -566,10 +566,17 @@ Options with values:
 --proc-group		Group name to run the process. After the initialization, the turnserver process
 			will make an attempt to change the current group ID to that group.
 
--K, --keep-address-family		TURN server allocates address family according TURN
+-K, --keep-address-family			Deprecated and will be removed in favor of --allocation-default-address-family!!
+			TURN server allocates address family according TURN
 			Client <=> Server communication address family.
 			!! It breaks RFC6156 section-4.2 (violates default IPv4) !!
 
+-A --allocation-default-address-family=<ipv4|ipv6|keep> 		Default is IPv4
+			TURN server allocates address family according TURN client requested address family.
+			If address family not requested explicitly by the client, then it falls back to this default.
+			The standard RFC explicitly define that this default must be IPv4, 
+			so use other option values with care!
+
 --cli-ip		Local system IP address to be used for CLI management interface.
 			The turnserver process can be accessed for management with telnet,
 			at this IP address and on the CLI port (see the next parameter).

examples/etc/turnserver.conf

@@ -658,7 +658,7 @@
 #
 #mobility
 
-# Allocate Address Family according
+# Allocate Address Family according (DEPRECATED and will be removed in favour of allocation-default-address-family)
 # If enabled then TURN server allocates address family according  the TURN
 # Client <=> Server communication address family.
 # (By default Coturn works according RFC 6156.)
@@ -666,6 +666,16 @@
 #
 #keep-address-family
 
+# TURN server allocates address family according TURN client requested address family.
+# If address family not requested explicitly by the client, then it falls back to this default.
+# The standard RFC explicitly define that this default must be IPv4, 
+# so use other option values with care! 
+# Possible values: "ipv4" or "ipv6" or "keep" 
+# "keep" sets the allocation default address family according to 
+# the TURN client allocation request connection address family.
+#allocation-default-address-family="ipv4"
+#allocation-default-address-family="ipv4"
+
 
 # User name to run the process. After the initialization, the turnserver process
 # will attempt to change the current user ID to that user.

man/man1/turnadmin.1

@@ -1,5 +1,5 @@
 .\" Text automatically generated by txt2man
-.TH TURN 1 "10 January 2021" "" ""
+.TH TURN 1 "12 March 2021" "" ""
 .SH GENERAL INFORMATION
 
 \fIturnadmin\fP is a TURN administration tool. This tool can be used to manage

man/man1/turnserver.1

@@ -1,5 +1,5 @@
 .\" Text automatically generated by txt2man
-.TH TURN 1 "10 January 2021" "" ""
+.TH TURN 1 "12 March 2021" "" ""
 .SH GENERAL INFORMATION
 
 The \fBTURN Server\fP project contains the source code of a TURN server and TURN client
@@ -815,11 +815,20 @@ will make an attempt to change the current group ID to that group.
 .TP
 .B
 \fB\-K\fP, \fB\-\-keep\-address\-family\fP
+Deprecated and will be removed in favor of \fB\-\-allocation\-default\-address\-family\fP!!
 TURN server allocates address family according TURN
 Client <=> Server communication address family.
 !! It breaks RFC6156 section\-4.2 (violates default IPv4) !!
 .TP
 .B
+\fB\-A\fP \fB\-\-allocation\-default\-address\-family\fP=<ipv4|ipv6|keep>
+Default is IPv4
+TURN server allocates address family according TURN client requested address family.
+If address family not requested explicitly by the client, then it falls back to this default.
+The standard RFC explicitly define that this default must be IPv4, 
+so use other option values with care!
+.TP
+.B
 \fB\-\-cli\-ip\fP
 Local system IP address to be used for CLI management interface.
 The \fIturnserver\fP process can be accessed for management with telnet,

man/man1/turnutils.1

@@ -1,5 +1,5 @@
 .\" Text automatically generated by txt2man
-.TH TURN 1 "10 January 2021" "" ""
+.TH TURN 1 "12 March 2021" "" ""
 .SH GENERAL INFORMATION
 
 A set of turnutils_* programs provides some utility functionality to be used

src/apps/relay/mainrelay.c

@@ -167,7 +167,7 @@ DEFAULT_CPUS_NUMBER,
 ///////// Encryption /////////
 "", /* secret_key_file */
 "", /* secret_key */
-0,  /* keep_address_family */
+ALLOCATION_DEFAULT_ADDRESS_FAMILY_IPV4,  /* allocation_default_address_family */
 0,  /* no_auth_pings */
 0,  /* no_dynamic_ip_list */
 0,  /* no_dynamic_realms */
@@ -645,9 +645,15 @@ static char Usage[] = "Usage: turnserver [options]\n"
 "						After the initialization, the turnserver process\n"
 "						will make an attempt to change the current group ID to that group.\n"
 " --mobility					Mobility with ICE (MICE) specs support.\n"
-" -K, --keep-address-family			TURN server allocates address family according TURN\n"
-"						Client <=> Server communication address family. \n"
+" -K, --keep-address-family			Deprecated in favor of --allocation-default-address-family!!\n"
+"						TURN server allocates address family according TURN\n"
+"						Client <=> Server communication address family.\n"
 "						!! It breaks RFC6156 section-4.2 (violates default IPv4) !!\n"
+" -A --allocation-default-address-family=<ipv4|ipv6|keep> 		Default is IPv4\n"
+"						TURN server allocates address family according TURN client requested address family. \n"
+"						If address family is not requested explicitly by client, then it falls back to this default.\n"
+"						The standard RFC explicitly define actually that this default must be IPv4,\n"
+"                       so use other option values with care!\n"
 " --no-cli					Turn OFF the CLI support. By default it is always ON.\n"
 " --cli-ip=<IP>					Local system IP address to be used for CLI server endpoint. Default value\n"
 "						is 127.0.0.1.\n"
@@ -661,7 +667,7 @@ static char Usage[] = "Usage: turnserver [options]\n"
 "						is 127.0.0.1.\n"
 " --web-admin-port=<port>			Web-admin server port. Default is 8080.\n"
 " --web-admin-listen-on-workers			Enable for web-admin server to listens on STUN/TURN workers STUN/TURN ports.\n"
-"						By default it is disabled for security resons!\n"
+"						By default it is disabled for security reasons!\n"
 "						(This behavior used to be the default behavior, and was enabled by default.)\n"
 " --server-relay					Server relay. NON-STANDARD AND DANGEROUS OPTION. Only for those applications\n"
 "						when we want to run server applications on the relay endpoints.\n"
@@ -731,7 +737,7 @@ static char AdminUsage[] = "Usage: turnadmin [command] [options]\n"
 	"					Setting to zero value means removal of the option.\n"
 	"	-h, --help			Help\n";
 
-#define OPTIONS "c:d:p:L:E:X:i:m:l:r:u:b:B:e:M:J:N:O:q:Q:s:C:K:vVofhznaAS"
+#define OPTIONS "c:d:p:L:E:X:i:m:l:r:u:b:B:e:M:J:N:O:q:Q:s:C:K:A:vVofhznaS"
 
 #define ADMIN_OPTIONS "PEgGORIHKYlLkaADSdb:e:M:J:N:u:r:p:s:X:o:h:x:v:f:"
 
@@ -949,6 +955,7 @@ static const struct myoption long_options[] = {
 				{ "no-tlsv1_2", optional_argument, NULL, NO_TLSV1_2_OPT },
 				{ "secret-key-file", required_argument, NULL, SECRET_KEY_OPT },
 				{ "keep-address-family", optional_argument, NULL, 'K' },
+				{ "allocation-default-address-family", required_argument, NULL, 'A' },
 				{ "acme-redirect", required_argument, NULL, ACME_REDIRECT_OPT },
 				{ "log-binding", optional_argument, NULL, LOG_BINDING_OPT },
 
@@ -1169,7 +1176,24 @@ static void set_option(int c, char *value)
 
   switch (c) {
 	case 'K':
-		turn_params.keep_address_family = get_bool_value(value);
+		if (get_bool_value(value))
+			turn_params.allocation_default_address_family = ALLOCATION_DEFAULT_ADDRESS_FAMILY_KEEP;
+		break;
+	case 'A':
+		if (value && strlen(value) > 0) {
+			if(*value == '=') ++value;
+			if (!strcmp(value, "ipv6")) {
+				turn_params.allocation_default_address_family = ALLOCATION_DEFAULT_ADDRESS_FAMILY_IPV6;
+			} else if (!strcmp(value,"keep")) {
+				turn_params.allocation_default_address_family = ALLOCATION_DEFAULT_ADDRESS_FAMILY_KEEP;
+			} else if (!strcmp(value, "ipv4")) {
+				turn_params.allocation_default_address_family = ALLOCATION_DEFAULT_ADDRESS_FAMILY_IPV4;
+			} else {
+				TURN_LOG_FUNC(TURN_LOG_LEVEL_ERROR, "ERROR: invalid allocation_default_address_family parameter\n");
+			}
+		} else {
+			TURN_LOG_FUNC(TURN_LOG_LEVEL_ERROR, "ERROR: invalid allocation_default_address_family parameter\n");
+		}
 		break;
   case SERVER_NAME_OPT:
 	  STRCPY(turn_params.oauth_server_name,value);

src/apps/relay/mainrelay.h

@@ -332,7 +332,7 @@ typedef struct _turn_params_ {
   ///////// Encryption /////////
   char secret_key_file[1025];
   unsigned char secret_key[1025];
-  int keep_address_family;
+  ALLOCATION_DEFAULT_ADDRESS_FAMILY allocation_default_address_family;
   int no_auth_pings;
   int no_dynamic_ip_list;
   int no_dynamic_realms;

src/apps/relay/netengine.c

@@ -1676,7 +1676,7 @@ static void setup_relay_server(struct relay_server *rs, ioa_engine_handle e, int
 			 turn_params.oauth,
 			 turn_params.oauth_server_name,
 			 turn_params.acme_redirect,
-			 turn_params.keep_address_family,
+			 turn_params.allocation_default_address_family,
 			 &turn_params.log_binding);
 	
 	if(to_set_rfc5780) {

src/server/ns_turn_server.c

@@ -1284,31 +1284,30 @@ static int handle_turn_allocate(turn_turnserver *server,
 
 				if(!(*err_code)) {
 					if(!af4 && !af6) {
-						int a_family = STUN_ATTRIBUTE_REQUESTED_ADDRESS_FAMILY_VALUE_DEFAULT;
-						if (server->keep_address_family) {
-							switch(get_ioa_socket_address_family(ss->client_socket)) {
-								case AF_INET6 :
-									a_family = STUN_ATTRIBUTE_REQUESTED_ADDRESS_FAMILY_VALUE_IPV6;
-									break;
-								case AF_INET :
-									a_family = STUN_ATTRIBUTE_REQUESTED_ADDRESS_FAMILY_VALUE_IPV4;
-									break;
-							}
-						}
-
-						int res = create_relay_connection(server, ss, lifetime,
-						a_family, transport,
-						even_port, in_reservation_token, &out_reservation_token,
-						err_code, reason,
-						tcp_peer_accept_connection);
-
-						if(res<0) {
-							set_relay_session_failure(alloc,AF_INET);
-							if(!(*err_code)) {
-								*err_code = 437;
-							}
+						switch (server->allocation_default_address_family) {
+							case ALLOCATION_DEFAULT_ADDRESS_FAMILY_KEEP:
+								switch(get_ioa_socket_address_family(ss->client_socket)) {
+									case AF_INET6 :
+										af6 = STUN_ATTRIBUTE_REQUESTED_ADDRESS_FAMILY_VALUE_IPV6;
+										break;
+									case AF_INET :
+									default:
+										af4 = STUN_ATTRIBUTE_REQUESTED_ADDRESS_FAMILY_VALUE_IPV4;
+										break;
+								}
+								break;
+							case ALLOCATION_DEFAULT_ADDRESS_FAMILY_IPV6:
+								af6 = STUN_ATTRIBUTE_REQUESTED_ADDRESS_FAMILY_VALUE_IPV6;
+								break;
+							case ALLOCATION_DEFAULT_ADDRESS_FAMILY_IPV4:
+								/* no break */
+								/* Falls through. */
+							default:
+								af4 = STUN_ATTRIBUTE_REQUESTED_ADDRESS_FAMILY_VALUE_IPV4;
+								break;
 						}
-					} else if(!af4 && af6) {
+					}
+					if(!af4 && af6) {
 						int af6res = create_relay_connection(server, ss, lifetime,
 							af6, transport,
 							even_port, in_reservation_token, &out_reservation_token,
@@ -4932,7 +4931,7 @@ void init_turn_server(turn_turnserver* server,
 		int oauth,
 		const char* oauth_server_name,
 		const char* acme_redirect,
-		int keep_address_family,
+		ALLOCATION_DEFAULT_ADDRESS_FAMILY allocation_default_address_family,
 		vintp log_binding) {
 
 	if (!server)
@@ -5002,7 +5001,7 @@ void init_turn_server(turn_turnserver* server,
 
 	server->allocate_bps_func = allocate_bps_func;
 
-	server->keep_address_family = keep_address_family;
+	server->allocation_default_address_family = allocation_default_address_family;
 
 	set_ioa_timer(server->e, 1, 0, timer_timeout_handler, server, 1, "timer_timeout_handler");
 

src/server/ns_turn_server.h

@@ -75,6 +75,14 @@ enum _MESSAGE_TO_RELAY_TYPE {
 };
 typedef enum _MESSAGE_TO_RELAY_TYPE MESSAGE_TO_RELAY_TYPE;
 
+///////// ALLOCATION DEFAULT ADDRESS FAMILY TYPES /////////////////////
+enum _ALLOCATION_DEFAULT_ADDRESS_FAMILY {
+	ALLOCATION_DEFAULT_ADDRESS_FAMILY_IPV4 = 0,
+	ALLOCATION_DEFAULT_ADDRESS_FAMILY_IPV6,
+	ALLOCATION_DEFAULT_ADDRESS_FAMILY_KEEP,
+};
+typedef enum _ALLOCATION_DEFAULT_ADDRESS_FAMILY ALLOCATION_DEFAULT_ADDRESS_FAMILY;
+
 struct socket_message {
 	ioa_socket_handle s;
 	ioa_net_data nd;
@@ -174,8 +182,8 @@ struct _turn_turnserver {
 	/* ACME redirect URL */
 	const char* acme_redirect;
 
-	/* Keep Address Family */
-	int keep_address_family;
+	/* Allocation Default Address Family */
+	ALLOCATION_DEFAULT_ADDRESS_FAMILY allocation_default_address_family;
 
 	/* Log Binding Requrest */
 	vintp log_binding;
@@ -225,7 +233,7 @@ void init_turn_server(turn_turnserver* server,
 				    int oauth,
 				    const char* oauth_server_name,
 					const char* acme_redirect,
-					int keep_address_family,
+					ALLOCATION_DEFAULT_ADDRESS_FAMILY allocation_default_address_family,
 					vintp log_binding);
 
 ioa_engine_handle turn_server_get_engine(turn_turnserver *s);