fabiang/sasl

Abstraction of various SASL mechanism responses.

fabiang/sasl

The PHP SASL Authentification Library. Full refactored version of the the original Auth_SASL2 Pear package., _(*1)

Provides code to generate responses to common SASL mechanisms, including:, _(*2)

• Digest-MD5
• Cram-MD5
• Plain
• Anonymous
• Login (Pseudo mechanism)
• SCRAM

, _(*3)

Security

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., _(*4)

Installation

The easiest way to install fabiang/sasl is by using Composer:, _(*5)

composer require fabiang/sasl

Usage

Use the factory method to create a authentication mechanism object:, _(*6)

use Fabiang\SASL\SASL;

$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:, _(*7)

// 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 returned by the server:, _(*8)

$response = $mechanism->createResponse($challenge);

Note: The challenge must be Base64 decoded., _(*9)

SCRAM verification

To verify the data returned by the server for SCRAM you can call:, _(*10)

$trusted = $mechanism->verify($data);

If the method returns false you should disconnect., _(*11)

SCRAM downgrade protection

To enable downgrade protection for SCRAM, you'll need to pass the allowed authentication mechanisms and channel-binding types via options to the factory:, _(*12)

Note: Channel-binding is currently not supported due to limitations of PHP., _(*13)

$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' => [ // 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

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., _(*14)

Authcid = e.g. username, Secret = e.g. password, _(*15)

Unit tests

If you like this library and you want to contribute, make sure the unit tests and integration tests are running., _(*16)

Run the unit tests:, _(*17)

./vendor/bin/phpunit

Integration tests

The integration tests verify the authentication methods against an Ejabberd and Dovecot server., _(*18)

To launch the servers you can use the provided Docker Compose file. Just install Docker and run:, _(*19)

docker compose up -d

Note: ejabberd takes up to twenty minutes to start., _(*20)

Now you can run the integration tests:, _(*21)

./vendor/bin/behat

License

BSD-3-Clause. See the LICENSE.md., _(*22)