Refactoring library to modernize code base. Fix #16

- Added data types everywhere + strict types
- Drop support for PHP < 8.1
- Renamed "Sasl" to "SASL"
- SASL factroy is now an enum

Author: fabiang

.envrc

@@ -1 +1,3 @@
 export XDEBUG_MODE=coverage
+export EJABBERD_VERSION=24.12
+export DOVECOT_VERSION=2.3.18

.github/workflows/ci.yml

@@ -92,45 +92,6 @@ jobs:
     strategy:
       matrix:
         php:
-        - version: 5.3
-          phpunit: 4.8
-          compat: true
-          coverage: false
-        - version: 5.4
-          phpunit: 4.8
-          compat: true
-          coverage: false
-        - version: 5.5
-          phpunit: 4.8
-          compat: true
-          coverage: false
-        - version: 5.6
-          phpunit: 5.7
-          compat: true
-          coverage: false
-        - version: 7.0
-          phpunit: 6.5
-          compat: true
-          coverage: false
-        - version: 7.1
-          phpunit: 7.5
-          compat: true
-          coverage: false
-        - version: 7.2
-          phpunit: 8.5
-          coverage: false
-        - version: 7.3
-          phpunit: 9.5
-          coverage: false
-        - version: 7.4
-          phpunit: 9.5
-          coverage: false
-        - version: 8.0
-          phpunit: 9.5
-          coverage: false
-        - version: 8.1
-          phpunit: 9.5
-          coverage: false
         - version: 8.2
           phpunit: 10.0
           coverage: true
@@ -185,13 +146,23 @@ jobs:
       run: |
         ./vendor/bin/phpunit \
           --no-configuration \
+          --display-skipped \
+          --display-deprecations \
+          --display-errors \
+          --display-notices \
+          --display-warnings \
           tests/src/
 
     - name: Run test suite with code coverage
       if: ${{ matrix.php.coverage }}
       run: |
         ./vendor/bin/phpunit \
           --no-configuration \
+          --display-skipped \
+          --display-deprecations \
+          --display-errors \
+          --display-notices \
+          --display-warnings \
           --coverage-clover build/logs/clover.xml \
           --coverage-filter src/ \
           tests/src/

.gitignore

@@ -5,7 +5,9 @@ phpunit.xml
 .phpunit.result.cache
 .phpunit.cache/
 .phpcs-cache
+.phpunit.cache/
 *.log
+*.orig
 codeclimate.json
 ocular.phar
 ocular.phar*

.scrutinizer.yml

@@ -25,7 +25,7 @@ tools:
 
 build:
   environment:
-    php: 8.2.0
+    php: 8.3.0
   nodes:
     analysis:
       tests:

LICENSE.md

@@ -3,7 +3,7 @@ Modified BSD License
 
 Copyright (c) 2002-2003 Richard Heyes,
               2014 Jaussoin Timothée,
-              2014-2024 Fabian Grutschus
+              2014-2025 Fabian Grutschus
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without modification,

README.md

@@ -1,6 +1,16 @@
 # fabiang/sasl
 
 The PHP SASL Authentification Library.
