Merge pull request #13 from shoddyguard/add_tls

Add TLS Support

Author: shoddyguard

CHANGELOG.md

@@ -12,14 +12,15 @@ All notable changes to this project will be documented in this file.
 - Tidied up documentation and added some more examples
 - Expanded acceptance testing slightly
 - Adds support for DHCP on IPV4 and IPV6, IPV6 remains untested
+- Adds experimental support for TLS/SSL
 
 **Bugfixes**
 Partially fixed #10 whereby you could not specify port numbers when using IP addresses (eg `127.0.0.1:5353` would fail).  
 This is marked as partially fixed as it works for IPV4 addresses but not IPV6 addresses at present.  
 Will require more familiarity with IPV6 before that can be implemented.
 
 **Known Issues**
-IPSET and TLS/SSL still not implemented
+IPSET still not implemented
 
 ### [v0.1.0](https://github.com/shoddyguard/Puppet-Adguard/tree/v0.1.0) (2020-03-21)
 

README.md

@@ -163,5 +163,4 @@ In these cases this module will disable `DNSStubListener` in `/etc/systemd/resol
 
 ## Unsupported features
 Currently this module does not support:
-- ipset
-- TLS/SSL settings
+- ipset

REFERENCE.md

@@ -14,6 +14,10 @@
 
 * `adguard::params`: Private class for managing some of the more complex default parameters
 
+### Functions
+
+* [`adguard::validate_tls_options`](#adguardvalidate_tls_options): This function ensures that the TLS config is valid before applying it.
+
 ### Data types
 
 * [`Adguard::Blocked_service`](#adguardblocked_service): A list of services that AdGuard Home is able to block out of the box.
@@ -24,9 +28,11 @@
 * [`Adguard::Dhcp_v6_options`](#adguarddhcp_v6_options): A structured hash for sepcifying DHCP options for IPV6
 * [`Adguard::Dns_server`](#adguarddns_server): Valid DNS server types
 * [`Adguard::Filter`](#adguardfilter): Used to manage filters in Adguard
+* [`Adguard::Http_proxy`](#adguardhttp_proxy): Very basic validation to ensure the proxy type is sensible
 * [`Adguard::Ipv4_port`](#adguardipv4_port): Accepts an IPV4 address with a port (eg 192.168.1.1:8080)
 * [`Adguard::Log_file`](#adguardlog_file): Supported log file types
 * [`Adguard::Rewrite`](#adguardrewrite): Stuctured hash for managing rewrites
+* [`Adguard::Tls_options`](#adguardtls_options): Configures TLS options in AdGuard Home
 * [`Adguard::User`](#adguarduser): A structed hash for providing users for the adguard web UI.
 
 ## Classes
@@ -104,6 +110,8 @@ The following parameters are available in the `adguard` class:
 * [`cache_time`](#cache_time)
 * [`rewrites`](#rewrites)
 * [`blocked_services`](#blocked_services)
+* [`enable_tls`](#enable_tls)
+* [`tls_options`](#tls_options)
 * [`filters`](#filters)
 * [`whitelist_filters`](#whitelist_filters)
 * [`user_rules`](#user_rules)
@@ -150,7 +158,7 @@ Note: the password needs to be in BCrypt-encrypted format.
 
 ##### <a name="http_proxy"></a>`http_proxy`
 
-Data type: `Optional[Stdlib::HTTPUrl]`
+Data type: `Optional[Adguard::Http_proxy]`
 
 Define an optional http_proxy.
 While adguard supports SOCKS5 alongside HTTP/S, this is **not** supported in the Puppet module at this time.
@@ -566,6 +574,22 @@ An array of any services you wish to block.
 
 Default value: ``undef``
 
+##### <a name="enable_tls"></a>`enable_tls`
+
+Data type: `Boolean`
+
+EXPERIMENTAL: enable TLS. This workflow is largely untested, use with caution.
+
+Default value: ``false``
+
+##### <a name="tls_options"></a>`tls_options`
+
+Data type: `Optional[Adguard::Tls_options]`
+
+The TLS configuration options.
+
+Default value: ``undef``
+
 ##### <a name="filters"></a>`filters`
 
 Data type: `Array[Adguard::Filter]`
@@ -740,6 +764,26 @@ The version to install from the GitHub release
 
 Default value: `'latest'`
 
+## Functions
+
+### <a name="adguardvalidate_tls_options"></a>`adguard::validate_tls_options`
+
+Type: Puppet Language
+
+This function ensures that the TLS config is valid before applying it.
+
+#### `adguard::validate_tls_options(Adguard::Tls_options $tls_options)`
+
+The adguard::validate_tls_options function.
+
+Returns: `Boolean` Returns true if the configuration is valid
+
+##### `tls_options`
+
+Data type: `Adguard::Tls_options`
+
+Accepts a hash of tls_options
+
 ## Data types
 
 ### <a name="adguardblocked_service"></a>`Adguard::Blocked_service`
@@ -858,6 +902,16 @@ Struct[{
 }]
 ```
 
+### <a name="adguardhttp_proxy"></a>`Adguard::Http_proxy`
+
+Very basic validation to ensure the proxy type is sensible
+
+Alias of
+
+```puppet
+Pattern[/^(http|https|socks5)\:\/\//]
+```
+
 ### <a name="adguardipv4_port"></a>`Adguard::Ipv4_port`
 
 Accepts an IPV4 address with a port (eg 192.168.1.1:8080)
