policy TLS_FORWARDING: rename pin to pin_sha256

The pin parameter contains SHA-256 encoded using Base64, but this is not
the only option. Explicit name allows us to add alternative formats
later on, and is consistent with GnuTLS naming.

modules/policy/README.rst

@@ -61,17 +61,17 @@ TLS Examples
 
 	modules = { 'policy' }
 	-- forward all queries over TLS to the specified server
-	policy.add(policy.all(policy.TLS_FORWARD({{'192.0.2.1', pin='YQ=='}})))
+	policy.add(policy.all(policy.TLS_FORWARD({{'192.0.2.1', pin_sha256='YQ=='}})))
 	-- for brevity, other TLS examples omit policy.add(policy.all())
-	-- single server authenticated using its certificate pin
-	  policy.TLS_FORWARD({{'192.0.2.1', pin='YQ=='}})  -- pin is base64-encoded
+	-- single server authenticated using its certificate pin_sha256
+	  policy.TLS_FORWARD({{'192.0.2.1', pin_sha256='YQ=='}})  -- pin_sha256 is base64-encoded
 	-- single server using non-standard port
-	  policy.TLS_FORWARD({{'192.0.2.1@443', pin='YQ=='}})  -- use @ or # to specify port
+	  policy.TLS_FORWARD({{'192.0.2.1@443', pin_sha256='YQ=='}})  -- use @ or # to specify port
 	-- single server with multiple valid pins (e.g. anycast)
-	  policy.TLS_FORWARD({{'192.0.2.1', pin={'YQ==', 'Wg=='}})
+	  policy.TLS_FORWARD({{'192.0.2.1', pin_sha256={'YQ==', 'Wg=='}})
 	-- multiple servers, each with own authenticator
 	  policy.TLS_FORWARD({ -- please note that { here starts list of servers
-		{'192.0.2.1', pin='Wg=='},
+		{'192.0.2.1', pin_sha256='Wg=='},
 		-- server must present certificate issued by specified CA and hostname must match
 		{'2001:DB8::d0c', hostname='res.example.', ca_file='/etc/knot-resolver/tlsca.crt'}
 	})

modules/policy/policy.lua

@@ -155,15 +155,15 @@ end
 
 -- Check for allowed authentication types and return type for the current target
 local function tls_forward_target_authtype(idx, target)
-	if (target.pin and not (target.ca_file or target.hostname or target.insecure)) then
-		if not is_nonempty_string_or_table(target.pin) then
+	if (target.pin_sha256 and not (target.ca_file or target.hostname or target.insecure)) then
+		if not is_nonempty_string_or_table(target.pin_sha256) then
 			error('TLS_FORWARD target authentication is invalid at position '
-			      .. idx .. '; pin must be string or list of strings')
+			      .. idx .. '; pin_sha256 must be string or list of strings')
 		end
-		return 'pin'
-	elseif (target.insecure and not (target.ca_file or target.hostname or target.pin)) then
+		return 'pin_sha256'
+	elseif (target.insecure and not (target.ca_file or target.hostname or target.pin_sha256)) then
 		return 'insecure'
-	elseif (target.ca_file and target.hostname and not (target.insecure or target.pin)) then
+	elseif (target.ca_file and target.hostname and not (target.insecure or target.pin_sha256)) then
 		if not (is_nonempty_string_or_table(target.hostname)
 			and is_nonempty_string_or_table(target.ca_file)) then
 			error('TLS_FORWARD target authentication is invalid at position '
@@ -172,7 +172,7 @@ local function tls_forward_target_authtype(idx, target)
 		return 'cert'
 	else
 		error('TLS_FORWARD authentication options at position ' .. idx
-		      .. ' are invalid; specify one of: pin / hostname+ca_file / insecure')
+		      .. ' are invalid; specify one of: pin_sha256 / hostname+ca_file / insecure')
 	end
 end
 
@@ -213,9 +213,9 @@ local function tls_forward(target)
 			hostnames[sockaddr_lua] = {}
 			insert_from_string_or_table(upstream_list_entry.ca_file, ca_files[sockaddr_lua])
 			insert_from_string_or_table(upstream_list_entry.hostname, hostnames[sockaddr_lua])
-		elseif auth_type == 'pin' then
+		elseif auth_type == 'pin_sha256' then
 			pins[sockaddr_lua] = {}
-			insert_from_string_or_table(upstream_list_entry.pin, pins[sockaddr_lua])
+			insert_from_string_or_table(upstream_list_entry.pin_sha256, pins[sockaddr_lua])
 		elseif auth_type ~= 'insecure' then
 			-- insecure does nothing, user does not want authentication
 			assert(false, 'unsupported auth_type')
@@ -227,7 +227,7 @@ local function tls_forward(target)
 		assert(#config.string_addr > 0)
 		if config.auth_type == 'insecure' then
 			net.tls_client(config.string_addr)
-		elseif config.auth_type == 'pin' then
+		elseif config.auth_type == 'pin_sha256' then
 			assert(#pins[sockaddr_lua] > 0)
 			net.tls_client(config.string_addr, pins[sockaddr_lua])
 		elseif config.auth_type == 'cert' then

modules/policy/policy_test.lua

@@ -21,13 +21,13 @@ local function test_tls_forward()
 			       {'100:dead::@443', insecure=true}
 			   }), 'TLS_FORWARD with duplicate IP addresses but different ports is allowed')
 
-	boom(policy.TLS_FORWARD, {{{'::1', pin=''}}}, 'TLS_FORWARD with empty pin')
-	-- boom(policy.TLS_FORWARD, {{{'::1', pin='č'}}}, 'TLS_FORWARD with bad pin')
+	boom(policy.TLS_FORWARD, {{{'::1', pin_sha256=''}}}, 'TLS_FORWARD with empty pin_sha256')
+	-- boom(policy.TLS_FORWARD, {{{'::1', pin_sha256='č'}}}, 'TLS_FORWARD with bad pin_sha256')
 	ok(policy.TLS_FORWARD({
-			{'::1', pin='ZTNiMGM0NDI5OGZjMWMxNDlhZmJmNGM4OTk2ZmI5MjQyN2FlNDFlNDY0OWI5MzRjYTQ5NTk5MWI3ODUyYjg1NQ=='}
-		}), 'TLS_FORWARD with base64 pin')
+			{'::1', pin_sha256='ZTNiMGM0NDI5OGZjMWMxNDlhZmJmNGM4OTk2ZmI5MjQyN2FlNDFlNDY0OWI5MzRjYTQ5NTk5MWI3ODUyYjg1NQ=='}
+		}), 'TLS_FORWARD with base64 pin_sha256')
 	ok(policy.TLS_FORWARD({
-		{'::1', pin={
+		{'::1', pin_sha256={
 			'ZTNiMGM0NDI5OGZjMWMxNDlhZmJmNGM4OTk2ZmI5MjQyN2FlNDFlNDY0OWI5MzRjYTQ5NTk5MWI3ODUyYjg1NQ==',
 			'MTcwYWUzMGNjZDlmYmE2MzBhZjhjZGE2ODQxZTAwYzZiNjU3OWNlYzc3NmQ0MTllNzAyZTIwYzY5YzQ4OGZmOA=='
 		}}}), 'TLS_FORWARD with table of pins')