The "cloak_sha256" Module (v4)

Description

This module adds the hmac-sha256 and hmac-sha256-addr cloaking methods for use with the cloak module.

Configuration

To load this module use the following <module> tag:

<module name="cloak_sha256">

<cloak>

The <cloak> tag defines a cloaking profile. This tag can be defined as many times as required.

Name	Type	Default Value	Description
key	Text	None	A random 30+ character value to use as a secret key when cloaking. The longer this is the more secure it is.
prefix	Text	None	The value to prefix cloaks with.
suffix	Text	ip	The value to suffix IP address cloaks with.
case	Text	lower	Whether to use upper-case or lower-case characters when converting cloak hashes to a human-readable form.
hostparts	Number	3	If the hmac-sha256 method is used then the maximum number of DNS hostname segments that should be visible.
pathparts	Number	1	The maximum number of UNIX socket path segments that should be visible.
psl	Text	None	If defined and the module was built against libpsl then the path to a Public Suffix List database to use instead of <cloak:hostparts> for finding the public part of a hostname. Can also be set to system to use the system database.
class	String	None	If non-empty then a comma-delimited list of of connect classes that can receive this cloak.

This module also extends the <cloak:method> field with the following values:

Name	Description
hmac-sha256	If the user has a DNS hostname or is connecting via a UNIX socket then cloak with an HMAC-SHA256 hash of their hostname and socket path suffixed with the public part of that value. Otherwise, cloak with three HMAC-SHA256 hashes of significant ranges of their IP address (see below).
hmac-sha256-addr	If the user is connecting via a UNIX socket then cloak with an HMAC-SHA256 hash of their socket path suffixed with the public part of the path. Otherwise, cloak with three HMAC-SHA256 hashes of significant ranges of their IP address (see below).

The case field should be set to one of the following values:

Value	Description
lower	Use lower-case characters in the cloak hash.
upper	Use upper-case characters in the cloak hash.

Example Usage

Cloaking using the hmac-sha256 method:

<cloak method="hmac-sha256"
       key="changeme"
       prefix="MyNet"
       suffix="ip"
       case="lower"
       hostparts="3"
       pathparts="1"
       psl="system"
       class="">

Cloaking using the hmac-sha256-addr method:

<cloak method="hmac-sha256-addr"
       key="changeme"
       prefix="MyNet"
       suffix="ip"
       case="lower"
       pathparts="1"
       class="">

Special Notes

Assuming an IPv4 address of 12.23.34.45 and cloaked part of 74ero2cv.ucctzwrd.uyclsgi7 the cloak segments represent:

IPv4 Segment	Cloak Segment	CIDR Range
12.23.34.45	74ero2cv (1)	/32
12.23.34	ucctzwrd (2)	/24
12.23	uyclsgi7 (3)	/16

Assuming an IPv6 address of 2001:db8:dead:cafe:beef:feed:f00d:face and a cloaked part of 2rravfdm:zjmad7mb:l2kirwft the cloak segments represent:

IPv6 Segment	Cloak Segment	CIDR Range
2001:db8:dead:cafe:beef:feed:f00d:face	2rravfdm (1)	/128
2001:db8:dead:cafe:beef:feed:f00d	zjmad7mb (2)	/112
2001:db8:dead:cafe	l2kirwft (3)	/64