@@ -891,6 +945,33 @@ Struct[{
 }]
 ```
 
+### <a name="adguardtls_options"></a>`Adguard::Tls_options`
+
+Configures TLS options in AdGuard Home
+
+* **See also**
+  * https://github.com/AdguardTeam/AdGuardHome/wiki/Encryption
+
+Alias of
+
+```puppet
+Struct[{
+  server_name           => Stdlib::Host,
+  force_https           => Boolean,
+  port_https            => Stdlib::Port,
+  port_dns_over_tls     => Stdlib::Port,
+  port_dns_over_quic    => Stdlib::Port,
+  port_dnscrypt         => Stdlib::Port,
+  dnscrypt_config_file  => Optional[Stdlib::Unixpath],
+  allow_unencrypted_doh => Boolean,
+  strict_sni_check      => Boolean,
+  certificate_chain     => Optional[String],
+  private_key           => Optional[String],
+  certificate_path      => Optional[Stdlib::Unixpath],
+  private_key_path      => Optional[Stdlib::Unixpath]
+}]
+```
+
 ### <a name="adguarduser"></a>`Adguard::User`
 
 A structed hash for providing users for the adguard web UI.

functions/validate_tls_options.pp

@@ -0,0 +1,38 @@
+# @summary 
+#   This function ensures that the TLS config is valid before applying it.
+#
+# @param tls_options
+#   Accepts a hash of tls_options
+#
+# @return [Boolean] Returns true if the configuration is valid
+function adguard::validate_tls_options(Adguard::Tls_options $tls_options) >> Boolean {
+  # If dnscrypt is enabled (any port other than 0) there must be a path to a config file
+  if ($tls_options['port_dnscrypt'] != 0 and !$tls_options['dnscrypt_config_file'])
+  {
+    fail('dnscrypt_config_file must be set when port_dnscrypt is set to a non zero value')
+  }
+  # Perform sanity checks on the certificate values as there are a few combinationss that won't work.
+  if ($tls_options['certificate_chain'] or $tls_options['private_key'])
+  {
+    # AdGuard Home only supports using either hardcoded certs or a path on disk, not both at the same time.
+    if ($tls_options['certificate_path'] or $tls_options['private_key_path'])
+    {
+      fail('cannot use certificate_chain/private_key with certificate_path/private_key_path')
+    }
+    # Seeing as we've confirmed certificate_chain and/or private_key are in use we need to ensure both values are present
+    if (!$tls_options['certificate_chain'] or !$tls_options['private_key'])
+    {
+      fail('both certificate_chain and private_key must be set together')
+    }
+  }
+  else
+  {
+    # We've confirmed that neither certificate_chain or private_key is set so validate we have paths to the certs
+    if (!$tls_options['certificate_path'] or !$tls_options['private_key_path'])
+    {
+      fail('certificate_path and private_key_path required when not providing certificate_chain/private_key')
+    }
+  }
+  # And if we've gotten here then return true
+  Boolean('true')
+}

manifests/init.pp

@@ -130,6 +130,10 @@
 #      - answer: the ip address to point to
 # @param blocked_services
 #   An array of any services you wish to block.
+# @param enable_tls
+#   EXPERIMENTAL: enable TLS. This workflow is largely untested, use with caution.
+# @param tls_options
+#   The TLS configuration options.
 # @param filters
 #   An array of block filters to add. Will default to the standard list provided by AdGuard
 #   Format:
@@ -189,7 +193,7 @@
   Array[Adguard::User] $users,
   Stdlib::IP::Address::V4::Nosubnet $webui_interface = '0.0.0.0',
   Stdlib::Port $webui_port = 80,
-  Optional[Stdlib::HTTPUrl] $http_proxy = undef,
+  Optional[Adguard::Http_proxy] $http_proxy = undef,
   Integer $rlimit_nofile = 0,
   Boolean $debug_pprof = false,
   Integer $web_session_ttl = 8,
@@ -247,6 +251,8 @@
   Integer $cache_time = 30,
   Optional[Array[Adguard::Rewrite]] $rewrites = undef,
   Optional[Array[Adguard::Blocked_service]] $blocked_services = undef,
+  Boolean $enable_tls = false,
+  Optional[Adguard::Tls_options] $tls_options = undef,
   Array[Adguard::Filter] $filters = $adguard::params::filters,
   Optional[Array[Adguard::Filter]] $whitelist_filters = undef,
   Optional[Array] $user_rules = undef,
@@ -270,6 +276,7 @@
 )
 inherits adguard::params
 {
+  # Validate various options that may have been provided
   if ($blocking_mode == 'custom_ip')
   {
     if (!$blocking_ipv4 or !$blocking_ipv6)
@@ -313,6 +320,17 @@
       warning('dhcp_interface and/or dhcp_vX_options set when enable_dhcp is false. DHCP options will have no effect')
     }
   }
+  if ($enable_tls)
+  {
+    if (!$tls_options)
+    {
+      fail('tls_options required when enable_tls is true')
+    }
+    if (adguard::validate_tls_options($tls_options) != true)
+    {
+      fail('failed to validate tls_options')
+    }
+  }
   # Puppet has excellent facts, make use of them
   case $::architecture
   {