test(unit): Add unit test for TLS auth

Author: julienloizelet

.github/workflows/test-suite.yml

@@ -103,6 +103,10 @@ jobs:
         run: |
           ddev exec BOUNCER_KEY=${{ env.BOUNCER_KEY }} AGENT_TLS_PATH=/var/www/html/cfssl USE_CURL=1 LAPI_URL=https://crowdsec:8080 MEMCACHED_DSN=memcached://memcached:11211 REDIS_DSN=redis://redis:6379 /usr/bin/php ./${{env.EXTENSION_PATH}}/vendor/bin/phpunit --testdox --colors --exclude-group ignore ./${{env.EXTENSION_PATH}}/tests/Integration/IpVerificationTest.php
 
+      - name: Run "IP verification with TLS" test
+        run: |
+          ddev exec AGENT_TLS_PATH=/var/www/html/cfssl BOUNCER_TLS_PATH=/var/www/html/cfssl LAPI_URL=https://crowdsec:8080 MEMCACHED_DSN=memcached://memcached:11211 REDIS_DSN=redis://redis:6379 /usr/bin/php ./${{env.EXTENSION_PATH}}/vendor/bin/phpunit --testdox --colors --exclude-group ignore ./${{env.EXTENSION_PATH}}/tests/Integration/IpVerificationTest.php    
+
       - name: Run "Geolocation with file_get_contents" test
         run: |
           ddev exec BOUNCER_KEY=${{ env.BOUNCER_KEY }} AGENT_TLS_PATH=/var/www/html/cfssl LAPI_URL=https://crowdsec:8080  /usr/bin/php ./${{env.EXTENSION_PATH}}/vendor/bin/phpunit --testdox --colors --exclude-group ignore ./${{env.EXTENSION_PATH}}/tests/Integration/GeolocationTest.php

docs/DEVELOPER.md

@@ -234,9 +234,16 @@ ddev exec BOUNCER_KEY=your-bouncer-key AGENT_TLS_PATH=/var/www/html/cfssl LAPI_U
 /usr/bin/php ./my-own-modules/crowdsec-php-lib/vendor/bin/phpunit --testdox --colors --exclude-group ignore ./my-own-modules/crowdsec-php-lib/tests/Integration/GeolocationTest.php
 ```
 
-N.B: If you want to test with `curl` instead of `file_get_contents` calls to LAPI, you have to add `USE_CURL=1` in 
+**N.B**: If you want to test with `curl` instead of `file_get_contents` calls to LAPI, you have to add `USE_CURL=1` in 
 the previous commands.
 
+**N.B**: If you want to test with `tls` authentification, you have to add `BOUNCER_TLS_PATH` environment varibale 
+and specify the path where you store certificates and keys. For example:
+
+```bash
+ddev exec USE_CURL=1 AGENT_TLS_PATH=/var/www/html/cfssl  BOUNCER_TLS_PATH=/var/www/html/cfssl LAPI_URL=https://crowdsec:8080 MEMCACHED_DSN=memcached://memcached:11211 REDIS_DSN=redis://redis:6379 /usr/bin/php ./my-own-modules/crowdsec-php-lib/vendor/bin/phpunit --testdox --colors --exclude-group ignore ./my-own-modules/crowdsec-php-lib/tests/Integration/IpVerificationTest.php
+```
+
 
 #### Auto-prepend mode (standalone mode)
 

docs/USER_GUIDE.md

@@ -119,82 +119,136 @@ Here is the list of available settings:
 
 ##### LAPI Connection
 
-- `api_key`: Key generated by the cscli (CrowdSec cli) command like `cscli bouncers add bouncer-php-library`
+- `auth_type`: Select from `api_key` and `tls`. Choose if you want to use an API-KEY or a TLS (pki) authentification.
+  TLS authentication is only available if you use CrowdSec agent with a version superior to 1.4.0.
+
+
+- `api_key`: Key generated by the cscli (CrowdSec cli) command like `cscli bouncers add bouncer-php-library`.
+  Only required if you choose `api_key` as `auth_type`.
+
+
+- `tls_cert_path`: absolute path to the bouncer certificate (e.g. pem file).
+  Only required if you choose `tls` as `auth_type`.
+
+
+- `tls_key_path`: Absolute path to the bouncer key (e.g. pem file).
+  Only required if you choose `tls` as `auth_type`.
+
+
+- `tls_verify_peer`: This option determines whether request handler verifies the authenticity of the peer's certificate.
+  Only required if you choose `tls` as `auth_type`. 
+  When negotiating a TLS or SSL connection, the server sends a certificate indicating its identity.
+  If `tls_verify_peer` is set to true, request handler verifies whether the certificate is authentic.
+  This trust is based on a chain of digital signatures,
+  rooted in certification authority (CA) certificates you supply using the `tls_ca_cert_path` setting below.
+
+
+- `tls_ca_cert_path`: Absolute path to the CA used to process peer verification.
+  Only required if you choose `tls` as `auth_type` and `tls_verify_peer` is set to true.
+
 
 - `api_url`: Define the URL to your LAPI server, default to `http://localhost:8080`.
 
