acme-client

Acme::Client

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

You can find the server reference implementation for ACME server here and also the a reference client in python.

ACME is part of the Letsencrypt project, that are working hard at encrypting all the things.

Usage

# We're going to need a private key.
require 'openssl'
private_key = OpenSSL::PKey::RSA.new(2048)

# We need an ACME server to talk to, see github.com/letsencrypt/boulder
endpoint = 'https://acme-staging.api.letsencrypt.org'

# Initialize the client
require 'acme-client'
client = Acme::Client.new(private_key: private_key, endpoint: endpoint)

# If the private key is not known to the server, we need to register it for the first time.
registration = client.register(contact: 'mailto:unixcharles@gmail.com')

# You'll may need to agree to the term (that's up the to the server to require it or not but boulder does by default)
registration.agree_terms

# Let's try to optain a certificate for yourdomain.com

# We need to prove that we control the domain using one of the challenges method.
authorization = client.authorize(domain: 'yourdomain.com')

# For now the only challenge method supprted by the client is http-01.
challenge = authorization.http01

# The http-01 method will require you to response to an HTTP request.

# You can retrieve the expected path for the file.
challenge.filename # => ".well-known/acme-challenge/:some_token"

# You can generate the body of the expected response.
challenge.file_content # => 'string token and JWK thumbprint' 

# You can send no Content-Type at all but if you send one it has to be 'text/plain'.
challenge.content_type
  
# Save the file. We'll create a public directory to serve it from, and we'll creating the challenge directory.
FileUtils.mkdir_p( File.join( 'public', File.dirname( challenge.filename ) ) )

# Then writing the file
File.open( File.join( 'public', challenge.filename), 'w') {|f| f << challenge.file_content }

# The challenge file can be server with a Ruby webserver such as run a webserver in another console. You may need to forward ports on your router
#ruby -run -e httpd public -p 8080 --bind-address 0.0.0.0


# Once you are ready to serve the confirmation request you can proceed.
challenge.request_verification # => true
challenge.verify_status # => 'pending'

# Wait a bit for the server to make the request, or really just blink, it should be fast.
sleep(1)

challenge.verify_status # => 'valid'

# We're going to need a CSR, lets do this real quick with Ruby+OpenSSL.
csr = OpenSSL::X509::Request.new

# We need a private key for the certificate, not the same as the account key.
certificate_private_key = OpenSSL::PKey::RSA.new(2048)

# We just going to add the domain but normally you might want to provide more information.
csr.subject = OpenSSL::X509::Name.new([
  ['CN', 'yourdomain.com', OpenSSL::ASN1::UTF8STRING]
])

csr.public_key = certificate_private_key.public_key
csr.sign(certificate_private_key, OpenSSL::Digest::SHA256.new)

# We can now request a certificate
https_cert = client.new_certificate(csr) # => #<OpenSSL::X509::Certificate ....>

# Save the certificate and key
File.open("server.crt", 'w') {|f| f << https_cert }
File.open("server.key", 'w') {|f| f << certificate_private_key }

# Start a webserver, using your shiny new certificate
# ruby -r openssl -r webrick -r 'webrick/https' -e "s = WEBrick::HTTPServer.new(
#   :Port => 8443,
#   :DocumentRoot => Dir.pwd,
#   :SSLEnable => true,
#   :SSLPrivateKey => OpenSSL::PKey::RSA.new( File.open('server.key').read),
#   :SSLCertificate => OpenSSL::X509::Certificate.new( File.open('server.crt').read)); trap('INT') { s.shutdown }; s.start"

Not implemented

• Recovery methods are not implemented.
• http-01 is the only challenge method implemented

Development

All the tests use VCR to mock the interaction with the server but if you need to record new interation against the server simply clone boulder and run it normally with ./start.py.

Pull request?

Yes.

License

MIT License