{"id":17250288,"url":"https://github.com/sorah/acmesmith","last_synced_at":"2025-05-15T23:02:58.859Z","repository":{"id":3752106,"uuid":"50779521","full_name":"sorah/acmesmith","owner":"sorah","description":"An effective ACME v2 client: Manage keys on the cloud (e.g. S3)","archived":false,"fork":false,"pushed_at":"2025-04-28T00:45:02.000Z","size":301,"stargazers_count":119,"open_issues_count":0,"forks_count":25,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-05-15T23:01:58.199Z","etag":null,"topics":["acme","acme-protocol","cloud","letsencrypt"],"latest_commit_sha":null,"homepage":"","language":"Ruby","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/sorah.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.txt","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,"zenodo":null},"funding":{"ko_fi":"sorah","github":["sorah"]}},"created_at":"2016-01-31T14:57:16.000Z","updated_at":"2025-04-28T00:42:57.000Z","dependencies_parsed_at":"2023-12-26T08:45:56.107Z","dependency_job_id":"8ec07a72-ea67-4a81-99a4-744de3953f00","html_url":"https://github.com/sorah/acmesmith","commit_stats":{"total_commits":164,"total_committers":10,"mean_commits":16.4,"dds":"0.25609756097560976","last_synced_commit":"f461e2faccb532ea6d6b163cecf2cc6094c4a8bf"},"previous_names":[],"tags_count":30,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sorah%2Facmesmith","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sorah%2Facmesmith/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sorah%2Facmesmith/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sorah%2Facmesmith/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sorah","download_url":"https://codeload.github.com/sorah/acmesmith/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254436943,"owners_count":22070946,"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","acme-protocol","cloud","letsencrypt"],"created_at":"2024-10-15T06:46:46.695Z","updated_at":"2025-05-15T23:02:58.847Z","avatar_url":"https://github.com/sorah.png","language":"Ruby","funding_links":["https://ko-fi.com/sorah","https://github.com/sponsors/sorah","https://ko-fi.com/J3J8CKMUU'"],"categories":[],"sub_categories":[],"readme":"# Acmesmith: A simple, effective ACME v2 client to use with many servers and a cloud\n\n![ci](https://github.com/sorah/acmesmith/workflows/ci/badge.svg?event=push)  \u003ca href='https://ko-fi.com/J3J8CKMUU' target='_blank'\u003e\u003cimg height='36' style='border:0px;height:36px;' src='https://cdn.ko-fi.com/cdn/kofi3.png?v=3' border='0' alt='Buy Me a Coffee at ko-fi.com' /\u003e\u003c/a\u003e\n\n\nAcmesmith is an [ACME (Automatic Certificate Management Environment)](https://github.com/ietf-wg-acme/acme) client that works perfect on environment with multiple servers. This client saves certificate and keys on cloud services (e.g. AWS S3) securely, then allow to deploy issued certificates onto your servers smoothly. This works well on [Let's encrypt](https://letsencrypt.org).\n\nThis tool is written in Ruby, but Acmesmith saves certificates in simple scheme, so you can fetch certificate by your own simple scripts.\n\n## Features\n\n- ACME v2 client designed to work on multiple servers\n- ACME registration, domain authorization, certificate requests \n  - Tested against [Let's encrypt](https://letsencrypt.org)\n- Storing keys in several ways\n- Challenge response\n- Many cloud services support\n  - AWS S3 storage and Route 53 `dns-01` responder support out-of-the-box\n  - 3rd party plugins available for OpenStack designate, Google Cloud DNS, simple http-01, and Google Cloud Storage. See [Plugins](#3rd-party-plugins) below\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'acmesmith'\n```\n\nAnd then execute:\n\n    $ bundle\n\nOr install it yourself as:\n\n    $ gem install acmesmith\n\n### Docker\n\n```\ndocker run -v /path/to/acmesmith.yml:/app/acmesmith.yml:ro sorah/acmesmith:latest\n```\n\n[`Dockerfile`](./Dockerfile) is available. Default confguration file is at `/app/acmesmith.yml`.\n\nPre-built docker images are provided at https://hub.docker.com/r/sorah/acmesmith for your convenience\nBuilt with GitHub Actions \u0026 [sorah-rbpkg/dockerfiles](https://github.com/sorah-rbpkg/dockerfiles).\n\n## Usage\n\n```\n$ acmesmith new-account CONTACT              # Create account key (contact e.g. mailto:xxx@example.org)\n```\n\n```\n$ acmesmith order COMMON_NAME [SAN]     # request certificate for CN +COMMON_NAME+ with SANs +SAN+\n$ acmesmith add-san COMMON_NAME [SAN]     # re-request existing certificate of CN with additional SAN(s)\n```\n\n```\n$ acmesmith list [COMMON_NAME]                          # list certificates or its versions\n$ acmesmith current COMMON_NAME                         # show current version for certificate\n$ acmesmith show-certificate COMMON_NAME                # show certificate\n$ acmesmith show-private-key COMMON_NAME                # show private key\n$ acmesmith save-certificate COMMON_NAME --output=PATH  # Save certificate to a file\n$ acmesmith save-private-key COMMON_NAME --output=PATH  # Save private key to a file\n$ acmesmith save-pkcs12      COMMON_NAME --output=PATH  # Save certificate and private key to a PKCS12 file\n```\n\n```\n$ acmesmith autorenew [-r RATIO] [-d DAYS] # Renew certificates which being expired soon. Default to -r 1/3\n```\n\n```\n# Save (or update) certificate files and key in a one command\n$ acmesmith save COMMON_NAME \\\n      --version-file=/tmp/cert.txt   # Path to save a certificate version for following run \n      --key-file=/tmp/cert.key       # Path to save a key\n      --fullchain-file=/tmp/cert.pem # Path to save a certficiate and its chain (concatenated)\n```\n\nSee `acmesmith help [subcommand]` for more help.\n\n## Configuration\n\nSee [config.sample.yml](./config.sample.yml) to start. Default configuration file is `./acmesmith.yml`.\n\n``` yaml\ndirectory: https://acme-v02.api.letsencrypt.org/directory # production\n\nstorage:\n  # configure where to store keys and certificates; described later\n  type: s3\n  region: 'us-east-1'\n  bucket: 'my-acmesmith-bucket'\n  prefix: 'prod/'\n\nchallenge_responders:\n  # configure how to respond ACME challenges; described later\n  - route53: {}\n```\n\n### Storage\n\nStorage provider stores issued certificates, private keys and ACME account keys.\n\n- Amazon S3: [s3](./docs/storages/s3.md)\n- Filesystem: [filesystem](./docs/storages/filesystem.md)\n- Google Cloud Storage: [minimum2scp/acmesmith-google-cloud-storage](https://github.com/minimum2scp/acmesmith-google-cloud-storage) _(plugin)_\n\n### Challenge Responders\n\nChallenge responders responds to ACME challenges to prove domain ownership to CA.\n\n- API driven\n  - AWS Route 53: [route53](./docs/challenge_responders/route53.md) (`dns-01`)\n  - Google Cloud DNS: [nagachika/acmesmith-google-cloud-dns](https://github.com/nagachika/acmesmith-google-cloud-dns) (`dns-01`, _plugin_ )\n  - OpenStack Designate v1: [hanazuki/acmesmith-designate](https://github.com/hanazuki/acmesmith-designate) (`dns-01`, _plugin_ )\n  - Verisign MDNS REST API: [benkap/acmesmith-verisign](https://github.com/benkap/acmesmith-verisign) (`dns-01`, _plugin_ )\n- Generic\n  - Static HTTP: [mipmip/acmesmith-http-path](https://github.com/mipmip/acmesmith-http-path) (`http-01`, _plugin_ )\n\n#### Common options\n\n```yaml\nchallenge_responders:\n  ## Multiple responders are accepted.\n  ## The first responder that supports a challenge and applicable for given domain name will be used.\n  - {RESPONDER_TYPE}:\n      {RESPONDER_OPTIONS}\n\n    ### Filter (optional)\n    filter:\n      subject_name_exact:\n        - my-app.example.com\n      subject_name_suffix:\n        - .example.org\n      subject_name_regexp:\n        - '\\Aapp\\d+.example.org\\z'\n\n  - {RESPONDER_TYPE}:\n      {RESPONDER_OPTIONS}\n    ...\n```\n\n### Post Issuing Hooks\n\nPost issuing hooks are configurable actions that are executed\nwhen a new certificate has been succesfully issued. The hooks are\nsequentially executed in the same order as they are configured, and they\nare configurable per certificate's common-name.\n\n- Shell script: [shell](./docs/post_issuing_hooks/shell.md)\n- Amazon Certificate Manager (ACM): [acm](./docs/post_issuing_hooks/acm.md)\n\n### Chain preference\n\nIf you want to prefer an alternative chain given by CA ([RFC8555 Section 7.4.2.](https://datatracker.ietf.org/doc/html/rfc8555#section-7.4.2)), use the following configuration. Preference may be delcared with common name.\n\nWhen chain preferences are configured for the common name of an ordered certificate, Acmesmith will retrieve all available alternative chains and evaluate rules in an configured order. The first chain matched to a rule will be used and saved to a storage.\n\nDuring rule evaluation, a root issuer name and key id are taken from the last available intermediate (Issuer and AKI) provided in a chain, when a chain doesn't have a root certificate (trust anchor).\n\n```yaml\nchain_preferences:\n  - root_issuer_name: \"ISRG Root X1\"\n    ### Optionally, you may specify CA SKI/AKI:\n    # root_issuer_key_id: \"79:b4:59:e6:7b:b6:e5:e4:01:73:80:08:88:c8:1a:58:f6:e9:9b:6e\"\n\n    ### Filter by common name (optional)\n    filter:\n      exact:\n        - my-app.example.com\n      suffix:\n        - .example.org\n      regexp:\n        - '\\Aapp\\d+.example.org\\z'\n```\n\n## Vendor dependent notes\n\n- [./docs/vendor/aws.md](./docs/vendor/aws.md): IAM and KMS key policies, and some tips\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at https://github.com/sorah/acmesmith.\n\n### Running tests\n\nunit test:\n\n```\nbundle exec rspec\n```\n\nintegration test using [letsencrypt/pebble](https://github.com/letsencrypt/pebble). needs Docker:\n\n```\nACMESMITH_CI_START_PEBBLE=1 CI=1 bundle exec -t integration_pebble\n```\n\n## Writing plugins\n\nPublish as a gem (RubyGems). Files will be loaded automatically from `lib/acmesmith/{plugin_type}/{name}.rb`.\n\ne.g.\n\n- storage: `lib/acmesmith/storages/perfect_storage.rb` \u0026 `Acmesmith::Storages::PerfectStorage`\n- challenge_responder: `lib/acmesmith/challenge_responders/perfect_authority.rb` \u0026 `Acmesmith::Storages::PerfectAuthority`\n- post_issuing_hook: `lib/acmesmith/challenge_responders/nice_deploy.rb` \u0026 `Acmesmith::Storages::NiceDeploy`\n\n## Development\n\nAfter checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.\n\nTo install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).\n\n\n\n## License\n\nThe gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsorah%2Facmesmith","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsorah%2Facmesmith","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsorah%2Facmesmith/lists"}