windwalker/srp

A modern PHP/JS package of SRP-6a (RFC5054). Contains server and client part to help developer use on any cases.

1.0.1 2023-11-19 07:30 UTC

Requires

• php: >=8.1
• brick/math: ^0.11.0

Requires (Dev)

• phpunit/phpunit: ^10.0
• windwalker/utilities: ^4.0

MIT

• Simon Asika

• security
• password
• Passwordless
• SRP

README

SRP Package (PHP)

Windwalker SRP Package PHP | JS

This is a modern PHP/JS package which provides an implementation of SRP-6a (RFC5054). The PHP / JS side both have server and client part to help developer use on any cases.

This package passed the srptools Test Vectors, it means that this package is fully implement the RFC5054 spec, and you can use this package to work with any other packages which is also fully adheres the RFC spec. The main difference is that this package will pad value to fit the length of g (prime) value before hash, however, most of the SRP packages will probably not pad them before hashing.

We also provide a way to disable the padding behavior if you want to use this package with another package that does not pad values before hashing.

Installation

PHP

composer require windwalker/srp

JS

npm i @windwalker-io/srp --save

# OR

yarn add @windwalker-io/srp

See the JS package documentation here.

Getting Started

You must prepare a large safe prime, a generator and a key, the prime and generator is base 10, and the key is hex (base16) format. This package also provides a default safe prime, you can directly use it.

use Windwalker\SRP\SRPServer;
use Windwalker\SRP\SRPClient;

$server = new SRPServer(
    SRPServer::DEFAULT_PRIME, // 217661744586174357731910088918027537819...
    SRPServer::DEFAULT_GENERATOR, // 02
    SRPServer::DEFAULT_KEY, // 5b9e8ef059c6b32ea59fc1d322d37f04aa30bae5aa9003b8321e21ddb04e300
);

these value can be BigInteger format, we use brick/math as the BigInteger library.

use Brick\Math\BigInteger;
use Windwalker\SRP\SRPServer;
use Windwalker\SRP\SRPClient;

$server = new SRPServer(
    BigInteger::of(SRPServer::DEFAULT_PRIME),
    BigInteger::of(SRPServer::DEFAULT_GENERATOR),
    BigInteger::fromBase(SRPServer::DEFAULT_KEY, 16),
);

Use createFromConfig() if you set the config in an array.

use Windwalker\SRP\SRPServer;

$config = [
    'prime' => SRPServer::DEFAULT_PRIME, // 217661744586174357731910088918027537819...
    'generator' => SRPServer::DEFAULT_GENERATOR, // 02
    'key' => SRPServer::DEFAULT_KEY, // 5b9e8ef059c6b32ea59fc1d322d37f04aa30bae5aa9003b8321e21ddb04e300
];

Use create() to ignore all parameters, this package will use the prepared default secure config.

use Windwalker\SRP\SRPServer;
use Windwalker\SRP\SRPClient;

$server = SRPServer::create();
$client = SRPClient::create();

There has some more configure options:

use Windwalker\SRP\SRPServer;

// Set the secret size
$server->setSize(512); // Default is 256
// Same as
$server->setLength(64);


// Set Hash algo,  default is `sha256`
$server->setHaser('sha1');
$server->setHaser('sha256');
$server->setHaser('sha384');
$server->setHaser('sha512');

// Blake2b will use sodium ext to hash it.
$server->setHaser('blake2b-256');
$server->setHaser('blake2b-224');
$server->setHaser('blake2b-384');
$server->setHaser('blake2b-512');

// Set custom hash logic
$server->setHaser(fn(string $str) => ...);


// Disable padding
$server->enablePad(false);

Sample Code

Here we use both PHP server and client to run a sample SRP flow. You can replace the client part as JS. All values generated by SRP package is a BigInteger object, you can convert it to hex by $v->toBase(16) for storing to DB or transfer by HTTP request.

The full description of this flow is under the next chapter.

use Windwalker\SRP\SRPServer;
use Windwalker\SRP\SRPClient;

$server = SRPServer::create();
$client = SRPClient::create();

// Register page: User input identify and password.
$identity = '...';
$password = '...';

// Register: generate new salt & verifier
$pf = $client->register($identity, $password);
$salt = $pf->salt; // BigInteger object
$verifier = $pf->verifier; // BigInteger object

// Use toBase(16) convert to hex string
$salt->toBase(16);
$verifier->toBase(16);

// Send to Server store

