The "gateway" Module (v4)
Description
This module adds the ability for IRC gateways to forward the real IP address of users connecting through them.
Configuration
To load this module use the following <module> tag:
<module name="gateway">
<gateway>
The <gateway> tag defines a specific IRC gateway. This tag can be defined as many times as required.
| Name | Type | Default Value | Description |
|---|---|---|---|
| fingerprint | Text | None | Required for the webirc type if password is not set! The TLS (SSL) client certificate fingerprint that the WebIRC gateway will authenticate with. |
| mask | Text | None | Required! The IP address or hostname of the gateway. |
| newusername | Text | gateway | If the username type is used then the value to replace usernames that contain hexadecimal-encoded IPv4 addresses. |
| type | Text | None | Required! The type of authentication that the gateway uses. |
| password | Text | None | Required for the webirc type if fingerprint is not set! The password that the WebIRC gateway will authenticate with. |
| hash | Text | None | If the webirc type is used the algorithm that the password is hashed with. |
| trustedflags | Text | * | If the webirc type is used a space-delimited list of flags to trust from a WebIRC gateway. |
The hash field is currently optional but will be required in the next major version of InspIRCd when using password authentication.
The following hashing modules are included with InspIRCd:
| Algorithm | Module(s) | Description |
|---|---|---|
| argon2d | argon2 | Hashes using the Argon2d algorithm. |
| argon2i | argon2 | Hashes using the Argon2i algorithm. |
| argon2id | argon2 | Hashes using the Argon2id algorithm. |
| bcrypt | bcrypt | Hashes using the bcrypt algorithm. |
| hmac-md5 | password_hash, md5 | Deprecated! Hashes using the MD5 and HMAC algorithms. |
| hmac-sha1 | password_hash, sha1 | Hashes using the SHA-1 and HMAC algorithms. |
| hmac-sha224 | password_hash, sha2 | Hashes using the SHA-224 and HMAC algorithms. |
| hmac-sha256 | password_hash, sha2 | Hashes using the SHA-256 and HMAC algorithms. |
| hmac-sha384 | password_hash, sha2 | Hashes using the SHA-384 and HMAC algorithms. |
| hmac-sha512 | password_hash, sha2 | Hashes using the SHA-512 and HMAC algorithms. |
| md5 | md5 | Deprecated! Hashes using the MD5 algorithm. |
| pbkdf2-hmac-md5 | pbkdf2, md5 | Deprecated! Hashes using the MD5 and PBKDF2 algorithms. |
| pbkdf2-hmac-sha1 | pbkdf2, sha1 | Hashes using the SHA-1 and PBKDF2 algorithms. |
| pbkdf2-hmac-sha224 | pbkdf2, sha2 | Hashes using the SHA-224 and PBKDF2 algorithms. |
| pbkdf2-hmac-sha256 | pbkdf2, sha2 | Hashes using the SHA-256 and PBKDF2 algorithms. |
| pbkdf2-hmac-sha384 | pbkdf2, sha2 | Hashes using the SHA-384 and PBKDF2 algorithms. |
| pbkdf2-hmac-sha512 | pbkdf2, sha2 | Hashes using the SHA-512 and PBKDF2 algorithms. |
| sha1 | sha1 | Hashes using the SHA-1 algorithm. |
| sha224 | sha2 | Hashes using the SHA-224 algorithm. |
| sha256 | sha2 | Hashes using the SHA-256 algorithm. |
| sha384 | sha2 | Hashes using the SHA-384 algorithm. |
| sha512 | sha2 | Hashes using the SHA-512 algorithm. |
The type field should be set to one of the following values:
| Value | Description |
|---|---|
| gateway | The IP address of the user will be sent in the username field in hexadecimal (IPv4 only). |
| webirc | The IP address of the user will be sent using the /WEBIRC command (recommended). |
Example Usage
Tells the gateway module that the *.username.gateway.example.com gateway will encode the IPv4 address of users into their username.
<gateway type="username"
mask="*.username.gateway.example.com"
newusername="wobble">
Tells the gateway module that gateways with an IP matching 192.0.2.0/24 will send the IP address of users with the /WEBIRC command using TLS (SSL) client certificate fingerprint authentication:
<gateway type="webirc"
fingerprint="bd90547b59c1942b85f382bc059318f4c6ca54c5"
mask="192.0.2.0/24">
Tells the gateway module that gateways with a hostname matching *.webirc.gateway.example.com will send the IP address of users with the /WEBIRC command using password authentication:
<gateway type="webirc"
password="$2a$10$WEUpX9GweJiEF1WxBDSkeODBstIBMlVPweQTG9cKM8/Vd58BeM5cW"
hash="bcrypt"
mask="*.webirc.gateway.example.com">
<connect>
This module extends the core <connect> tags with the following fields:
| Name | Type | Default Value | Description |
|---|---|---|---|
| webirc | Text | None | If defined then a glob pattern to match the name of a WebIRC gateway against. |
Example Usage
Requires that users must be connecting via the "wibble" WebIRC gateway to use the Example class:
<connect name="Example"
...
webirc="wibble">
Commands
| Name | Parameter Count | Syntax | Description |
|---|---|---|---|
| HEXIP | 1 | <hex-ip|real-ip> | Encodes or decodes an IP between its human readable form and its hex form. |
| WEBIRC | 4-5 | <password> <gateway> <hostname> <address> [<flags>] | Allows gateways to specify the hostname and IP address of users. |
More information about the /WEBIRC command is available on the IRCv3 website.
Example Usage
Decodes 7f000001 to its human readable form:
/HEXIP 7f000001
Encodes 127.0.0.1 to its hex form:
/HEXIP 127.0.0.1
Extended Bans
| Name | Character | Type | Ban Syntax | Description |
|---|---|---|---|---|
| gateway | w | Matching | [!]gateway:<pattern> | Matches against the name of the gateway that WebIRC users are connecting from. |
Server Notice Masks
| Character | Description |
|---|---|
| w | Notifications about gateways changing IP addresses on the local server. |
| W | Notifications about gateways changing IP addresses on a remote server. |
Special Notes
The /WEBIRC command should generally not be executed by users. It is intended to be an entirely internal feature which is executed automatically by gateways.