百科.dev
全部条目在线工具AI 编程趋势榜开源项目技术资讯提交条目
登录
< 返回工具列表
A

acme-client

> 编程语言
开源

一个用于 letsencrypt ACME 协议的 Ruby 客户端。

505 stars0 点赞2 次浏览
访问官网GitHub

工具介绍

一个用于 letsencrypt ACME 协议的 Ruby 客户端。

Acme::Client

acme-client is a client implementation of the ACME / RFC 8555 protocol in Ruby.

You can find the ACME reference implementations of the server in Go and the client in Python.

ACME is part of the Letsencrypt project, which goal is to provide free SSL/TLS certificates with automation of the acquiring and renewal process.

Installation

Via RubyGems:

$ gem install acme-client

Or add it to a Gemfile:

ruby
gem 'acme-client'

Usage

  • Acme::Client
    • Installation
    • Usage
    • Setting up a client
    • Account management
    • Obtaining a certificate
      • Ordering a certificate
      • Preparing for HTTP challenge
      • Preparing for DNS challenge
      • Requesting a challenge verification
      • Downloading a certificate
      • Ordering an alternative certificate
    • Extra
      • Certificate revokation
      • Certificate renewal
    • Not implemented
    • Requirements
    • Development
    • Pull request?
    • License

Setting up a client

The client is initialized with a private key and the directory of your ACME provider.

LetsEncrypt's directory is https://acme-v02.api.letsencrypt.org/directory.

They also have a staging endpoint at https://acme-staging-v02.api.letsencrypt.org/directory.

acme-ruby expects OpenSSL::PKey::RSA or OpenSSL::PKey::EC

You can generate one in Ruby using OpenSSL.

ruby
require 'openssl'
private_key = OpenSSL::PKey::RSA.new(4096)

Or load one from a PEM file

ruby
require 'openssl'
OpenSSL::PKey::RSA.new(File.read('/path/to/private_key.pem'))

See RSA and EC for documentation.

ruby
client = Acme::Client.new(private_key: private_key, directory: 'https://acme-staging-v02.api.letsencrypt.org/directory')

If your account is already registered, you can save some API calls by passing your key ID directly. This will avoid an unnecessary API call to retrieve it from your private key.

ruby
client = Acme::Client.new(private_key: private_key, directory: 'https://acme-staging-v02.api.letsencrypt.org/directory', kid: 'https://example.com/acme/acct/1')

Account management

Accounts are tied to a private key. Before being allowed to create orders, the account must be registered and the ToS accepted using the private key. The account will be assigned a key ID.

ruby
client = Acme::Client.new(private_key: private_key, directory: 'https://acme-staging-v02.api.letsencrypt.org/directory')
account = client.new_account(contact: 'mailto:[email protected]', terms_of_service_agreed: true)

After the registration you can retrieve the account key indentifier (kid).

ruby
client = Acme::Client.new(private_key: private_key, directory: 'https://acme-staging-v02.api.letsencrypt.org/directory')
account = client.new_account(contact: 'mailto:[email protected]', terms_of_service_agreed: true)
account.kid # => 

If you already have an existing account (for example one created in ACME v1) please note that unless the kid is provided at initialization, the client will lazy load the kid by doing a POST to newAccount whenever the kid is required. Therefore, you can easily get your kid for an existing account and (if needed) store it for reuse:

ruby
client = Acme::Client.new(private_key: private_key, directory: 'https://acme-staging-v02.api.letsencrypt.org/directory')

# kid is not set, therefore a call to newAccount is made to lazy-initialize the kid
client.kid
=> "https://acme-staging-v02.api.letsencrypt.org/acme/acct/000000"

External Account Binding support

You can use External Account Binding by providing a external_account_binding with a kid and hmac_key.

ruby
client = Acme::Client.new(private_key: private_key, directory: 'https://acme.zerossl.com/v2/DV90')
account = client.new_account(contact: 'mailto:[email protected]', terms_of_service_agreed: true, external_account_binding: { kid: "your kid", hmac_key: "your hmac key"})

Obtaining a certificate

Ordering a certificate

To order a new certificate, the client must provide a list of identifiers.

The returned order will contain a list of Authorization that need to be completed in other to finalize the order, generally one per identifier.

Each authorization contains multiple challenges, typically a dns-01, dns-account-01, and a http-01 challenge. The applicant is only required to complete one of the challenges.

The dns-account-01 challenge prepends an account-specific label before _acme-challenge, producing a record name of the form _._acme-challenge so different clients can validate the same domain concurrently.

You can access the challenge you wish to complete using the #dns, #dns_account, or #http methods.

ruby
order = client.new_order(identifiers: ['example.com'])
authorization = order.authorizations.first
challenge = authorization.http

Preparing for HTTP challenge

To complete the HTTP challenge, you must return a file using HTTP.

The path follows the following format:

.well-known/acme-challenge/#{token}

And the file content is the key authorization. The HTTP01 object has utility methods to generate them.

