rest2wireguard

Alpine-based TLS-securely WebAPI-managed Wireguard server.

Useable for both personal and enterprise purposes.

Breaking changes is coming with the 'v2' branch. However, older versions will not be removed and current master will be saved as 'v1'.

Quick start:

docker run --cap-add NET_ADMIN -p 51850:51820/udp -p 51851:51821/tcp --env REST2WG_ALLOW_NOAUTH=true luminodiode/rest2wireguard

You will get the image listening 51850 by Wireguard and 51851 by WebAPI with TLS encryption without authorization request header required. You can also expose 51822 port if you want to make requests without TLS encryption. Dont forget to allow ports in your UFW if there is one:

ufw allow 51850/udp && ufw allow 51851/tcp

Now you can access next endpoints:

• GET /api/status - always returns 200_OK (if not 401). May return Authorization header HMAC in body.
• GET /api/peers[?withCleanup=false] - get list of all peers [and remove outdated].
• PUT /api/peers - add new peer.
• PATCH /api/peers - remove existing peer.
• DELETE /api/peers/{PubkeyBase64Url} - do the same as above but without RFC 9110 violation.

Where for PUT and PATCH endpoints you must provide application/json body in the next format:

{
    "publicKey":"LwkXubXSXLOzQPK0a6PQp1DWz08lsfk+Oyp7s1056H8="
}

And the response format for PUT endpoint will be:

{
    "allowedIps": "10.6.0.29/32",
    "interfacePublicKey": "3CTcRIiXHORtMLdYJ0F1AqsQITiH6WEPXZxHjuMgqDY="
}

Now you can connect wireguard client to your server. Example configuration:

[Interface]
PrivateKey = YBth+re5L1qqO+O6kjB72RbZUZMmu8KxL0ppjyGyfmk=
Address = 10.6.0.29/32
DNS = 8.8.8.8

[Peer]
PublicKey = 3CTcRIiXHORtMLdYJ0F1AqsQITiH6WEPXZxHjuMgqDY=
AllowedIPs = 0.0.0.0/0
Endpoint = YOUR.SERVER.IP.ADDRESS:51850

If you want to use authorization

You need to leave REST2WG_ALLOW_NOAUTH unset (false is the default value). Then generate the key and its hash. You can open this url, click 'Run' and copy generated key-hash pair or run this code on your machine locally. You will get the next output:

Key base64 (for client):
zXCzMDwZt/bMTrT+rt08cH6XH+ut61LJRKEa+OLRJEMgegUv4HLxp9sB1+FnKJYkImn7Sh64eDRs1PtwV5ptmQ==

Key hash base64 (for server):
EbnejPeYabvB709y/3a/ubyUHqiCwjJqLWw0PE0AzSDTxHF+fXrKIagzSBKMF/2pwkrKk2KUhUNm6mhyUajFlA==

The first value is the key itself, base64 encoded. You will need to pass it with your requests Authorization header in the next format:

Authorization: Basic zXCzMDwZt/bMTrT+rt08cH6XH+ut61LJRKEa+OLRJEMgegUv4HLxp9sB1+FnKJYkImn7Sh64eDRs1PtwV5ptmQ==

The second value is the key hash, base64 encoded. You will need to pass it to your docker container with the enviroment variable (if you want to pass it using docker secrets - read the full reference below):

--env REST2WG_AUTH_KEYHASH_BASE64=EbnejPeYabvB709y/3a/ubyUHqiCwjJqLWw0PE0AzSDTxHF+fXrKIagzSBKMF/2pwkrKk2KUhUNm6mhyUajFlA==

Be aware, the data is not encrypted here, just encoded. If you are using auth you should pass your requests to the 51821 port only, using TLS. Becouse we are using self-signed certificate, we need to verify the server. For this purpose GET /api/status may return Authorization header HmacSha512 if auth is enabled and the "SecretSigningKey" was provided in aspsecrets.json (see the format below). In this case response body will be:

