Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/0x7466/LeSSL

A certificate manager for lets-encrypt certificates
https://github.com/0x7466/LeSSL

Last synced: 1 day ago
JSON representation

A certificate manager for lets-encrypt certificates

Host: GitHub
URL: https://github.com/0x7466/LeSSL
Owner: 0x7466
License: mit
Created: 2016-02-10T13:31:27.000Z (almost 9 years ago)
Default Branch: master
Last Pushed: 2023-04-19T18:28:57.000Z (over 1 year ago)
Last Synced: 2024-11-10T12:05:50.641Z (3 days ago)
Language: Ruby
Size: 146 KB
Stars: 205
Watchers: 4
Forks: 6
Open Issues: 0
Metadata Files:
- Readme: README.md
- License: MIT-LICENSE

Awesome Lists containing this project

README

LeSSL
=====

[![Gem Version](https://badge.fury.io/rb/le_ssl.svg)](https://badge.fury.io/rb/le_ssl)
[![Build Status](https://travis-ci.org/tobiasfeistmantl/LeSSL.svg?branch=master)](https://travis-ci.org/tobiasfeistmantl/LeSSL)

LeSSL is a simple gem to authorize for domains and obtaining certificates from the Let's Encrypt CA. Now it's very easy to get free and trusted SSL certificates!

Compatibility
-------------

Rails 4+

Installation
------------

Install from Rubygems:

```
$ gem install le_ssl
```

or add it to your Gemfile:

```ruby
gem 'le_ssl'
```

And then run `bundle install` and you are ready to go.

Getting Started
---------------

Create an instance of the LeSSL Manager:

```ruby
private_key = OpenSSL::PKey::RSA.new(4096)
manager = LeSSL::Manager.new(email: '[email protected]', agree_terms: true, private_key: private_key)
```
It's recommended to store the contact email and the private key in environment variables because you are just allowed to obtain certificates for domains you are authorized for.

If you have `LESSL_CLIENT_PRIVATE_KEY` and `LESSL_CONTACT_EMAIL` set, you don't have to pass them to the initializer.

```ruby
# Example
manager = LeSSL::Manager.new(agree_terms: true) # Accepting the terms is enough
```

The manager registers automatically a new account on the Let's Encrypt servers.

Authorize for a domain now:

**Important! Every domain you want to be authorized for must have a valid A record which points to your server IP!**

```ruby
manager.authorize_for_domain('example.com')
manager.authorize_for_domain('www.example.com')
```

If your domain is properly set up, you should now be authorized for the domain. Be also sure that your Rails server is running.

Obtaining a SSL certificate:

```ruby
manager.request_certificate('www.example.com', 'example.com')
```

This puts the public and private keys into `config/ssl`. Now you just have to configure your webserver to use these certificates and you should be ready for encrypted HTTP.

**Note that you have to authorize seperately for subdomains (e.g. www.example.com)!**

Use DNS verification
--------------------

If the domain isn't pointing to your server, you can also use a DNS TXT verification. Simply pass the option `:challenge` with the value `:dns` to the parameters of the `#authorize_for_domain` method:

```ruby
challenge = manager.authorize_for_domain('example.com', challenge: :dns)
```

**Important!** Save the returned value into a variable because it's needed to request the verification!

Then create the corresponding DNS TXT record for your domain. (Hint: The `#authorize_for_domain` method prints the information if you use it from the command line)

Wait a few minutes to be sure that the record was updated by the Let's encrypt servers.

And as last step request the verification for the challenge.

```ruby
manager.request_verification(challenge)
```

This returns the verification status afterwards.

If this returns `valid` you are authorized to obtain a certificate for this domain.

### Automatic verification

You can tell LeSSL to verify the DNS record automatically. In this way you don't have to worry if the DNS record is already present.

**Caution!** This option is blocking the thread until the verification is completed!

```ruby
manager.authorize_for_domain('example.com', challenge: :dns, automatic_verification: true)
```

By default, LeSSL uses the Google public nameservers (8.8.8.8 and 8.8.4.4) to check the records but you can use also your own ones:

```ruby
manager.authorize_for_domain('example.com', challenge: :dns, automatic_verification: true, custom_nameservers: 32.34.65.23)
```

The verification process may take some time, especially if you already have an _acme-challenge TXT record in your DNS table with a higher TTL. If you are able to configure the TTL on your own set it the shortest possible TTL. (E.g. 60 seconds)

Skip registration
-----------------

You can also skip the automatic registering which is done in the initializer:

```ruby
manager = LeSSL::Manager.new(agree_terms: true, email: '[email protected]', private_key: private_key, skip_register: true)
```

To register an account call the `#register` method:

```ruby
manager.register('[email protected]')
```

Development
-----------

LeSSL uses the staging servers of Let's Encrypt if the Rails environment is set to 'development'.

You need help?
--------------

Ask a question on [StackOverflow](https://stackoverflow.com/) with the tag 'le-ssl'.

Planned Features
----------------

* Automatically renew certificates with an ActiveJob job
* Automatically install certificates in popular web servers

We welcome also other feature request and of course feature pull requests!

Other things to do
------------------

* **To test the gem.**

Also here we would be thankful for pull requests.

Contribution
------------

Create pull requests on Github and help us to improve this gem. There are some guidelines to follow:

* Follow the conventions
* Test all your implementations
* Document methods which aren't self-explaining (we are using [YARD](http://yardoc.org/))