letsencrypt-nginx Documentation

letsencrypt-nginx Documentation Release 0

Let’s Encrypt Project

April 14, 2016

Contents

1

2

API Documentation 1.1 letsencrypt_nginx.nginxparser 1.2 letsencrypt_nginx.obj . . . . . . 1.3 letsencrypt_nginx.parser . . . . 1.4 letsencrypt_nginx.tls_sni_01 .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

3 3 4 5 8

Indices and tables

9

Python Module Index

11

i

ii

letsencrypt-nginx Documentation, Release 0

Contents:

Contents

1

letsencrypt-nginx Documentation, Release 0

2

Contents

CHAPTER 1

API Documentation

1.1 letsencrypt_nginx.nginxparser Very low-level nginx config parser based on pyparsing. class letsencrypt_nginx.nginxparser.RawNginxParser(source) Bases: object A class that parses nginx configuration with pyparsing. parse() Returns the parsed tree. as_list() Returns the parsed tree as a list. class letsencrypt_nginx.nginxparser.RawNginxDumper(blocks, indentation=4) Bases: object A class that dumps nginx configuration from the provided tree. letsencrypt_nginx.nginxparser.loads(source) Parses from a string. Parameters souce (str) – The string to parse Returns The parsed tree Return type list letsencrypt_nginx.nginxparser.load(_file) Parses from a file. Parameters _file (file) – The file to parse Returns The parsed tree Return type list letsencrypt_nginx.nginxparser.dumps(blocks, indentation=4) Dump to a string. Parameters • block (list) – The parsed tree • indentation (int) – The number of spaces to indent Return type str 3

letsencrypt-nginx Documentation, Release 0

letsencrypt_nginx.nginxparser.dump(blocks, _file, indentation=4) Dump to a file. Parameters • block (list) – The parsed tree • _file (file) – The file to dump to • indentation (int) – The number of spaces to indent Return type NoneType

1.2 letsencrypt_nginx.obj Module contains classes used by the Nginx Configurator. class letsencrypt_nginx.obj.Addr(host, port, ssl, default) Bases: letsencrypt.plugins.common.Addr Represents an Nginx address, i.e. what comes after the ‘listen’ directive. According to the documentation, this may be address[:port], port, or unix:path. The latter is ignored here. The default value if no directive is specified is *:80 (superuser) or *:8000 (otherwise). If no port is specified, the default is 80. If no address is specified, listen on all addresses. Todo Old-style nginx configs define SSL vhosts in a separate block instead of using ‘ssl’ in the listen directive.

Parameters • addr (str) – addr part of vhost address, may be hostname, IPv4, IPv6, “”, or “*” • port (str) – port number or “*” or “” • ssl (bool) – Whether the directive includes ‘ssl’ • default (bool) – Whether the directive includes ‘default_server’ classmethod fromstring(str_addr) Initialize Addr from string. class letsencrypt_nginx.obj.VirtualHost(filep, addrs, ssl, enabled, names, raw) Bases: object Represents an Nginx Virtualhost. Variables • filep (str) – file path of VH • addrs (set) – Virtual Host addresses (set of Addr) • names (set) – Server names/aliases of vhost (list of str) • raw (list) – The raw form of the parsed server block • ssl (bool) – SSLEngine on in vhost • enabled (bool) – Virtual host is enabled

4

Chapter 1. API Documentation

letsencrypt-nginx Documentation, Release 0

1.3 letsencrypt_nginx.parser NginxParser is a member object of the NginxConfigurator class. class letsencrypt_nginx.parser.NginxParser(root, ssl_options) Bases: object Class handles the fine details of parsing the Nginx Configuration. Variables • root (str) – Normalized abosulte path to the server root directory. Without trailing slash. • parsed (dict) – Mapping of file paths to parsed trees load() Loads Nginx files into a parsed tree. _parse_recursively(filepath) Parses nginx config files recursively by looking at ‘include’ directives inside ‘http’ and ‘server’ blocks. Note that this only reads Nginx files that potentially declare a virtual host. Parameters filepath (str) – The path to the files to parse, as a glob abs_path(path) Converts a relative path to an absolute path relative to the root. Does nothing for paths that are already absolute. Parameters path (str) – The path Returns The absolute path Return type str get_vhosts() Gets list of all ‘virtual hosts’ found in Nginx configuration. Technically this is a misnomer because Nginx does not have virtual hosts, it has ‘server blocks’. Returns List of VirtualHost objects found in configuration Return type list _get_included_directives(block) Returns array with the “include” directives expanded out by concatenating the contents of the included file to the block. Parameters block (list) – Return type list _parse_files(filepath, override=False) Parse files from a glob Parameters • filepath (str) – Nginx config file path • override (bool) – Whether to parse a file that has been parsed Returns list of parsed tree structures Return type list _set_locations(ssl_options) Set default location for directives.

