{"id":21371503,"url":"https://github.com/chirpstack/chirpstack-certificates","last_synced_at":"2026-01-03T00:32:08.666Z","repository":{"id":51797410,"uuid":"117255906","full_name":"chirpstack/chirpstack-certificates","owner":"chirpstack","description":"Scripts to generate certificates for the ChirpStack components.","archived":false,"fork":false,"pushed_at":"2023-06-14T14:34:46.000Z","size":16,"stargazers_count":34,"open_issues_count":2,"forks_count":22,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-01-22T20:51:51.071Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://www.chirpstack.io/","language":"Makefile","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chirpstack.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2018-01-12T15:17:30.000Z","updated_at":"2024-12-19T22:48:49.000Z","dependencies_parsed_at":"2024-03-26T16:44:47.249Z","dependency_job_id":null,"html_url":"https://github.com/chirpstack/chirpstack-certificates","commit_stats":null,"previous_names":["chirpstack/chirpstack-certificates"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chirpstack%2Fchirpstack-certificates","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chirpstack%2Fchirpstack-certificates/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chirpstack%2Fchirpstack-certificates/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chirpstack%2Fchirpstack-certificates/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chirpstack","download_url":"https://codeload.github.com/chirpstack/chirpstack-certificates/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243846982,"owners_count":20357297,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-22T08:13:41.022Z","updated_at":"2026-01-03T00:32:08.623Z","avatar_url":"https://github.com/chirpstack.png","language":"Makefile","readme":"# ChirpStack certificates\n\nThis repository contains configuration to generate certificates that can be\nused by [ChirpStack](https://www.chirpstack.io/) for securing gateway\nconnections and the per-application MQTT integration connections:\n\n* Generating a \"common authority\" for\n  * Signing (client-)certificates\n  * Validating (client-)certificates\n* Server-certificate for the ChirpStack Gateway Bridge to use mTLS if configured with the Basics Station backend\n* Server-certificate for the MQTT broker to allow mTLS based authentication and authorization for\n  * Gateways connecting over MQTT (certificate per Gateway ID)\n  * Per-application MQTT integrations (certificate per Application ID)\n\n## Requirements\n\nFor generating the certificates, [cfssl](https://github.com/cloudflare/cfssl)\nis used. Make sure you have this tool installed.\n\nTo modify the hosts using the `set-hosts` command you will need\n[jq](https://stedolan.github.io/jq/) installed.\n\n## Modifying hosts\n\nYou can modify all `certificate.json` files at once with specific hosts with the\n`make set-hosts` command:\n\n```\nMQTT_BROKER_HOSTS=127.0.0.1,localhost,mqtt.example.com \\\nCHIRPSTACK_GATEWAY_BRIDGE_HOSTS=127.0.0.1,localhost,cgwb.example.com \\\nmake set-hosts\n```\n\nThe `make set-hosts` accepts the following environment variables:\n\n* `MQTT_BROKER_HOSTS`: comma-separated list of hostnames for the MQTT broker\n* `CHIRPSTACK_GATEWAY_BRIDGE_HOSTS`: comma-separated list of hostnames for the ChirpStack Gateway Bridge (Basics Station backend)\n\nIn case the environment variable is not specified, then it will fallback to\n`127.0.0.1,localhost`.\n\n## Modifying hosts using Docker Compose\n\nUsing Docker Compose, you can use the following command:\n\n```\ndocker-compose run --rm \\\n    -e MQTT_BROKER_HOSTS=\"localhost,mqtt.example.com\" \\\n    -e CHIRPSTACK_GATEWAY_BRIDGE_HOSTS=\"localhost,cgwb.example.com\" \\\n    chirpstack-certificates make set-hosts\n```\n\n## Generating certificates\n\nSimply run `make` to generate all certificates. All certificates will be\nwritten to the `certs` folder. See also the `Makefile` for all commands\nbeing executed.\n\nYou probably want to make changes to the `certificate.json` files under\n`config`. Please see [https://cfssl.org](https://cfssl.org) for documentation\nabout the `cfssl` usage.\n\n## Generating certificates using Docker Compose\n\nAn alternate way to generate the certificates that does not require to have the\ndifferent dependencies installed is by using docker (you will need docker, of course).\n\n```\ndocker-compose run --rm chirpstack-certificates make\n```\n\n## Certificates\n\n### certs/ca\n\nThis directory contains the CA certificate and private key that you must configure\nin the `chirpstack.toml` configuration, such that it can generate\nclient-certificates for gateways and application integrations. \n\nThe CA certificate must also be configured in the MQTT broker and by the\nChirpStack Gateway Bridge Basics Station backend (if used) to validate the\nclient-certificate of connecting clients.\n\n### certs/chirpstack-gateway-bridge/basicstation\n\nThis directory contains the server-certificate and private key used by the\nChirpStack Gateway Bridge Basics Station backend (if used). \n\n### certs/mqtt-broker\n\nThis directory contains the server-certificate and private key used by the\nMQTT broker.\n\n## Configuration examples\n\nNote that the filenames in the example refer to the filenames as being used\nin the `certs/` directory (not including the names of the directories).\n\nThe examples assume that you will copy the generated certificates to the\nappropriate directories, and that you will set the correct file-permissions.\n\n### ChirpStack\n\nTo enable creating client-certificates for gateways through the web-interface,\nyou must configure the `[gateway]` section in the `chirpstack.toml`\nconfiguration:\n\n```toml\n[gateway]\nclient_cert_lifetime=\"12months\"\nca_cert=\"/etc/chirpstack/certs/ca.pem\"\nca_key=\"/etc/chirpstack/certs/ca-key.pem\"\n```\n\nTo enable creating client-certificates for (per application) MQTT integrations,\nyou must configure the `[integration.mqtt.client]` section in the\n`chirpstack.toml` configuration:\n\n```toml\n[integration.mqtt.client]\nclient_cert_lifetime=\"12months\"\nca_cert=\"/etc/chirpstack/certs/ca.pem\"\nca_key=\"/etc/chirpstack/certs/ca-key.pem\"\n```\n\n### ChirpStack Gateway Bridge\n\nTo enable TLS and validating gateway client-certificates of incoming\nBasics Station connections, you must configure the\n`[backend.basicstation]` section in the `chirpstack-gateway-bridge.toml`\nconfiguration:\n\n```toml\n[backend.basic_station]\ntls_cert=\"/etc/chirpstack-gateway-bridge/certs/basicstation.pem\"\ntls_key=\"/etc/chirpstack-gateway-bridge/certs/basicstation-key.pem\"\nca_cert=\"/etc/chirpstack-gateway-bridge/certs/ca.pem\"\n```\n\n### Mosquitto\n\nTo enable TLS and validating client-certificates of incoming MQTT connections\n(gateways and per-application MQTT integrations), you must configure a TLS\nlistener. Example:\n\n`/etc/mosquitto/acl`:\n\n```\npattern readwrite +/gateway/%u/#\npattern readwrite application/%u/#\n```\n\n`/etc/mosquitto/conf.d/listeners.conf`:\n\n```\nper_listener_settings true\n\nlistener 1883 127.0.0.1\nallow_anonymous true\n\nlistener 8883 0.0.0.0\ncafile /etc/mosquitto/certs/ca.pem\ncertfile /etc/mosquitto/certs/mqtt-broker.pem\nkeyfile /etc/mosquitto/certs/mqtt-broker-key.pem\nallow_anonymous false\nrequire_certificate true\nuse_identity_as_username true\nacl_file /etc/mosquitto/acl\n```\n\nFor more information, please refer to the [Mosquitto TLS configuration guide](https://www.chirpstack.io/docs/guides/mosquitto-tls-configuration.html).","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchirpstack%2Fchirpstack-certificates","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchirpstack%2Fchirpstack-certificates","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchirpstack%2Fchirpstack-certificates/lists"}