// Login start
// AJAX:hello?{identity} - Server step (1)
// salt & verifier has already stored on user data, server can get it from DB
// b & B must remember on session, we will use it at following steps.
$r = $server->step1($identity, $salt, $verifier);
$b = $r->secret; // BigInteger object
$B = $r->public; // BigInteger object

// Server hello: returns B & salt to client

// Client step (1) & (2)
$pr = $client->step1($identity, $password, $salt);
$a = $pr->secret;
$A = $pr->public;
$x = $pr->hash;

$pr = $client->step2($identity, $salt, $A, $a, $B, $x);
$K = $pr->key;
$M1 = $pr->proof;

// AJAX:authenticate?{identity,A,M1} - Server step (2)
// Send identity & A & M1 to server and compare it.
// The salt & verifier stored on user data, get it from DB.
// The b, B stored in session state, get and clear them.
$pr = $server->step2($identity, $salt, $verifier, $A, $B, $b, $M1);
$M2 = $pr->proof;

// Server returns M2 to Client
// Client step (3) (optional)
$client->step3($A, $K, $M1, $M2);

// If all passed, should not throw any exceptions.

The SRP Flow

The definitions and processes of SRP-6a are dispersed in RFC 2945 and RFC 5054; this is an attempt to integrate them for an overview. Please follow strictly to the RFC-specified procedures without custom modification, and do not transmit any variables unnecessarily to avoid security breaches.

Definition

Registration

When an app (web/mobile) start registration flow, it may display a identity (I) (username or email) and password (P) field to user. They entered their username and password, then click the register button. The SRP client will generate a random salt (s), and a password verifier (v) which is generated from salt, identity and password.

Then app will send only the salt, verifier and identity to server and do not send password. It is a protocol violation and security bug if the raw password is accidently transmitted to the server even if it is ignored by the server.

You can save the user info and salt, verifier to DB when server receive the registration request. It is optional if you want to encrypt the salt and verifier before saving, make sure you encrypt it by a key which is only known by server.

Login

Hello and Server step1

When a user start login process, they may enter their identity and password on form fields, and click the login button. The SRP client will send a Hello request with identity to server. Server should check user exists by this identity, and get salt and verifier from user data. Next, server will generate a random private b and a public B, and remember them by DB, session or cache storage that we will need them in the further steps, then, return the salt, B back to client (Server Hello). This process is similar to a handshake, to create a connecting session for both side.

Some package calls client Hello as challenge action, and the B is server challenge value.

Client step 1 & 2

After receiving the B and salt, Client runs step 1 to generate a and A, and then , runs step2 to use all of the above values to generate a client proof M1. It will be sent to server with A (authenticate action). Server side also use all the generated values to generate a M1 and compare it. If compare failure, server will report an error, and if compare success, server will generate a server proof M2 and back to client. To this step, the authenticate actions is done, you can simply redirect user to login success page.

There is an optional Client step3 is that you can verify the M2 to authority server is trusted and make sure both side generate a same session key (S). If you done this step3, it means you complete the authenticate handshake and did a two-way authentication. If you want to run the step3 to complete all the process, you can redirect user after step3 done.

About the S and M

When client and server generating M, they will both generate a premaster secret (S). The S should be same, even if the 2 sides did not send S to another. The M1 and M2 is a verifier to make sure both side have a same S. So, S can be a trusted session key or encryption key if you want to do some other cryptography behavior in the future.

Some Important Notes

• You don't need to use AJAX to implement SRP flow. You can simply use form post to do all the steps. For example, you may separate username and password into 2 steps on your website, and store values in hidden inputs. Make sure you stored a and b in your browser and server cache that can use them cross steps and do not accendently send them to remote side.
• The verifier is generated from identity and password, which means you must re-create a new verifier to replace old one if user changes either of identity or password.
• Always make sure you don't send any unnecessary values to each side, even if server or client ignore them, it is considered as a protocol violation and security bug. Also, the MITM attacker is able to use these sensitive data.
• Always clear values when restart an authenticate process. Generally, you can reload page so that all values and JS object will be reset. If you are developing a SPA app, wrap whole process in a function and do not cache values to object properties, and create a new client JS object every time.
• SRP should not replace HTTPS, you should always use SSL/TLS on your app and enable the Cookies HttpOnly and secure settings.

Contribution

If you want to report bug, simply open an issue. Any PR is welcome and can speed up the fixing process.

If you have a security issue, please send to [e-mail] (Simon).