ruby
> http_challenge.content_type # => 'text/plain'
> http_challenge.file_content # => example_token.TO1xJ0UDgfQ8WY5zT3txynup87UU3PhcDEIcuPyw4QU
> http_challenge.filename # => '.well-known/acme-challenge/example_token'
> http_challenge.token # => 'example_token'

For test purposes you can just save the challenge file and use Ruby to serve it:

bash
ruby -run -e httpd public -p 8080 --bind-address 0.0.0.0

Preparing for DNS challenge

To complete the DNS challenge, you must set a DNS record to prove that you control the domain.

The DNS01 object has utility methods to generate them.

ruby
dns_challenge.record_name # => '_acme-challenge'
dns_challenge.record_type # => 'TXT'
dns_challenge.record_content # => 'HRV3PS5sRDyV-ous4HJk4z24s5JjmUTjcCaUjFt28-8'

Preparing for DNS-Account-01 challenge

To complete the DNS-Account-01 challenge, you must set a DNS TXT record using an account-specific name. This allows multiple ACME clients to validate the same domain concurrently without conflicts.

The DNSAccount01 object has utility methods to generate the required DNS record:

ruby
dns_account_challenge = authorization.dns_account

dns_account_challenge.record_name    # => '_ujmmovf2vn55tgye._acme-challenge'
dns_account_challenge.record_type    # => 'TXT'
dns_account_challenge.record_content # => 'HRV3PS5sRDyV-ous4HJk4z24s5JjmUTjcCaUjFt28-8'

The record name includes an account-specific label derived from your account URL, ensuring different clients can validate simultaneously:

  • DNS-01: _acme-challenge.example.com (shared)
  • DNS-Account-01: _ujmmovf2vn55tgye._acme-challenge.example.com (account-specific)

Requesting a challenge verification

Once you are ready to complete the challenge, you can request the server perform the verification.

ruby
challenge.request_validation

The validation is performed asynchronously and can take some time to be performed by the server.

You can poll until its status changes.

ruby
while challenge.status == 'pending'
  sleep(2)
  challenge.reload
end
challenge.status # => 'valid'

Downloading a certificate

Once all required authorizations have been validated through challenges, the order can be finalized using a CSR (Certificate Signing Request).

A CSR can be slightly tricky to generate using OpenSSL from Ruby standard library. acme-client provide a utility class CertificateRequest to help with that. You'll need to use a different private key for the certificate request than the one you use for your Acme::Client account.

Certificate generation happens asynchronously. You may need to poll.

ruby
csr = Acme::Client::CertificateRequest.new(private_key: a_different_private_key, subject: { common_name: 'example.com' })
order.finalize(csr: csr)
while order.status == 'processing'
  sleep(1)
  order.reload
end
order.certificate # => PEM-formatted certificate

When the server fails issuance after accepting the finalize request, the order moves to invalid and carries a problem document explaining why.

ruby
if order.status == 'invalid'
  order.error       # => { "type" => "urn:ietf:params:acme:error:rateLimited", "detail" => "..." }
  order.typed_error # => Acme::Client::Error::RateLimited
end

Ordering an alternative certificate

The provider may provide alternate certificate with different certificate chain. You can specify the required chain and the client will automatically download alternate certificate and match the chain by name.

ruby
begin
  order.certificate(force_chain: 'DST Root CA X3')
rescue Acme::Client::Error::ForcedChainNotFound
  order.certificate
end

Note: if the specified forced chain doesn't match an existing alternative certificate the method will raise an Acme::Client::Error::ForcedChainNotFound error.

Learn more about the original Github issue for this client here, information from Let's Encrypt here, and cross-signing here.

Extra

Certificate revokation

To revoke a certificate you can call #revoke with the certificate.

ruby
client.revoke(certificate: certificate)

Certificate renewal

There is no renewal process, just create a new order.

Account Key Roll-over

To change the key used for an account you can call #account_key_change with the new private key or jwk.

ruby
require 'openssl'
new_private_key = OpenSSL::PKey::RSA.new(4096)
client.account_key_change(new_private_key: new_private_key)

Profile Extension

Provide a CA profile when creating a new order:

ruby
order = client.new_order(identifiers: ['example.com'], profile: 'shortlived')

ACME servers may list supported profiles in the directory endpoint:

ruby
client.profiles => {"classic": "https://example.com/docs/classic", "shortlived": "https://example.com/docs/shortlived"}

See the RFC draft of certificate profiles for more info.

Requirements

Ruby >= 3.0

Development

All the tests use VCR to mock the interaction with the server. If you need to record new interaction you can specify the directory URL with the ACME_DIRECTORY_URL environment variable.

ACME_DIRECTORY_URL=https://acme-staging-v02.api.letsencrypt.org/directory rspec

Pull request?

Yes.

License

MIT License

Issues· 1 开放

查看全部 Issues在 GitHub 打开

暂无开放 Issues,或尚未同步最近议题。

> 标签

Ruby

暂无评论,来聊聊你的看法吧

> 工具信息

发布日期2026年8月1日
最后更新2026年9月17日
分类编程语言
定价开源

> 相关工具

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言