1.3. letsencrypt_nginx.parser

5

letsencrypt-nginx Documentation, Release 0

Locations are given as file_paths .. todo:: Make sure that files are included _find_config_root() Find the Nginx Configuration Root file. filedump(ext=’tmp’) Dumps parsed configurations into files. Parameters ext (str) – The file extension to use for the dumped files. If empty, this overrides the existing conf files. _has_server_names(entry, names) Checks if a server block has the given set of server_names. This is the primary way of identifying server blocks in the configurator. Returns false if ‘entry’ doesn’t look like a server block at all. ..todo :: Doesn’t match server blocks whose server_name directives are split across multiple conf files. Parameters • entry (list) – The block to search • names (set) – The names to match Return type bool add_server_directives(filename, names, directives, replace) Add or replace directives in the first server block with names. ..note :: If replace is True, this raises a misconfiguration error if the directive does not already exist. ..note :: If replace is False nothing gets added if an identical block exists already. ..todo :: Doesn’t match server blocks whose server_name directives are split across multiple conf files. Parameters • filename (str) – The absolute filename of the config file • names (set) – The server_name to match • directives (list) – The directives to add • replace (bool) – Whether to only replace existing directives add_http_directives(filename, directives) Adds directives to the first encountered HTTP block in filename. We insert new directives at the top of the block to work around https://trac.nginx.org/nginx/ticket/810: If the first server block doesn’t enable OCSP stapling, stapling is broken for all blocks. Parameters • filename (str) – The absolute filename of the config file • directives (list) – The directives to add get_all_certs_keys() Gets all certs and keys in the nginx config. Returns list of tuples with form [(cert, key, path)] cert - str path to certificate file key - str path to associated key file path - File path to configuration file. Return type set letsencrypt_nginx.parser._do_for_subarray(entry, condition, func) Executes a function for a subarray of a nested array if it matches the given condition.

6

Chapter 1. API Documentation

letsencrypt-nginx Documentation, Release 0

Parameters • entry (list) – The list to iterate over • condition (function) – Returns true iff func should be executed on item • func (function) – The function to call for each matching item letsencrypt_nginx.parser.get_best_match(target_name, names) Finds the best match for target_name out of names using the Nginx name-matching rules (exact > longest wildcard starting with * > longest wildcard ending with * > regex). Parameters • target_name (str) – The name to match • names (set) – The candidate server names Returns Tuple of (type of match, the name that matched) Return type tuple letsencrypt_nginx.parser._is_include_directive(entry) Checks if an nginx parsed entry is an ‘include’ directive. Parameters entry (list) – the parsed entry Returns Whether it’s an ‘include’ directive Return type bool letsencrypt_nginx.parser._get_servernames(names) Turns a server_name string into a list of server names Parameters names (str) – server names Return type list letsencrypt_nginx.parser.parse_server(server) Parses a list of server directives. Parameters server (list) – list of directives in a server block Return type dict letsencrypt_nginx.parser._add_directives(block, directives, replace) Adds or replaces directives in a config block. When replace=False, it’s an error to try and add a directive that already exists in the config block with a conflicting value. When replace=True, a directive with the same name MUST already exist in the config block, and the first instance will be replaced. ..todo :: Find directives that are in included files. Parameters • block (list) – The block to replace in • directives (list) – The new directives. letsencrypt_nginx.parser._add_directive(block, directive, replace) Adds or replaces a single directive in a config block. See _add_directives for more documentation.

1.3. letsencrypt_nginx.parser

7

letsencrypt-nginx Documentation, Release 0