+
 - `api_timeout`: In seconds. The timeout when calling LAPI. Must be greater or equal than 1. Default to 1 sec.
 
+
 - `use_curl`: By default, this lib call the REST LAPI using `file_get_contents` method (`allow_url_fopen` is required).
   You can set `use_curl` to `true` in order to use `cURL` request instead (`curl` is in then required)
 
+
 ##### Debug
 - `debug_mode`: `true` to enable verbose debug log. Default to `false`.
 
+
 - `disable_prod_log`: `true` to disable prod log. Default to `false`.
 
-- `log_directory_path`: Absolute path to store log files. Important note: be sur this path won't be publicly accessible
+
+- `log_directory_path`: Absolute path to store log files. Important note: be sur this path won't be publicly 
+  accessible.
+
 
 - `display_errors`: true to stop the process and display errors on browser if any.
 
+
 - `forced_test_ip`: Only for test or debug purpose. Default to empty. If not empty, it will be used instead of the 
   real remote ip.
 
+
 - `forced_test_forwarded_ip`: Only for test or debug purpose. Default to empty. If not empty, it will be used 
   instead of the real forwarded ip. If set to `no_forward`, the x-forwarded-for mechanism will not be used at all.
 
 ##### Bouncer behavior
 
 - `bouncing_level`:  Select from `bouncing_disabled`, `normal_bouncing` or `flex_bouncing`. Choose if you want to apply CrowdSec directives (Normal bouncing) or be more permissive (Flex bouncing). With the `Flex mode`, it is impossible to accidentally block access to your site to people who don’t deserve it. This mode makes it possible to never ban an IP but only to offer a Captcha, in the worst-case scenario.
 
+
 - `fallback_remediation`: Select from `bypass` (minimum remediation), `captcha` or `ban` (maximum remediation). Default to 'captcha'. Handle unknown remediations as.
 
+
 - `max_remediation_level`: Select from `bypass`,`captcha` or `ban`. Default to 'ban'. Cap the 
   remediation to the selected one.
 
+
 - `trust_ip_forward_array`:  If you use a CDN, a reverse proxy or a load balancer, set an array of IPs. For other IPs, the bouncer will not trust the X-Forwarded-For header.
 
-- `excluded_uris`: array of URIs that will not be bounced
+
+- `excluded_uris`: array of URIs that will not be bounced.
 
 ##### Cache
 
 - `cache_system`: Select from `phpfs` (File system cache), `redis` or `memcached`.
 
+
 - `fs_cache_path`: Will be used only if you choose File system as cache_system. Important note: be sur this path 
   won't be publicly accessible.
 
-- `redis_dsn`:   Will be used only if you choose Redis cache as cache_system
 
-- `memcached_dsn`: Will be used only if you choose Memcached as cache_system
+- `redis_dsn`:   Will be used only if you choose Redis cache as cache_system.
+
+
+- `memcached_dsn`: Will be used only if you choose Memcached as cache_system.
+
 
 - `clean_ip_cache_duration`: Set the duration we keep in cache the fact that an IP is clean. In seconds. Defaults to 5.
 