+Full refactored version of the the original [Auth_SASL2 Pear package](http://pear.php.net/package/Auth_SASL2/).
+
+Provides code to generate responses to common SASL mechanisms, including:
+
+* Digest-MD5
+* Cram-MD5
+* Plain
+* Anonymous
+* Login (Pseudo mechanism)
+* SCRAM
 
 [![PHP Version Require](https://poser.pugx.org/fabiang/sasl/require/php)](https://packagist.org/packages/fabiang/sasl)
 [![Latest Stable Version](https://poser.pugx.org/fabiang/sasl/v/stable.svg)](https://packagist.org/packages/fabiang/sasl)
@@ -10,22 +20,17 @@ The PHP SASL Authentification Library.
 [![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/fabiang/sasl/badges/quality-score.png?b=develop)](https://scrutinizer-ci.com/g/fabiang/sasl/?branch=develop)
 [![Code Coverage](https://scrutinizer-ci.com/g/fabiang/sasl/badges/coverage.png?b=develop)](https://scrutinizer-ci.com/g/fabiang/sasl/?branch=develop)
 
-Provides code to generate responses to common SASL mechanisms, including:
-* Digest-MD5
-* Cram-MD5
-* Plain
-* Anonymous
-* Login (Pseudo mechanism)
-* SCRAM
+## Security
 
-Full refactored version of the the original [Auth_SASL2 Pear package](http://pear.php.net/package/Auth_SASL2/).
+Please note that MD5- and SHA1-based authentication mechanism are considered insecure.
+Therefore you should prefer at least SCRAM-SHA-256 for **non-secure connections (TLS)** when ever possible.
+For that reason Digest-MD5, Cram-MD5 and SCRAM-SHA-1 are deprecated and were removed in modern server software.
 
 ## Installation
 
-The easiest way to install fabiang/sasl is by using Composer:
+The easiest way to install fabiang/sasl is by using [Composer](https://getcomposer.org):
 
 ```
-curl -sS https://getcomposer.org/installer | php
 composer require fabiang/sasl
 ```
 
@@ -34,24 +39,31 @@ composer require fabiang/sasl
 Use the factory method to create a authentication mechanism object:
 
 ```php
-use Fabiang\Sasl\Sasl;
+use Fabiang\SASL\SASL;
 
-$factory = new Sasl;
-
-$mechanism = $factory->factory('SCRAM-SHA-1', array(
+$mechanism = SASL::SCRAM_SHA3_256->mechanism([
     'authcid'  => 'username',
     'secret'   => 'password',
     'authzid'  => 'authzid', // optional. Username to proxy as
     'service'  => 'servicename', // optional. Name of the service
     'hostname' => 'hostname', // optional. Hostname of the service
-));
+]);
 
 $response = $mechanism->createResponse();
 ```
 
+Or create from string:
+
+```php
+// throws Fabiang\SASL\Exception\UnsupportedMechanismException
+$mechanism = SASL::fromString('SCRAM-SHA3-256')->mechanism([
+    // ...
+]);
+```
+
 Challenge-based authentication mechanisms implement the interface
-`Fabiang\Sasl\Authentication\ChallengeAuthenticationInterface`.
-For those mechanisms call the method again with the challenge:
+`Fabiang\SASL\Authentication\ChallengeAuthenticationInterface`.
+For those mechanisms call the method again with the challenge returned by the server:
 
 ```php
 $response = $mechanism->createResponse($challenge);
@@ -64,7 +76,7 @@ $response = $mechanism->createResponse($challenge);
 To verify the data returned by the server for SCRAM you can call:
 
 ```php
-$mechanism->verify($data);
+$trusted = $mechanism->verify($data);
 ```
 
 If the method returns false you should disconnect.
@@ -74,20 +86,21 @@ If the method returns false you should disconnect.
 To enable [downgrade protection for SCRAM](https://xmpp.org/extensions/xep-0474.html), you'll need to pass
 the allowed authentication mechanisms and channel-binding types via options to the factory:
 
-**Note**: Channel-binding is currently not supported [due to limitations of PHP](https://github.com/php/php-src/issues/16766).
+**Note**: [Channel-binding](https://en.wikipedia.org/wiki/Salted_Challenge_Response_Authentication_Mechanism#Channel_binding)
+is currently not supported [due to limitations of PHP](https://github.com/php/php-src/issues/16766).
 
 ```php
-$mechanism = $factory->factory('SCRAM-SHA-1', array(
+$authentication = AuthenticationMechanism::SCRAM_SHA_1->mechanism([
     'authcid'  => 'username',
     'secret'   => 'password',
     'authzid'  => 'authzid', // optional. Username to proxy as
     'service'  => 'servicename', // optional. Name of the service
     'hostname' => 'hostname', // optional. Hostname of the service
-    'downgrade_protection' => array( // optional. When `null` downgrade protection string from server won't be validated
-        'allowed_mechanisms'       => array('SCRAM-SHA-1-PLUS', 'SCRAM-SHA-1'), // allowed mechanisms by the server
-        'allowed_channel_bindings' => array('tls-unique', 'tls-exporter', 'tls-server-end-point'), // allowed channel-binding types by the server
-    ),
-));
+    'downgrade_protection' => [ // optional. When `null` downgrade protection string from server won't be validated
+        'allowed_mechanisms'       => ['SCRAM-SHA-1-PLUS', 'SCRAM-SHA-1'], // allowed mechanisms by the server
+        'allowed_channel_bindings' => ['tls-unique', 'tls-exporter', 'tls-server-end-point'], // allowed channel-binding types by the server
+    ],
+]);
 ```
 
 ### Required options
@@ -96,15 +109,17 @@ List of options required by authentication mechanisms.
 For mechanisms that are challenge-based you'll need to call `createResponse()`
 again and send the returned value to the server.
 
-| Mechanism  | Authcid | Secret | Authzid  | Service | Hostname | Challenge |
-| ---------- | ------- | ------ | -------- | ------- | -------- | --------- |
-| Anonymous  | yes     | no     | no       | no      | no       | no        |
-| Cram-MD5   | yes     | yes    | no       | no      | no       | yes       |
-| Digest-MD5 | yes     | yes    | optional | yes     | yes      | yes       |
-| External   | no      | no     | yes      | no      | no       | no        |
-| Login      | yes     | yes    | no       | no      | no       | no        |
-| Plain      | yes     | yes    | optional | no      | no       | no        |
-| SCRAM-*    | yes     | yes    | optional | no      | no       | yes       |
+| Mechanism  | Authcid  | Secret | Authzid  | Service | Hostname |     | Challenge |
+| ---------- | -------- | ------ | -------- | ------- | -------- | --- | --------- |
+| Anonymous  | optional | no     | no       | no      | no       |     | no        |
+| Cram-MD5   | yes      | yes    | no       | no      | no       |     | yes       |
+| Digest-MD5 | yes      | yes    | optional | yes     | yes      |     | yes       |
+| External   | no       | no     | optional | no      | no       |     | no        |
+| Login      | yes      | yes    | no       | no      | no       |     | no        |
+| Plain      | yes      | yes    | optional | no      | no       |     | no        |
+| SCRAM-*    | yes      | yes    | optional | no      | no       |     | yes       |
+
+Authcid = e.g. username, Secret = e.g. password
 
 ## Unit tests
 

behat.yml

@@ -3,7 +3,7 @@ default:
     authentication_features:
       paths: [ "%paths.base%/tests/features/" ]
       contexts:
-        - Fabiang\Sasl\Behat\XMPPContext:
+        - Fabiang\SASL\Behat\XMPPContext:
           - localhost
           - 15222
           # Extra test server for https://dyn.eightysoft.de/xeps/xep-0474.html
@@ -13,7 +13,7 @@ default:
           - testpass
           - "%paths.base%/tests/log/features/"
           - tlsv1.2
-        - Fabiang\Sasl\Behat\POP3Context:
+        - Fabiang\SASL\Behat\POP3Context:
           - localhost
           - 1110
           - vmail

composer.json

@@ -25,26 +25,28 @@
     ],
     "autoload": {
         "psr-4": {
-            "Fabiang\\Sasl\\": "src/"
+            "Fabiang\\SASL\\": "src/"
         },
-        "files": ["src/throwable.php"]
+        "files": [
+            "src/deprecated.php",
+            "src/override.php"
+        ]
     },
     "autoload-dev": {
         "psr-4": {
-            "Fabiang\\Sasl\\Behat\\": "tests/features/bootstrap",
-            "Fabiang\\Sasl\\": "tests/src"
-        },
-        "files": ["tests/compat.php"]
+            "Fabiang\\SASL\\Behat\\": "tests/features/bootstrap",
+            "Fabiang\\SASL\\": "tests/src"
+        }
     },
     "require": {
-        "php": "^5.3.3 || ^7.0 || ~8.0.0 || ~8.1.0 || ~8.2.0 || ~8.3.0 || ~8.4.0"
+        "php": "~8.2.0 || ~8.3.0 || ~8.4.0"
     },
     "require-dev": {
-        "behat/behat": "^3.6",
-        "phpunit/phpunit": ">=4.8",
+        "behat/behat": "^3.18",
+        "phpunit/phpunit": "^10.0 || ^11.5",
         "slevomat/coding-standard": "*",
         "squizlabs/php_codesniffer": "*",
-        "vimeo/psalm": "^5.23"
+        "vimeo/psalm": "^6.0"
     },
     "config": {
         "sort-packages": true,
@@ -55,7 +57,7 @@
     "scripts": {
         "phpcs": "phpcs",
         "psalm": "psalm",
-        "phpunit": "phpunit",
+        "phpunit": "phpunit --display-phpunit-deprecations --display-skipped --display-deprecations --display-errors --display-notices --display-warnings",
         "behat": "behat",
         "test": [
             "@psalm",

docker-compose.yml

@@ -1,7 +1,6 @@
-version: '3'
 services:
   xmpp:
-    image: ejabberd/ecs:${EJABBERD_VERSION:-24.02}
+    image: ejabberd/ecs:${EJABBERD_VERSION:-24.12}
     volumes:
       - "./tests/config/ejabberd/ejabberd.yml:/home/ejabberd/conf/ejabberd.yml"
       - "./tests/config/ejabberd/ejabberd.db:/home/ejabberd/database/ejabberd.db"
@@ -27,7 +26,7 @@ services:
       - CTL_ON_CREATE=register testuser localhost testpass
 
   mail:
-    image: dovecot/dovecot:2.3.18
+    image: dovecot/dovecot:${DOVECOT_VERSION:-2.3.18}
     volumes:
       - "./tests/config/dovecot/dovecot.conf:/etc/dovecot/dovecot.conf"
       - "./tests/config/dovecot/users:/etc/dovecot/users"