1.4 letsencrypt_nginx.tls_sni_01 A class that performs TLS-SNI-01 challenges for Nginx class letsencrypt_nginx.tls_sni_01.NginxTlsSni01(configurator) Bases: letsencrypt.plugins.common.TLSSNI01 TLS-SNI-01 authenticator for Nginx Variables • configurator – NginxConfigurator object • achalls (list) – Annotated class:KeyAuthorizationAnnotatedChallenge challenges Parameters • indices (list) – Meant to hold indices of challenges in a larger array. NginxTlsSni01 is capable of solving many challenges at once which causes an indexing issue within NginxConfigurator who must return all responses in order. Imagine NginxConfigurator maintaining state about where all of the http-01 Challenges, TLS-SNI-01 Challenges belong in the response array. This is an optional utility. • challenge_conf (str) – location of the challenge config file perform() Perform a challenge on Nginx. Returns list of letsencrypt.acme.challenges.TLSSNI01Response Return type list _mod_config(ll_addrs) Modifies Nginx config to include challenge server blocks. Parameters ll_addrs (list) – list of lists of letsencrypt_nginx.obj.Addr to apply Raises .MisconfigurationError – Unable to find a suitable HTTP block in which to include authenticator hosts. _make_server_block(achall, addrs) Creates a server block for a challenge. Parameters • achall (letsencrypt.achallenges.KeyAuthorizationAnnotatedChallenge) – Annotated TLS-SNI-01 challenge • addrs (list) – addresses of challenged domain list of type Addr Returns server block for the challenge host Return type list Let’s Encrypt nginx plugin.

8

Chapter 1. API Documentation

CHAPTER 2

Indices and tables

• genindex • modindex • search

9

letsencrypt-nginx Documentation, Release 0

10

Chapter 2. Indices and tables

Python Module Index

l letsencrypt_nginx, 8 letsencrypt_nginx.nginxparser, 3 letsencrypt_nginx.obj, 4 letsencrypt_nginx.parser, 5 letsencrypt_nginx.tls_sni_01, 8

11

letsencrypt-nginx Documentation, Release 0

12

Python Module Index

Index

Symbols

Addr (class in letsencrypt_nginx.obj), 4 _add_directive() (in module letsencrypt_nginx.parser), 7 as_list() (letsencrypt_nginx.nginxparser.RawNginxParser method), 3 _add_directives() (in module letsencrypt_nginx.parser), 7 _do_for_subarray() (in module letsencrypt_nginx.parser), D 6 _find_config_root() (letsen- dump() (in module letsencrypt_nginx.nginxparser), 3 crypt_nginx.parser.NginxParser method), dumps() (in module letsencrypt_nginx.nginxparser), 3 6 _get_included_directives() (letsen- F crypt_nginx.parser.NginxParser method), filedump() (letsencrypt_nginx.parser.NginxParser 5 method), 6 _get_servernames() (in module letsen- fromstring() (letsencrypt_nginx.obj.Addr class method), crypt_nginx.parser), 7 4 _has_server_names() (letsencrypt_nginx.parser.NginxParser method), G 6 get_all_certs_keys() (letsen_is_include_directive() (in module letsencrypt_nginx.parser.NginxParser method), crypt_nginx.parser), 7 6 _make_server_block() (letsen- get_best_match() (in module letsencrypt_nginx.parser), 7 crypt_nginx.tls_sni_01.NginxTlsSni01 get_vhosts() (letsencrypt_nginx.parser.NginxParser method), 8 method), 5 _mod_config() (letsencrypt_nginx.tls_sni_01.NginxTlsSni01 method), 8 L _parse_files() (letsencrypt_nginx.parser.NginxParser letsencrypt_nginx (module), 8 method), 5 letsencrypt_nginx.nginxparser (module), 3 _parse_recursively() (letsen- letsencrypt_nginx.obj (module), 4 crypt_nginx.parser.NginxParser method), letsencrypt_nginx.parser (module), 5 5 letsencrypt_nginx.tls_sni_01 (module), 8 _set_locations() (letsencrypt_nginx.parser.NginxParser load() (in module letsencrypt_nginx.nginxparser), 3 method), 5 load() (letsencrypt_nginx.parser.NginxParser method), 5

A

loads() (in module letsencrypt_nginx.nginxparser), 3

abs_path() (letsencrypt_nginx.parser.NginxParser N method), 5 NginxParser (class in letsencrypt_nginx.parser), 5 add_http_directives() (letsen- NginxTlsSni01 (class in letsencrypt_nginx.tls_sni_01), 8 crypt_nginx.parser.NginxParser method), 6 P add_server_directives() (letsenparse() (letsencrypt_nginx.nginxparser.RawNginxParser crypt_nginx.parser.NginxParser method), method), 3 6 parse_server() (in module letsencrypt_nginx.parser), 7 13

letsencrypt-nginx Documentation, Release 0

perform() (letsencrypt_nginx.tls_sni_01.NginxTlsSni01 method), 8

R RawNginxDumper (class in crypt_nginx.nginxparser), 3 RawNginxParser (class in crypt_nginx.nginxparser), 3

letsenletsen-

V VirtualHost (class in letsencrypt_nginx.obj), 4

14

Index