TypeScript SRP (Secure Remote Password) [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

npm i @windwalker-io/srp --save

# OR

yarn add @windwalker-io/srp

See the PHP package documentation here.

Requirement

Thi package uses ES2020 BigInt and bundle as ES2020 code. You must make sure your browser environment supports this.

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.

import { SRPServer, DEFAULT_PRIME, DEFAULT_GENERATOR, DEFAULT_KEY } from '@windwalker-io/srp';

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

these value can be ES2020 BigInt format.

import { SRPServer, DEFAULT_PRIME, DEFAULT_GENERATOR, DEFAULT_KEY } from '@windwalker-io/srp';

const server = new SRPServer(
    BigInt('my prime'),
    BigInt('my generator'),
    BigInt(`0x${'my key'}`)
);

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

import { SRPServer, SRPClient } from '@windwalker-io/srp';

const server = SRPServer.create();
const client = SRPClient.create();

There has some more configure options:

// 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');

// Web has no native blake2b, you must use custom callback to hash.
// Set custom hash logic
server.setHaser(async (buffer) => ...);


// Disable padding
server.enablePad(false);

About the custom hasher callback, the input and return value is must be Uint8Array, you must convert it by your-self.

server.setHaser(async (buffer: Uint8Array) => {
  return await someHashFunc(buffer);
});

server.setHaser(async (buffer: Uint8Array) => {
  return str2uint8(await someHashFuncOnlyReturnString(buffer));
});

If you want to operate the values your-self, consider install a bigint operation library like bigint-toolkit.

Sample Code

Here we use both JS server and client to run a sample SRP flow. You can replace the server part as PHP or other backend packages. All values generated by SRP package is a bigint value, you can convert it to hex by v.toString(16) for storing to DB or transfer by HTTP request.

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

const server = SRPServer.create();
const client = SRPClient.create();

// Register
const identity = '...';
const password = '...';

// Register: generate new salt & verifier
const { salt, verifier } = await client.register(identity, password);

// Use toString(16) convert to hex string
salt.toString(16);
verifier.toString(16);

// Send to Server store

// Login start
// AJAX:challenge?{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.
const { secret: b, public: B } = await server.step1(identity, salt, verifier);

// Server returns B & salt to client

// Client step (1) & (2)
const { secret: a, public: A, hash: x } = await client.step1(identity, password, salt);
const { key: K, proof: M1 } = await client.step2(identity, salt, A, a, B, x);

// 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.
const { proof: M2 } = await server.step2(identity, salt, verifier, A, b, B, M1);

// Server returns M2 to Client
// Client step (3) (optional)
await 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

| Variable | Name | Send | Calc | |-----------------|---------------------------------------------------------------------|------|------------------------------------------------| | I, identity | The main identity (username or email). | C=>S | | | N | A large safe prime, All arithmetic is done modulo N. | X | | | g | A generator modulo N | X | | | k | Multiplier parameter | X | SHA1(N \| PAD(g)) | | s | The user salt. | C<=S | random() | | v | Password Verifier | X | g^x % N | | x | The hash of salt + identity + password. | X | SHA1(s \| SHA1(I \| ":" \| P)) | | a, b | Client & server secret key | X | random() | | A | Client public key | C=>S | g^a % N | | B | Server public key | C<=S | k*v + g^b % N | | u | The value to prevent attacker who learns a user's verifier | X | H(PAD(A) \| PAD(B)) | | S (client) | Pre master secret (The secure common session key) | X | (B - (k * g^x)) ^ (a + (u * x)) % N | | S (server) | Pre master secret (The secure common session key) | X | (A * v^u) ^ b % N | | K | The session key hash for used to generate M | X | H(S) | | M1 | Evidence message 1, To verify both side generated same session key. | C=>S | H(H(N) XOR H(g) \| H(U) \| s \| A \| B \| K) | | M2 | Evidence message 2, To verify both side generated same session key. | C<=S | H(A \| M \| K) |

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 [email protected] (Simon).