+
 - `bad_ip_cache_duration`: Set the duration we keep in cache the fact that an IP is bad. In seconds. Defaults to 20.
 
+
 - `captcha_cache_duration`: Set the duration we keep in cache the captcha flow variables for an IP. In seconds. 
   Defaults to 86400.. In seconds. Defaults to 20.
 
+
 - `geolocation_cache_duration`: Set the duration we keep in cache a geolocation result for an IP . In seconds. 
   Defaults to 86400. Depends on the below `geolocation[save_result]` configuration.
 
+
 - `stream_mode`: true to enable stream mode, false to enable the live mode. Default to false. By default, the `live mode` is enabled. The first time a stranger connects to your website, this mode means that the IP will be checked directly by the CrowdSec API. The rest of your user’s browsing will be even more transparent thanks to the fully customizable cache system. But you can also activate the `stream mode`. This mode allows you to constantly feed the bouncer with the malicious IP list via a background task (CRON), making it to be even faster when checking the IP of your visitors. Besides, if your site has a lot of unique visitors at the same time, this will not influence the traffic to the API of your CrowdSec instance.
 
 ##### Geolocation
 
 - `geolocation`: Settings for geolocation remediation (i.e. country based remediation).
+
 - `geolocation[enabled]`: true to enable remediation based on country. Default to false.
-- `geolocation[type]`:  Geolocation system. Only 'maxmind' is available for the moment. Default to `maxmind`
+
+- `geolocation[type]`:  Geolocation system. Only 'maxmind' is available for the moment. Default to `maxmind`.
+
 
 - `geolocation[save_result]`: true to store the geolocalized country in cache. Default to true. Setting true 
-  will avoid multiple call to the geolocalized system (e.g. maxmind database)
-- `geolocation[maxmind]`: MaxMind settings
+  will avoid multiple call to the geolocalized system (e.g. maxmind database).
+
+- `geolocation[maxmind]`: MaxMind settings.
+
 - `geolocation[maxmind][database_type]`: Select from `country` or `city`. Default to `country`. These are the two available MaxMind database types.
