{"id":19388331,"url":"https://github.com/mk-fg/acme-cert-tool","last_synced_at":"2025-04-23T23:31:37.069Z","repository":{"id":144995485,"uuid":"80823316","full_name":"mk-fg/acme-cert-tool","owner":"mk-fg","description":"Simple one-stop tool to manage X.509/TLS certs and all the ACME CA authorization stuff","archived":false,"fork":false,"pushed_at":"2025-02-13T05:56:25.000Z","size":166,"stargazers_count":19,"open_issues_count":0,"forks_count":10,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-04-02T22:23:21.475Z","etag":null,"topics":["acme-client","certificates","cryptography","letsencrypt","python","security","sysadmin","tls","tool","web-pki","x509"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"wtfpl","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mk-fg.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"COPYING","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":"2017-02-03T11:28:51.000Z","updated_at":"2025-02-13T05:56:28.000Z","dependencies_parsed_at":"2024-04-14T06:25:41.481Z","dependency_job_id":"06f9cf92-bfde-4ce8-9233-c980f9b0cabc","html_url":"https://github.com/mk-fg/acme-cert-tool","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/mk-fg%2Facme-cert-tool","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mk-fg%2Facme-cert-tool/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mk-fg%2Facme-cert-tool/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mk-fg%2Facme-cert-tool/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mk-fg","download_url":"https://codeload.github.com/mk-fg/acme-cert-tool/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250532054,"owners_count":21446107,"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":["acme-client","certificates","cryptography","letsencrypt","python","security","sysadmin","tls","tool","web-pki","x509"],"created_at":"2024-11-10T10:12:28.352Z","updated_at":"2025-04-23T23:31:37.054Z","avatar_url":"https://github.com/mk-fg.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"acme-cert-tool\n==============\n\nSimple one-stop tool to manage X.509/TLS certs and all the ACME CA\nauthorization stuff with minimum dependencies.\n\nShould work in unix-like environments like Linux/\\*BSD/OSX and WSL2.\n\nContents:\n\n- [Main features](#hdr-main_features)\n- [Usage example](#hdr-usage_example)\n- [Installation](#hdr-installation)\n- [ACME-related bugs, issues, vulnerabilities](#hdr-acme-related_bugs_issues_vulnerabilities)\n- [Links](#hdr-links)\n\nThis repository URLs:\n\n- https://github.com/mk-fg/acme-cert-tool\n- https://codeberg.org/mk-fg/acme-cert-tool\n- https://fraggod.net/code/git/acme-cert-tool\n\n\n\u003ca name=hdr-main_features\u003e\u003c/a\u003e\n## Main features\n\n- P-384 (secp384r1) ECC keys and certs are supported and the default,\n  with RSA also supported as a fallback option where still necessary\n  (e.g. certs for old clients that can't do ECC).\n\n- Can issue multiple certificates for diff key types in one command.\n\n- Single python3 script implementation,\n  only dependent on [cryptography.io](https://cryptography.io/) module.\n\n- Does not use openssl command-line tools nor ever requires user to run them.\n\n- Designed with automated non-interactive \"setup cert, auto-renewal and forget\"\n  operation in mind, all with a single command, if possible.\n\n- Does not do anything with httpd or any other daemons and their configuration.\n\n- Uses \"ACME v2\" protocol supported by Let's Encrypt since after April 2018,\n  with \"http-01\" validation only (token at \\/.well-known\\/acme-challenge\\/ URL over HTTP).\n\nCan generate/use/roll-over account keys (ec-384/rsa-2048/rsa-4096,\npem pkcs8 or openssl/pkcs1), register/query/deactivate accounts,\ngenerate configurable X.509 CSRs (ec-384/rsa-2048/rsa-4096 keys, pem\nopenssl/pkcs1 for certs and keys), sign these through ACME CA.\n\nHook scripts can be used at multiple points to integrate script into whatever\nsetup (e.g. sync challenge files, reload httpd, process keys, introduce delays, etc),\nsee `./acme-cert-tool.py --hook-list` for more info on these.\n\n\n\u003ca name=hdr-usage_example\u003e\u003c/a\u003e\n## Usage example\n\n```\n% ./acme-cert-tool.py --debug -gk le-staging.acc cert-issue \\\n   le-staging.cert.pem /srv/www/.well-known/acme-challenge mydomain.com\n```\n\n(``/srv/www/`` dir is assumed to be exposed on http://mydomain.com here)\n\nEC P-384 (default) account key (along with some metadata, as comments) will be\nstored in \"le-staging.acc\" file (note: account key has nothing to do with\ncertificate), certificate (chain) and its key (also P-384 by default) in\n\"le-staging.cert.pem\" file. \"http-01\" validation type is used.\n\nCan be re-run to generate new certificate there (i.e. renew) with same account key\nand domain authorization (`-g/--gen-key-if-missing` does not regen key files).\n\nTo use non-staging server with \"legit\" intermediate\n(be sure to check ToS and limits first!), simply add `-s le` there.\n\nWhen configuring web server after that, it should use resulting \\*.pem\nas both certificate chain and key (see also `-s/--split-key-file` option).\n\nRun `./acme-cert-tool.py -h` to get more information on all supported commands\nand options, and e.g. `./acme-cert-tool.py cert-issue -h` to see info and options\nfor a specific command.\n\n\n\u003ca name=hdr-installation\u003e\u003c/a\u003e\n## Installation\n\nThis is a python (3.8+) script, using [cryptography] module.\nIt's not in a [PyPI] registry.\n\n[pipx] can be used to run the tool via \"pipx run\", auto-installing \"cryptography\" to an ad-hoc venv:\n\n```\n% curl -OL https://raw.githubusercontent.com/mk-fg/acme-cert-tool/master/acme-cert-tool.py\n% pipx run acme-cert-tool.py --help\n```\n\nAlternatively, OS/distro package manager can be used to install necessary dependencies:\n\n```\narchlinux# pacman -S python python-cryptography\ndebian/ubuntu# apt-get install --no-install-recommends python3-minimal python3-cryptography\n```\n\nThen just download (or git-clone) and run the script:\n\n```\n% curl -OL https://raw.githubusercontent.com/mk-fg/acme-cert-tool/master/acme-cert-tool.py\n% chmod +x acme-cert-tool.py\n% ./acme-cert-tool.py --help\n```\n\nUnless any errors pop-up immediately, everything is installed correctly and ready to use.\n\nThere is no need to run this script as root, use its ``-m/--mode``, ``--challenge-file-mode``\noptions and/or ACLs (``setfacl -m d:...``) to share files between different uids/gids easily.\n\n[cryptography]: https://cryptography.io/\n[PyPI]: https://pypi.org/\n[pipx]: https://pypa.github.io/pipx/\n\n\n\u003ca name=hdr-acme-related_bugs_issues_vulnerabilities\u003e\u003c/a\u003e\n## ACME-related bugs, issues, vulnerabilities\n\nOnes that I'm aware of wrt either ACME protocol or this specific implementation\nare listed here, let me know if there are any other relevant problems.\n\n- [Critical vulnerability in JSON Web Encryption (2017-03-13)]\n\n  An Invalid Curve Attack on JWE ECDH-ES key agreement.\\\n  Does not affect ACME protocol, as ECDH-ES is not used there at all.\n\n- [Chaining Remote Web Vulnerabilities to Abuse Let's Encrypt (2017-08-29)]\n\n  Not strictly a protocol vulnerability, but more of a note on how leaving\n  something like poor path permissions or insecure site uploads which can drop\n  files to e.g. /var/www/htdocs/.well-known/acme-challenge can lead to someone\n  else issuing valid certs for the site for phishing purposes or such - beware.\n\n- [ACME TLS-SNI-01 validation vulnerability (2018-01-12)]\n\n  Does not affect this app, as it only uses http-01 validation.\\\n  TLS-SNI-01 itself was immediately disabled due to vulnerability to such attacks.\n\n- [CAA Rechecking Incident (2020-02-29)]\n\n  Server-side issue with Let's Encrypt. Revocation of ~3mil certs was planned,\n  but was cancelled when it became apparent that they won't get updated in time.\n\n  Shows that you probably should use `-e/--contact-email` option if possible,\n  though then again, they didn't go through with the revocation, so maybe not.\n\n\n- [Let's Encrypt Chain of Trust change (2024-09-30, announced 2023-07-10)]\n\n  Final change from IdenTrust root CA to its own ISRG root CA, which can affect\n  devices that weren't updated to include new root cert or ones with an otherwise\n  fixed/limited CA list.\n\n  LE is expected to start returning smaller cert-chain for new certs requested\n  from 2024-06-06 onwards, with no changes or updates to this script or its usage.\n\n[Critical vulnerability in JSON Web Encryption (2017-03-13)]:\n  http://blog.intothesymmetry.com/2017/03/critical-vulnerability-in-json-web.html\n[Chaining Remote Web Vulnerabilities to Abuse Let's Encrypt (2017-08-29)]:\n  https://www.mike-gualtieri.com/posts/chaining-remote-web-vulnerabilities-to-abuse-lets-encrypt\n[ACME TLS-SNI-01 validation vulnerability (2018-01-12)]:\n  https://labs.detectify.com/2018/01/12/how-i-exploited-acme-tls-sni-01-issuing-lets-encrypt-ssl-certs-for-any-domain-using-shared-hosting/\n[CAA Rechecking Incident (2020-02-29)]: https://letsencrypt.org/caaproblem/\n[Let's Encrypt Chain of Trust change (2024-09-30, announced 2023-07-10)]:\n  https://letsencrypt.org/2023/07/10/cross-sign-expiration.html\n\n\n\u003ca name=hdr-links\u003e\u003c/a\u003e\n## Links\n\n- ACME certificate providers\n\n  - [Let's Encrypt](https://letsencrypt.org/)\n\n    Original public Certificate Authority, issuing certificates for websites via\n    ACME protocol to anyone at no cost.\n\n    Supports IETF v2 version of ACME protocol, as described in\n    [RFC 8555](https://tools.ietf.org/html/rfc8555).\n\n  - [ZeroSSL](https://zerossl.com/) - another cert provider.\n\n  - [Buypass Go SSL](https://www.buypass.com/ssl/products/acme)\n\n  - [SSL.com](https://www.ssl.com/) - seem to provide ACME certs\n    [after free registration](https://scotthelme.co.uk/heres-another-free-ca-as-an-alternative-to-lets-encrypt/).\n\n  I've only used LE myself, so no idea if others are any good, though note that\n  since all private keys are always client-side only, practical differences between\n  them should be cert expiration time (i.e. how often this script needs to run), Terms of Service,\n  [Certificate Transparency logs](https://en.wikipedia.org/wiki/Certificate_Transparency)\n  (see [crt.sh](https://crt.sh) and such), ACME API reliability (uptime, bugs, etc), and how long -\n  if any - is their intermediate certificate chain (affecting size of cert bundle served to clients).\n\n- [RFC 8555 describing ACME protocol](https://tools.ietf.org/html/rfc8555)\n\n- [Let's Encrypt \"Chain of Trust\" page](https://letsencrypt.org/certificates/)\n\n  Links to LE root and intermediate certificates, which should be supplied in\n  resulting PEM files already, and usually shipped in browsers too.\n\n- [ACME client list](https://letsencrypt.org/docs/client-options/)\n\n  List of clients compatible with Let's Encrypt and similar ACME CA services.\n\n- [certbot](https://github.com/certbot/certbot/)\n\n  Official Let's Encrypt client, has a lot of options and plugins to e.g. mess\n  with httpd configuration files, fairly heavyweight.\n\n- [acme-tiny](https://github.com/diafygi/acme-tiny)\n\n  200-line Python (2/3) ACME client, main source of inspiration behind this one.\n\n  Fairly bare-bones, have to be supplemented with openssl cli stuff to generate\n  CSRs, relies on parsing openssl cli output, lacks (as of 2017-02-05) elliptic\n  curve key support, etc.\n\n- [easy-rsa](https://github.com/OpenVPN/easy-rsa/)\n\n  Good set of scripts to easily setup and maintain local X.509 PKI (e.g. that\n  has nothing to do with global TLS trust roots) - i.e. create CA, intermediates,\n  client/server certs - all with one or two trivial commands, very configurable.\n\n- Web TLS setup \"Best Practices\" checklists (updated every few months):\n\n  - [Qualys SSL Labs](https://github.com/ssllabs/research/wiki/SSL-and-TLS-Deployment-Best-Practices)\n  - [Mozilla](https://wiki.mozilla.org/Security/Server_Side_TLS)\n\n- EdDSA (ed25519) support info:\n\n  - [Not supported for ACME account keys yet]\n\n  - Not supported and/or standardized properly in browsers yet\n\n    - [community.letsencrypt.org thread #69868]\n\n    - [github letsencrypt/boulder issue #3649]\n\nLast updated on 2021-08-20, please open an issue if you notice any outdated info/links.\n\n[Not supported for ACME account keys yet]:\n  https://github.com/letsencrypt/boulder/issues/4213\n[community.letsencrypt.org thread #69868]:\n  https://community.letsencrypt.org/t/support-ed25519-and-ed448/69868\n[github letsencrypt/boulder issue #3649]:\n  https://github.com/letsencrypt/boulder/issues/3649\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmk-fg%2Facme-cert-tool","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmk-fg%2Facme-cert-tool","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmk-fg%2Facme-cert-tool/lists"}