{"id":16928817,"url":"https://github.com/hslatman/mud-file-server","last_synced_at":"2025-04-11T17:50:57.630Z","repository":{"id":57544317,"uuid":"285804965","full_name":"hslatman/mud-file-server","owner":"hslatman","description":"A MUD File Server for serving Manufacturer Usage Descriptions (RFC 8520) using the Caddy web server","archived":false,"fork":false,"pushed_at":"2023-10-24T22:47:54.000Z","size":15550,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-25T13:46:16.569Z","etag":null,"topics":["caddy","golang","iot","iot-access-control","mud","mud-file-server","mud-files","rfc-8520"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hslatman.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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,"publiccode":null,"codemeta":null}},"created_at":"2020-08-07T10:43:38.000Z","updated_at":"2024-02-29T13:03:49.000Z","dependencies_parsed_at":"2024-06-20T11:55:48.195Z","dependency_job_id":"0e7a4bc5-e6fd-4191-b243-c01d60ae8dca","html_url":"https://github.com/hslatman/mud-file-server","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hslatman%2Fmud-file-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hslatman%2Fmud-file-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hslatman%2Fmud-file-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hslatman%2Fmud-file-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hslatman","download_url":"https://codeload.github.com/hslatman/mud-file-server/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248455317,"owners_count":21106592,"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":["caddy","golang","iot","iot-access-control","mud","mud-file-server","mud-files","rfc-8520"],"created_at":"2024-10-13T20:37:43.816Z","updated_at":"2025-04-11T17:50:57.608Z","avatar_url":"https://github.com/hslatman.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MUD File Server\n\nA MUD File Server using [Caddy](https://caddyserver.com/) as the web server.\n\n## Description\n\n[Manufacturer Usage Descriptions](https://tools.ietf.org/html/rfc8520) (MUDs) allow manufacturers of IoT equipment to specify the intended network communication patterns of the devices they manufacture. \nThe access control policies described in a MUD File allow network controllers to automatically enforce rules on the device, resulting in devices only being allowed to communicate within the boundaries of the access control policies.\nMUD Files typically don't reside on the (local) network itself, which is why MUD Controllers need a way to retrieve MUD Files as soon as they find out that a MUD File exists for a device.\nMUD File Servers are responsible for serving MUD Files and their signatures, which can be retrieved by MUD Controllers when an IoT device emits a MUD URL.\n\nMUR URLs have the following basic properties:\n\n* They always use the \"https\" scheme\n* Any \"https://\" URL can be a MUD URL\n\nThis repository contains an implementation of a MUD File Server based on the [Caddy](https://caddyserver.com/) web server.\nIt is implemented as a Caddy module and can thus be embedded in a Caddy deployment like any other module.\nThe module is available to be imported as follows:\n\n```go\nimport (\n    _ \"github.com/hslatman/mud-file-server/pkg/mud\".\n)\n```\n\nThe repository also contains an example command for running a Caddy server with the MUD File Server enabled.\nThis can be found in the `cmd` directory.\n\n## Build\n\nThe MUD File Server binary can be built as shown below:\n\n```bash\n# build the server \n$ go build cmd/main.go -o muds\n```\n\n## Usage\n\n```bash\n# run the server directly from Go code, using the provided config.json \n$ go run cmd/main.go run --config config.json\n# run the server from compiled binary, using the provided config.json \n$ ./muds run --config config.json\n```\n\nNow the MUD File Server can be reached at https://localhost:9443/.\nAssuming the examples directory is available and the repository directory set as the root to serve files from, the example MUD file for `The BMS Example Light Bulb` can now be retrieved from:\n\nhttps://localhost:9443/examples/lightbulb2000.json\n\nAnd its signature can be retrieved from:\n\nhttps://localhost:9443/examples/lightbulb2000.json.p7s\n\nFiles that are invalid MUD Files or not parseable as CMS objects are not served by default.\n\nPlease note that the lightbulb2000.json file has been changed slightly to reflect the fact that it has a MUD signature available for demo purposes.\n\n### Configuration\n\nThe MUD File Server module can be configured like any other Caddy module.\nWe've provided a sample config.json file, which sets the root of the MUD File Server to be the current directory and disables request header validation (for demo purposes only).\nThe following options are available:\n\n* `root`: string that indicates the root directory to serve MUD Files and signatures from. Defaults to the Caddy `{http.vars.root}` parameter if set, but current working directory otherwise.\n* `validate_headers`: boolean that indicates requests headers should be validated or not. Disabling this is easier for demos in a web browser, but should not be done for an actual server. Defaults to true.\n* `validate_mud`: boolean that indicates the contents of a MUD file should be validated or not. Validation is performed using https://github.com/hslatman/mud.yang.go/. The signature is NOT validated. Defaults to true.\n* `set_etag`: boolean that indicates whether or not to set the ETag header in responses. Defaults to true.\n\n## Signing \u0026 Verifying MUD Files\n\nAccording to RFC 8520, MUD files MUST be signed using Cryptographic Message Contents (CMS).\nWithin the MUD file itself, the `mud-signature` property points to the location where the (detached) signature can be found.\nThe `mud-signature` property can be used by a MUD Manager to retrieve the signature file.\nBy default, the assumption is that the location of the signature file is right next to the MUD file itself, but it can be somewhere different.\nA small caveat is that the location of the signature file should be set before signing the MUD file, because it's in the contents of the MUD file to be signed.\n\nSigning a MUD file is described in the [RFC](https://tools.ietf.org/html/rfc8520#section-13).\nAn example command invocation looks like this:\n\n```bash\n# within the mud-file-server repository, assuming example certificates and keys are available\n$ openssl cms -sign -signer cert/server.crt -inkey cert/server.key -in examples/lightbulb2000.json -binary -outform DER -binary -certfile cert/intermediate.crt -out examples/lightbulb2000.json.p7s\n```\n\nSignatures can be checked as follows:\n\n```bash\n# within the mud-file-server repository, assuming the certificate that was used for signing the file is trusted\n$ openssl cms -verify -in examples/lightbulb2000.json.p7s -inform DER -content examples/lightbulb2000.json\n```\n\n### Example Certificates\n\nA small utility script for generating the keys and certificates for signing a MUD File has been included in this repository.\nIt serves as an example; it probably shouldn't be used as is for production deployments.\nIt can be used as follows:\n\n```bash\n# within the cert directory:\n$ ./new.sh\n```\n\nThe certificate and key generated are directly under the newly generated CA, so no intermediates are included.\nThe command for signing a MUD File using a key and certificate generated with the utility script should thus be changed to not include the intermediate certificate like below:\n\n```bash\n# within the mud-file-server repository, assuming example certificates and keys are available\n$ openssl cms -sign -signer cert/server.crt -inkey cert/server.key -in examples/lightbulb2000.json -binary -outform DER -binary -out examples/lightbulb2000.json.p7s\n```\n\n## Goal\n\nThe main goal of this repository is to provide a reference MUD File Server implementation that is compliant with RFC 8520.\nBy choosing Caddy as the server, which has been steadily growing in popularity because of its ease of deployment and automatic TLS configuration, it might become easier for companies to deploy a MUD File Server.\n\nCaddy was on my list of things to learn about and work with, so this little project allowed me to do just that.\n\n## TODO\n\n* Add logging using Caddy provided logger?\n* Do we need some kind of abstract file system handling?\n* Implement a simple overview page of MUDs available?\n* Implement a MUD viewer to visualize available MUDs?\n* Implement basic statistics about files requested?\n* More robust content type checking?\n* Add commands for signing / verifying MUD signatures? Or should that be part of mud.yang.go?\n* Add signature verification before serving the MUD file (if signature exists; on same server, or a different one)?\n* Add non-Caddy implementation to be embedded in any Go project?","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhslatman%2Fmud-file-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhslatman%2Fmud-file-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhslatman%2Fmud-file-server/lists"}