-- `geolocation[maxmind][database_path]`: Absolute path to the MaxMind database (mmdb 
+
+- `geolocation[maxmind][database_path]`: Absolute path to the MaxMind database (e.g. mmdb file)
 
 
 ##### Captcha and ban wall settings
 
 - `hide_mentions`: true to hide CrowdSec mentions on ban and captcha walls.
+
 - Wording and css settings: 
 
   `theme_color_text_primary`

scripts/auto-prepend/settings.example.php

@@ -21,14 +21,14 @@
      *
      * Only required if you choose tls as "auth_type"
      */
-    'tls_bouncer_key' => '',
+    'tls_key_path' => '',
 
     /** This option determines whether request handler verifies the authenticity of the peer's certificate.
      *
      * When negotiating a TLS or SSL connection, the server sends a certificate indicating its identity.
      * If "tls_verify_peer" is set to true, request handler verifies whether the certificate is authentic.
      * This trust is based on a chain of digital signatures,
-     * rooted in certification authority (CA) certificates you supply using the "tls_ca_cert" setting below.
+     * rooted in certification authority (CA) certificates you supply using the "tls_ca_cert_path" setting below.
      *
      */
     'tls_verify_peer' => true,
@@ -37,7 +37,7 @@
      *
      * Only required if you choose tls as "auth_type" and "tls_verify_peer" is true
      */
-    'tls_ca_cert' => '',
+    'tls_ca_cert_path' => '',
 
     /** The bouncer api key to access LAPI.
      *

tests/Integration/IpVerificationTest.php

@@ -20,10 +20,14 @@ final class IpVerificationTest extends TestCase
     /** @var bool  */
     private $useCurl;
 
+    /** @var bool  */
+    private $useTls;
+
     protected function setUp(): void
     {
         $this->logger = TestHelpers::createLogger();
         $this->useCurl = (bool) getenv('USE_CURL');
+        $this->useTls = (string) getenv('BOUNCER_TLS_PATH');
         $this->watcherClient = new WatcherClient(['use_curl' => $this->useCurl], $this->logger);
     }
 
@@ -43,6 +47,7 @@ public function testCanVerifyIpInLiveModeWithCacheSystem($cacheAdapterName, $ori
 
         // Init bouncer
         $bouncerConfigs = [
+            'auth_type' => $this->useTls ? Constants::AUTH_TLS : Constants::AUTH_KEY,
             'api_key' => TestHelpers::getBouncerKey(),
             'api_url' => TestHelpers::getLapiUrl(),
             'use_curl' => $this->useCurl,
@@ -52,6 +57,13 @@ public function testCanVerifyIpInLiveModeWithCacheSystem($cacheAdapterName, $ori
             'memcached_dsn' =>  getenv('MEMCACHED_DSN'),
             'fs_cache_path' => TestHelpers::PHP_FILES_CACHE_ADAPTER_DIR
         ];
+        if($this->useTls){
+            $bouncerConfigs['tls_cert_path'] = $this->useTls . '/bouncer.pem';
+            $bouncerConfigs['tls_key_path'] = $this->useTls . '/bouncer-key.pem';
+            $bouncerConfigs['tls_ca_cert_path'] = $this->useTls . '/ca-chain.pem';
+            $bouncerConfigs['tls_verify_peer'] = true;
+
+        }
 
         $bouncer = new Bouncer($bouncerConfigs, $this->logger);
 
@@ -154,6 +166,7 @@ public function testCanVerifyIpInStreamModeWithCacheSystem($cacheAdapterName, $o
         $this->watcherClient->setInitialState();
         // Init bouncer
         $bouncerConfigs = [
+            'auth_type' => $this->useTls ? Constants::AUTH_TLS : Constants::AUTH_KEY,
             'api_key' => TestHelpers::getBouncerKey(),
             'api_url' => TestHelpers::getLapiUrl(),
             'api_user_agent' => TestHelpers::UNIT_TEST_AGENT_PREFIX . '/' . Constants::BASE_USER_AGENT,
@@ -164,6 +177,12 @@ public function testCanVerifyIpInStreamModeWithCacheSystem($cacheAdapterName, $o
             'memcached_dsn' =>  getenv('MEMCACHED_DSN'),
             'fs_cache_path' => TestHelpers::PHP_FILES_CACHE_ADAPTER_DIR
         ];
+        if($this->useTls){
+            $bouncerConfigs['tls_cert_path'] = $this->useTls . '/bouncer.pem';
+            $bouncerConfigs['tls_key_path'] = $this->useTls . '/bouncer-key.pem';
+            $bouncerConfigs['tls_ca_cert_path'] = $this->useTls . '/ca-chain.pem';
+            $bouncerConfigs['tls_verify_peer'] = true;
+        }
 
         $bouncer = new Bouncer($bouncerConfigs, $this->logger);
         // Test cache adapter
@@ -251,8 +270,9 @@ public function testCanVerifyIpInStreamModeWithCacheSystem($cacheAdapterName, $o
             'The old decisions should now be removed, so the previously bad IP should now be clean'
         );
 
-        // Setup an new instance.
+        // Set up a new instance.
         $bouncerConfigs = [
+            'auth_type' => $this->useTls ? Constants::AUTH_TLS : Constants::AUTH_KEY,
             'api_key' => TestHelpers::getBouncerKey(),
             'api_url' => TestHelpers::getLapiUrl(),
             'stream_mode' => true,
@@ -263,6 +283,13 @@ public function testCanVerifyIpInStreamModeWithCacheSystem($cacheAdapterName, $o
             'memcached_dsn' =>  getenv('MEMCACHED_DSN'),
             'fs_cache_path' => TestHelpers::PHP_FILES_CACHE_ADAPTER_DIR
         ];
+        if($this->useTls){
+            $bouncerConfigs['tls_cert_path'] = $this->useTls . '/bouncer.pem';
+            $bouncerConfigs['tls_key_path'] = $this->useTls . '/bouncer-key.pem';
+            $bouncerConfigs['tls_ca_cert_path'] = $this->useTls . '/ca-chain.pem';
+            $bouncerConfigs['tls_verify_peer'] = true;
+
+        }
 
         $bouncer = new Bouncer($bouncerConfigs, $this->logger);