Skip to content
The Things Stack documentation home
Getting Started Concepts Cloud Enterprise Integrations API Hardware
Getting Started Concepts
Cloud Enterprise
Integrations API Hardware
Get The Things Stack

    Recent searches

      Popular pages

      • Getting Started
      • Adding Gateways
      • Adding Devices
      • Payload Formatters
      • Webhooks
      • Authentication

      No results for “”.

      • Check the spelling, or try fewer or more general words.
      • Ask the community on The Things Network Forum
      • Contact support
      ↑↓ to navigate ↵ to open Esc to close

      Hardware

      • Overview
      • Devices
      • Gateways
        • Concepts
          • Adding Gateways
          • LoRa Basics™ Station
            • Configuration and Update Server (CUPS)
            • LoRaWAN Network Server (LNS)
            • Using CUPS to redirect to a different LNS
            • Implementation Guide
            • mTLS Authentication
          • Semtech UDP Packet Forwarder
          • The Things Industries Gateway Protocol
          • Packet Forwarders
          • Gateway Round Trip Times
        • Models
        • Troubleshooting Gateways
      • Works with The Things Stack

      mTLS Authentication

      Updated 13 February 2025 Edit on GitHub
      Copy page
      • View as MarkdownThis page as plain text
      • Open in ChatGPTAsk questions about this page
      • Open in ClaudeAsk questions about this page

      The Things Stack supports mutual TLS to authenticate LoRa Basics™ Station CUPS connections in selected deployments. This guide explains how gateway vendors/resellers and users can leverage

      To check if your deployment supports it, contact the operator.

      Procedure

      1. The gateway vendor or user generates a CA (Certificate Authority) credentials in a secure environment. This usually consists of a public X.509 certificate and a private key.
      • Usually, a Root CA and one or many intermediate CAs are generated. The Root CA is typically only used generate intermediate CAs and the intermediate CAs are used to sign client/leaf certificates.
      1. The gateway vendor generates unique TLS client certificates for each gateway.
      • The public certificate uniquely identifies the gateway. The Common Name (CN) field of the certificate should be exactly equal to the hex encoded EUI-64 (16 digits). The other fields are left to the user.
      • The private key is the counterpart of the public certificate and is used for cryptographic operations while connecting to The Things Stack. Gateway vendors must ensure that this key is not easily accessible from the gateway. Anyone in possession of this key can impersonate the gateway.
      • If using RSA to generate key pairs, we recommend a minimum size of 2048 bits.
      1. The gateway vendor/user sends the CA certificate used for signing the gateway credentials to the operator of The Things Stack deployment. The operator will configure these CAs in The Things Stack.

      2. The user of the gateway registers it on a The Things Stack deployment. See instructions for in the Adding Gateways guide.

      3. When this gateway make a CUPS /update-info request to The Things Stack, it presents the client certificate. The Things Stack verifies this certificate against the configured CA certificate. If the cryptographic check is successful, The Things Stack will check rest of the CUPS request and respond with the LNS credentials.

      4. The gateway can now be connected to the LNS endpoint with the credentials sent by the CUPS server and if everything is successful, the gateway will connect to The Things Stack.

      Testing

      In order to test mTLS authentication, you can generate self-signed certificates.

      Warning:

      This is only for testing. Do not use this process in production.
      1. Create a client gateway private key. Note you can choose any length of the key.
      $ openssl genrsa -out gateway.key 2048
      
      1. Create a Root CA:
      $ openssl req -x509 -sha256 -days 1825 -newkey rsa:2048 -keyout root-ca.key -out root-ca.crt
      
      1. Create a Certificate Signing Request for your client (Gateways):

      Note:

      The CN (Common Name) field must be the hex encoded EUI64 (16 digits). Example: 0123456789ABCDEF
      $ openssl req -key gateway.key -new -out gateway.csr
      
      1. Generate the client certificate. The following generates a gateway certificate signed by the Root CA valid for 365 days.
      $ openssl X.509 -req -CA root-ca.crt -CAkey root-ca.key -in gateway.csr -out gateway.crt -days 365 -CAcreateserial -sha256 -days 365
      
      1. Send this CA certificate root-ca.crt to the operator of the desired The Things Stack deployment.

      2. Connect using a client (e.g. cURL):

      curl -v --cert <path>/gateway.crt --key <path>/gateway.key --cacert <path>/root-ca.crt https://<domain>:8987/update-info -d '{"router":"<EUI in ID6>"}'
      
      1. If the request is successful, you will receive an HTTP 200 response code with a binary blob containing the LNS credentials.
      ← Implementation Guide Semtech UDP Packet Forwarder →

      On this page

      • Procedure
      • Testing

      Sections

      Getting Started

      Concepts

      Cloud

      Enterprise

      Integrations

      API

      Hardware

      Sitemap

      View our Sitemap

      Contributing

      GitHub

      About Us

      The Things Industries

      Privacy Policy

      Cookie settings

      Cookie Settings

      We use cookies to enhance your experience, analyze site traffic and deliver personalized content. Read our Privacy Policy.

      Cookie categories