From d06cd7aa39484035fb2a4e881afb6644e897f115 Mon Sep 17 00:00:00 2001 From: pde and jdkasten Date: Sat, 21 Mar 2015 13:56:40 -0700 Subject: [PATCH] Update dev docs - Import and edit James's API docs into CONTRIBUTING.rst - Linke correctly to CONTRIBUTING from the main README --- CONTRIBUTING.rst | 77 ++++++++++++++++++++++++++++++++++++++++++++++++ README.rst | 3 +- 2 files changed, 79 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index bfd0a1c0f..654d5569b 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -27,6 +27,83 @@ The following tools are there to help you: .. _installing dependencies and setting up Let's Encrypt: https://letsencrypt.readthedocs.org/en/latest/using.html +CODE COMPONENTS AND LAYOUT +========================== + +letsencrypt/acme - contains all protocol specific code +letsencrypt/client - all client code +letsencrypt/scripts - just the starting point of the code, main.py + +Plugin-architecture +------------------- + +Let's Encrypt has a plugin architecture to facilitate support for different +webservers, other TLS servers, and operating systems. + +The most common kind of plugin is a "Configurator", which is likely to +implement the "Authenticator" and "Installer" interfaces (though some +Configurators may implement just one of those). + +Defined here: +https://github.com/letsencrypt/lets-encrypt-preview/blob/master/letsencrypt/client/interfaces.py + +There are also "Display" plugins, which implement bindings to alternative UI +libraries. + +Authenticators +-------------- + +Authenticators are plugins designed to solve challenges received from the +ACME server. From the protocol, there are essentially two different types +of challenges. Challenges that must be solved by individual plugins in +order to satisfy domain validation (dvsni, simpleHttps, dns) and client +specific challenges (recoveryToken, recoveryContact, pop). Client specific +challenges are always handled by the "Authenticator" +client_authenticator.py. Right now we have two DV Authenticators, +apache/configurator.py and the standalone_authenticator.py. The Standalone +and Apache authenticators only solve the DVSNI challenge currently. (You +can set which challenges your authenticator can handle through the +get_chall_pref(domain) function) + +(FYI: We also have a partial implementation for a dns_authenticator in a +separate branch). + +Challenge types are defined here... +( +https://github.com/letsencrypt/lets-encrypt-preview/blob/master/letsencrypt/client/constants.py#L16 +) + +Installer +--------- + +Installers classes exist to actually setup the certificate and be able +to enhance the configuration. (Turn on HSTS, redirect to HTTPS, etc). You +can indicate your abilities through the supported_enhancements call. We +currently only have one Installer written (still developing), +apache/configurator.py + +Installers and Authenticators will oftentimes be the same class/object. +Installers and Authenticators are kept separate because it should be +possible to use the standalone_authenticator (it sets up its own Python +server to perform challenges) with a program that cannot solve challenges +itself. (I am imagining MTA installers). + +*Display* - we currently offer a pythondialog and "text" mode for +displays. I have rewritten the interface which should be merged within the +next day (the rewrite is in the revoker branch of the repo and should be +merged within the next day) + +Here is what the display interface will look like +https://github.com/letsencrypt/lets-encrypt-preview/blob/revoker/letsencrypt/client/interfaces.py#L217 + +Augeus +------ + +Some plugins, especially those designed to reconfigure UNIX servers, can take +inherit from the augeus_configurator.py class in order to more efficiently +handle common operations on UNIX server configuration files. + + .. _coding-style: Coding style ============ diff --git a/README.rst b/README.rst index c27279ade..86d85ed1d 100644 --- a/README.rst +++ b/README.rst @@ -80,7 +80,7 @@ Documentation: https://letsencrypt.readthedocs.org/ Software project: https://github.com/letsencrypt/lets-encrypt-preview -Notes for developers: [CONTRIBUTING.rst](/CONTRIBUTING.rst) +Notes for developers: CONTRIBUTING.rst_ Main Website: https://letsencrypt.org/ @@ -91,3 +91,4 @@ email to client-dev+subscribe@letsencrypt.org) .. _Freenode: https://freenode.net .. _client-dev: https://groups.google.com/a/letsencrypt.org/forum/#!forum/client-dev +.. _CONTRIBUTING.rst: https://github.com/letsencrypt/lets-encrypt-preview/blob/master/CONTRIBUTING.rst