{"id":22954462,"url":"https://github.com/offdroid/swmn","last_synced_at":"2025-04-02T00:23:33.600Z","repository":{"id":191190047,"uuid":"397208216","full_name":"offdroid/swmn","owner":"offdroid","description":"Certificate management server with api and web UI","archived":false,"fork":false,"pushed_at":"2021-10-08T14:40:37.000Z","size":62,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-07T15:45:07.121Z","etag":null,"topics":["cert-manager","rocket-rs","rust"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/offdroid.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}},"created_at":"2021-08-17T10:23:16.000Z","updated_at":"2024-07-15T06:47:39.000Z","dependencies_parsed_at":"2023-08-28T17:38:05.894Z","dependency_job_id":"c606e65d-d2c3-4d68-9b62-3e959bbecce0","html_url":"https://github.com/offdroid/swmn","commit_stats":null,"previous_names":["offdroid/swmn"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/offdroid%2Fswmn","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/offdroid%2Fswmn/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/offdroid%2Fswmn/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/offdroid%2Fswmn/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/offdroid","download_url":"https://codeload.github.com/offdroid/swmn/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246731495,"owners_count":20824560,"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":["cert-manager","rocket-rs","rust"],"created_at":"2024-12-14T16:17:48.818Z","updated_at":"2025-04-02T00:23:33.575Z","avatar_url":"https://github.com/offdroid.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003e\u003ci\u003e\n    swmn\n\u003c/i\u003e\u003c/h1\u003e\n\nA basic but flexible certificate management solution intended for managing certificate based authentication from a webfrontend or REST api\n\u003cbr/\u003e\n\n\u003e :warning: If reliability or security is important, please don't use swmn — or at least consider its limitations carefully\u003csup\u003e[1](#security_note)\u003c/sup\u003e.\n\n# Configuration and setup\n\n## Requirements\n\n- `cargo`\n- Development libraries, among other:\n    - SQLite (`libsqlite3`)\n    - python3 (e.g. `python3-dev`)\n\n## Installation\n\nFor the api-only version, install directly using\n```bash\ncargo install --git https://github.com/offdroid/swmn.git\n```\nFor a version with the web interface, it is best to clone the repository as follows.\n```bash\ngit clone https://github.com/offdroid/swmn.git\ncd swmn\ncargo b --features web-interface\n```\n\n## Managing users\n\nShut the server down if it is running, then create the first user with\n```bash\nswmn user set \u003cusername\u003e\n```\nThis creates a new user or overrides the password of an existing one.\nOn the other hand, to delete users use\n```bash\nswmn user remove \u003cusername\u003e\n```\n\n\u003cdetails\u003e\n\u003csummary\u003e\nNote, that a removed but previously logged-in user will have access until the session cookie expires.\nAlternatively, logout all users by changing the `secret_key`.\n\u003c/summary\u003e\n\nFor instance by changing `secret_key` in `Rocket.toml` (and restarting swmn afterwards):\n```toml\n[production] # Or a different environment\nsecret_key = \"some_secure_key\"\n```\n\u003c/details\u003e\n\nPlease consult the CLI documentation with `swmn user --help` (or source code) for more details.\n\n## CA passphrase\n\nAny certificate authority (CA) should be secured with a passphrase.\nThis can be set globally: either as plaintext (not recommended), in the keyring or retrieved through a command at startup;\nIf neither option is set (or all fail) the passphrase has to be provided for each request, that requires it, such as certificate creation.\n\n- **plaintext** set `swmn.ca.passphrase` in `Rocket.toml`\n- **command** set `swmn.ca.passphrase_cmd` in `Rocket.toml`\n    - Use a utility such as [pass](https://www.passwordstore.org/)\n- **keyring** c.f. [Configuration section](#Configuration)\n\n## Managing certificate creation and revocation\n\nYou can now start smwn and log in, but not yet manage any certificates.\nTo be as flexible as possible this process is controlled through a Python script, c.f. [manage.py](./scripts/manage.py).\n\nIt must provide the following functions:\n\n```python\ndef make_cert(cn: str, passphrase: Optional[str], ca_passphrase: str, data):\n    pass\n\ndef revoke_cert(cn: str, ca_passphrase: str, data):\n    pass\n\ndef revoke_and_remove_cert(cn: str, ca_passphrase: str, already_revoked, data) -\u003e None:\n    pass\n\ndef list_certs(data) -\u003e List[str]:\n    pass\n\ndef get_config(cn: str, data) -\u003e str:\n    pass\n```\n\nThe implementation is left to the user by design and may use Python libraries (such as pyOpenSSL) or the command-line with `os.system()` for instance.\nIn case of failure, the script functions should throw an exception, which might be propagated the user.\n\nA non-default script location and module name can be defined in the `Rocket.toml` with the following keys:\n- `swmn.script.module`\n- `swmn.script.path`\n\n# Configuration\n\nLike any Rocket-based server swmn can be configured by a `Rocket.toml` in the working directory of swmn or at the path defined by `ROCKET_CONFIG`.\nC.f. [Rocket Configuration](https://rocket.rs/v0.5-rc/guide/configuration/#configuration) for more details.\n\nApart from basic settings like IP, port and secret-key this includes smwn specific details, such as the location of the `manage.py` script.\n\nOptionally, you can choose to store the CA passphrase in the keyring, which removes the need to explicitly specify it for creation and revokation operations. With the `secret-tool` utility run the following command:\n```bash\nsecret-tool store --label=\"swmn Certificate Authority (CA)\" application rust-keyring service swmn username \"Certificate Authority\"\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eSample configuration\u003c/summary\u003e\n\n```toml\n[default]\naddress = \"0.0.0.0\"\nport = 8000\n# Replace with a random value\nsecret_key = \"00000000000000000000000000000000000000000000\"\n\n[global.databases]\nswmn_db = { url = \"db.sqlite\" }\n\n[global.swmn]\nscript.module = \"manage\"\nscript.path = \"scripts/manage.py\"\nscript.ca.passphrase = \"Plaintext password\" # Not recommended\n# or\n# script.ca.passphrase_cmd = \"echo 'Do not use echo for this'\"\n```\n\u003c/details\u003e\n\n# API\n\nOne way of interacting with swmn is through the REST interface.\nSee the [rest-module](./src/rest) for more details.\n\n# CLI\n\nUser-accounts are managed through the CLI. Use `--help` for more details.\n\n\u003cdetails\u003e\n\u003csummary\u003eswmn user\u003c/summary\u003e\n\n```\nswmn-user\nAdministrative user management, exists after completion\n\nUSAGE:\n    swmn user \u003cSUBCOMMAND\u003e\n\nFLAGS:\n    -h, --help       Prints help information\n    -V, --version    Prints version information\n\nSUBCOMMANDS:\n    disable    Disable a user\n    enable     Enable a user\n    help       Prints this message or the help of the given subcommand(s)\n    list       List all users\n    remove     Remove an existing user; This does not revoke existing session cookies!\n    set        Set an user's password or create a new one\n```\n\u003c/details\u003e\n\n# TLS\n\nTo ensure a secure connection, use of TLS is highly recommended.\nThe TLS support of Rocket, which swmn is built on, is not considered production ready.\nCompile with the `tls` feature and see [Rocket: Configuring TLS](https://rocket.rs/v0.5-rc/guide/configuration/#tls).\nAlternatively and the probably better option would be to use a reverse proxy, such as [NGINX](https://www.nginx.com/) to add TLS.\n\nTo enable secure cookies (recommended if using TLS) set the environment variable `SECURE_COOKIES` to `true`.\n\n# Customizing the interface\n\nThe html web interface is very basic and works without JS — by design.\nIt can easily be replaced or extended through modification of the handlebars templates in [templates](./templates).\n\nMore ambitious extensions should replace the [`web`](./web/)-crate and/or make use of the REST-apis on the client-side.\n\n`web-interface` and `no-rest-api` are crate features to include or exclude the web interface or REST api.\n\n# Tests\n\nThe CLI tests require a swmn executable and are not run by default but can be with the following command\n```bash\n# Build beforehand, e.g.\n# cargo build\ncargo test -- --ignored\n# or to run all test\ncargo test -- --include-ignored\n```\nThis means that you need to build the regular swmn and test binary to test any changes!\n\nTo also test all local dependencies use\n```bash\ncargo test -p api -p cert -p common -p database -p web -p swmn -- --include-ignored\n```\n\n# License\n\nLicensed under MIT, see [LICENSE](./LICENSE).\n\n---\n\n\u003ca name=\"security_note\"\u003e1\u003c/a\u003e: Especially, handling of the CA passphrase might not be sufficiently secure for real-world environments\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foffdroid%2Fswmn","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foffdroid%2Fswmn","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foffdroid%2Fswmn/lists"}