{ "authKeyHmacSha512Base64": "6CzINt2nQqR1/xV5hjOj48b3NAxt0LjzJ4qlzc0IfZifuTK5sbvAoN1ExQXz3RZsBHRquc6cSs6vKkM1ud8N7Q==" }

Full list of environment variables

• NGINX

  • REST2WG_LIMIT_REQ - limit requests per second for every address (0.1 = 6 requests per minute etc.).
    • Valid range: 0.001<VALUE<10^7.
    • Default: 100000.
  • REST2WG_ALLOWED_IP - allow requests only from specified address.
    • Valid range: any IP-address.
    • Default: all.

• ASP WebAPI

  • REST2WG_ALLOW_NOAUTH - disable authorization header validation.
    • Valid range: true/false.
    • Default: false.
  • REST2WG_AUTH_KEYHASH_BASE64 - add specified key hash to the collection provided by aspsecrets.json.
    • Valid range: any base64-encoded string.
    • Default: null.
  • REST2WG_IGNORE_UNAUTHORIZED - server will not send any data back on an unauthorized request. It will be invisible.
    • Valid range: true/false.
    • Default: false.
  • REST2WG_HANDSHAKE_AGO_LIMIT - peer is removed on review if latest handshake occured more than VALUE seconds ago.
    • Valid range: 0<VALUE<2^31
    • Default: 2^31.
  • REST2WG_REVIEW_INTERVAL - interval of peers review and removing outdated (in seconds).
    • Valid range: 0<VALUE<2^21 (not 31!)
    • Default: 0.
    • Special value: 0 - review is never performed automatically.
  • REST2WG_SAVE_CONFIG_ON_CHANGE - will the server save wireguard config to file on every peers change.
    • Valid range: true/false.
    • Default: true.
  • REST2WG_DISABLE_GET_PEERS - disables GET:api/peers endpoint, returning 503 response.
    • Valid range: true/false.
    • Default: false.
  • REST2WG_DISABLE_DELETE_PEERS - disables PATCH:api/peers endpoint, returning 503 response.
    • Valid range: true/false.
    • Default: false.
  • REST2WG_DISABLE_STATUS_HMAC - disables returning Authorization header key HmacSha512 on GET /api/status endpoint.
    • Valid range: true/false.
    • Default: false.

Full list of listened ports

• 51820 - udp wireguard port.
• 51821 - tcp nginx-to-api HTTP2 self-signed TLS port.
• 51822 - tcp nginx-to-api no-TLS port.

Using docker secrets

The ASP-application loads /run/secrets/aspsecrets.json file, which is default location for docker secrets. So if you want to use it, create file in the next format, where every directive is optional. Be aware, environmental variables are being added to the arrays (e.g. MasterAccounts), otherwise it will override the aspsecrets values.

{
    "Logging": {
        "LogLevel": {
            "Default": "Information",
            "Microsoft.AspNetCore": "Information"
        }
    },
    "MasterAccounts": [ {
        "KeyHashBase64": "vklVGRgH4LFwwTs1coxGwErshhzxqy6l8uIewY6/345k1RT1C1mwwe6p8btbw0iowWxwNkjbLINh4skdRO2lxA=="
    } ],
    "PeersBackgroundServiceSettings": {
        "PeersRenewIntervalSeconds": 0,
        "HandshakeAgoLimitSeconds": 300
    },
    "SecretSigningKey": {
        "KeyBase64": "vklVGRgH4LFwwTs1coxGwErshhzxqy6l8uIewY6/345k1RT1C1mwwe6p8btbw0iowWxwNkjbLINh4skdRO2lxA=="
    }
}

Then put your json with the compose file, configured the next way:

version: '3.4'

services:
  rest2wg_1:
    image: luminodiode/rest2wireguard
    cap_add:
      - NET_ADMIN
    ports:
      - "51850:51820/udp"
      - "51851:51821/tcp"
    secrets:
      - source: backSecs
        target: aspsecrets.json
        
secrets:
  backSecs:
    file: ./yourAspSecretsFile.json