Thinbus SRP PHP is an implementation of the SRP-6a Secure Remote Password protocol.
Copyright (c) Simon Massey, 2015-2017
Note High performance PHP servers have a lot of native extensions by default including php-bcmath. If you are compling your own PHP you may find that Thinbus runs very slow. It uses the official Math_BigInteger class which tries to use a native library such as php-bcmath or php-gmp. If that isn't found it does the very large integer math as vanilla PHP which is too slow to be useful for cryptography. To fix this you need to install one or the other of the fast math php extensions.
Note To use PHP compose you need php extensions such as
dom,mbstring,xml,xmlwriter,zip (also don't forget
bcmath for the cryptography math). Those may not be installed on your server by default. You need to install packages such as
php-zip php-xml php-mbstring (also don't foget
php-bcmath for the cryptography math). How you build, install, and enable these is down to how you setup PHP. If you look in
Dockerfile you can see how I installed and set them up on centos7 for php72. You can also look on the
php5.6 branch docker file to see how I installed them and set them up for debian. Please don't ask me questions about your distro/versions as I used stackoverflow to figure all this out and so can you.
Install Dependencies And Run Unit Tests
With php7+ use:
composer update vendor/bin/phpunit --verbose ThinbusTest.php
With php5.6 use:
tar vxf php56.tar wget https://phar.phpunit.de/phpunit-5.7.phar php phpunit-5.7.phar --verbose ThinbusTest.php
There is a demo application that uses this library at https://packagist.org/packages/simon_massey/thinbus-php-srp-demo. That shows that after running
composer update the thinbus php code is stored under the
vendor folder which is where the application loads it from.
Using In Your Application
The core PHP library files are in the
thinbus/thinbus-srp.phpPHP port of the Thinbus Java SRP server code based on code by Ruslan Zavacky.
thinbus/thinbus-srp-common.phpcommon functions used by the client and server.
thinbus/thinbus-srp-client.phpPHP client code contributed by Keith Wagner.
thinbus/rfc5054-safe-prime-config.jsA sample configuration. See the main thinbus documentation for how to create your own safe prime.
thinbus/thinbus-srp6a-sha256-versioned.jsThe thinbus JS library which is tested in the main project. See the header in that file which states the version.
thinbus\thinbus-srp-config.php contains the SRP constants which looks something like:
$SRP6CryptoParams = [ "N_base10" => "19502997308..." "g_base10" => "2", "k_base16" => "1a3d1769e1d..." "H" => "sha256" ];
resource\thinbus\rfc5054-safe-prime-config.js; see the Thinbus documentation.
Consider creating your own large safe prime values using openssl using the Thinbus instructions.
You need to understand that:
- Every users has a password verifier and a unique salt that you store in your database. This implementation uses the RFC2945 approach of hashing the username into the password verifier. This means that if your application lets a user change their username then they will be locked out unless you generate and store a fresh password verifier.
- At every login attempt the browser first makes an AJAX call to get a one-time random challenge and the user salt from the server. The browser then uses that to compute a one-time proof-of-password and then immediately posts the proof-of-password to the server. The server checks the proof-of-password for the one-time challenge using the information stored in the user database. This means the server has to hold the thinbus object that generated the challenge for a short period (either your favourite cache or in your main database).
The following diagram shows what you need to know:
It is expected that you create your own code for loading and saving data to a real database. Do not use my demo application's SQLLite or RedBean code. Only use the PHP files at
thinbus\*.php folder of this repo. It is expected that you use your own code for handling authorisation of which pages users can or cannot access. Trying to modifying the demo files to support your application may be harder than just modifying your current application to simply use the core Thinbus library at
Please read the recommendations in the main thinbus documentation and take additional steps such as using HTTPS and encrypting the password verifier in the database which are not shown in this demo.
Note: With PHP7 the source of random numbers is now the official string random_bytes ( int $length ). With PHP5.2+ Thinbus uses the polyfill library random_compat. Note that PHP5.6 and PHP7.0 are no longer actively supported but do get security patches through 2018. So you really need to upgrade to PHP7.1+ today to have security patches for the next few years. See http://php.net/supported-versions.php
Note that the Math_BigInteger that Thinbus uses to do the crypto math runs very slow (and possibly hangs or possibly gives failing unit tests) unless a native math extension is installed. Usually high performance PHP server installation have a native math exention installed. If you find Thinbus runs slow on your host try installing "bcmath" (or "gmp"). The CI build runs the image created by
Dockerfile which is Centos7 with PHP7.2 with
php-bcmath which provides fast (native) and accurate very large integer maths need to run the SRP crypo math fast. (That images is published on hub.docker.com you can see the details in the bitbucket-pipelines.yaml file.)
If you are having problems first check that the PHP unit code runs locally on your workstation using the exact same version of PHP as you run on your server:
composer update vendor/bin/phpunit --verbose ThinbusTest.php
If all test pass should output a final line such as
OK (xx tests, yyy assertions). If not raise an issue with the verbose output of the phpunit command and the output of
phpinfo(); on your system.
If you find that the code runs slow in a server it is likely that the
pear/math_biginteger library cannot find a native implimentation. It uses the GMP or BCMath extensions, if available, and an internal implementation, otherwise. The fix is to install one of those extensions so that the very large number math is done at native speed rather than scripting speed.
Cross-browser Testing Platform and Open Source <3 Provided by Sauce Labs
Using Sauce Labs the demo app code thinbus-php-srp-demo has been tested to work on:
- Android 6.0
- Android 5.1
- Android 5.0
- Android 4.4
- iOS 11.0
- iOS 8.1
- Microsoft Edge 15
- Microsoft Edge 13
- Microsoft Explorer 11 (note all previous versions were end of life Jan 2016)
- Chrome 63
- Chrome 26
- Firefox 57
- Firefox 4 (released March 22, 2011!)
- Safari 11
- Safari 7
Copyright 2015-2017 Simon Massey Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.