certsling 0.10.0
Opinionated letsencrypt acme client working via a ssh port forward.
Requires Python: >=3.7

certsling
=========

An opinionated script to sign tls keys via `letsencrypt`_ on your local computer by forwarding the HTTP/DNS challenge via ssh.

.. _certsling: https://pypi.python.org/pypi/certsling
.. _letsencrypt: https://letsencrypt.org


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

Best installed via `pipsi`_::

    % pipsi install certsling

Or some other way to install a python package with included scripts.

.. _pipsi: https://pypi.python.org/pypi/pipsi


Requirements
------------

You need an ``openssl`` executable in your path for key generation and signing.


Testing with staging server
---------------------------

With the ``-s`` option you can use the staging server of `letsencrypt`_.
This is advised, so you don't run into quota limits or similar until your setup works.
The resulting certificate won't validate, but otherwise has the same content as a regular certificate.


Basic usage
-----------

Create a directory with the email address as the name, which you want to use for authentication with letsencrypt.
For example ``webmaster@example.com``::

    % mkdir webmaster@example.com

Create a ssh connection to your server which forwards a remote port to the local port ``8080``::

    % ssh root@example.com -R 8080:localhost:8080

On your server the webserver needs to proxy requests to ``example.com:80/.well-known/acme-challenge/*`` to that forwarded port.
An example for nginx::

        location /.well-known/acme-challenge/ {
            proxy_pass http://localhost:8080;
        }

From the directory you created earlier, invoke the ``certsling`` script with for example::

    % cd webmaster@example.com
    % certsling example.com www.example.com

On first run, you are asked whether to create a ``user.key`` for authorization with letsencrypt.

After that, challenges for the selected domains are created and a server is started on port ``8080`` to provide responses.
Your remote web server proxies them through the ssh connection to the locally running server.

If all went well, you get a server key and certificate in a new ``example.com`` folder::

    % ls example.com
    ...
    example.com-chained.crt
    example.com.crt
    example.com.key

The ``example.com-chained.crt`` file contains the full chain of you certificate together with the letsencrypt certificate.


Advanced usage
--------------

To use DNS based authentication, you need to have ``socat`` on your server.
Additionally you need to setup your DNS, so it delegates ``_acme-challenge`` requests to your server.
For that you can add something similar to this to your zone file or equivalent::

    _acme-challenge IN NS www
    _acme-challenge.www IN NS www

For the forwarding, you need to add port ``8053``::
Create a ssh connection to your server which forwards a remote port to the local port ``8080``::

    % ssh root@example.com -R 8080:localhost:8080 -R 8053:localhost:8053

Then in that ssh session, run the following to forward UDP port ``53`` to TCP on port ``8053``::

    # socat -T15 udp4-recvfrom:53,reuseaddr,fork tcp:localhost:8053

For ``certsling`` you need to add the `--dns`` option::

    % certsling --dns example.com www.example.com

It will then first try the HTTP challenge and if that fails it will try the DNS challenge.


Changelog
=========

0.10.0 - 2022-02-17
-------------------

* Drop Python 3.5 and 3.6 support, add Python 3.9 and 3.10.
  [fschulze]

* Add option to always update with current settings without asking.
  [fschulze]

* Updates for new root certificates.
  [fschulze]

* Output more info for failed authorizations.
  [fschulze]


0.9.1 - 2020-08-23
------------------

* Accept return code 200 for nonce request.
  [witsch]


0.9.0 - 2020-06-14
------------------

* Switch to ACME Version 2 aka RFC 8555 protocol.
  [fschulze]

* Enable ``-h`` for command line help output.
  [fschulze]

* Add option to disable HTTP challenge.
  [fschulze]

* Only start servers for enabled challenges.
  [fschulze]

* Drop Python 3.4 support.
  Python 3.5 support will end at it's EOL in September 2020.
  [fschulze]

* Exit when no domain was provided.
  [fschulze]

* Add ``-y`` option to automatically answer yes for any question.


0.8.0 - 2017-01-04
------------------

* Add new ``--update`` (``-u``) option to avoid having to remember the settings
  for each domain.
  [fschulze]

* Ask to repeat csr and crt generation on failure.
  [solidgoldbomb]

* Switch to dnspython after it merged with dnspython3.
  [fschulze]


0.7.0 - 2016-12-30
------------------

* Renamed to ``certsling``.
  [fschulze]

* Use symmetric difference in ``verify_domains``. This catches problems due to
  typos in domain names and some other cases.
  [solidgoldbomb]

* Update list of issuer names checked in ``verify_crt``.
  [solidgoldbomb (Stacey Sheldon)]

* More detailed error reporting.
  [fschulze]

* Ask to agree to terms of use of letsencrypt and allow updating the registration.
  [fschulze]


0.6.0 - 2016-05-09
------------------

* Upgrade to new X3 authority.
  [fschulze]


0.5.0 - 2016-02-12
------------------

* Allow selection of letsencrypt.org staging server with ``-s`` option.
  [fschulze]


0.4.1 - 2016-01-29
------------------

* Fix issue that the ``-chained.crt`` file wasn't updated.
  [fschulze]


0.4.0 - 2016-01-12
------------------

* Initial release
  [fschulze]