Download the PHP package filiprigoir/pswkey without Composer

��# PswKey-php

The conversion layer operates on derived shuffled alphabets.

## How to install

`bash

composer require filiprigoir/pswkey

`

---

## Core idea

Alphabet layouts are automatically derived from a seedphrase (salt) and optional keyphrase (pepper), creating isolated conversion spaces between systems, services and/or users.

This affects compatibility between instances, since alphabet layouts differ per setup.

All inputs are validated before decoding against their base alphabet. If this validation fails, decoding could be rejected by:

- early validation (quick check)

- deep validation (during the process)

For BaseX to Base10, Base100 and Base256 conversions, decoding additionally requires extra normalization into the canonical format.

In these cases, decoding follows a deterministic rejection model:

- invalid symbols are rejected

- incompatible alphabets are rejected

- decoding does not produce valid canonical output when the setup does not match

�! See: [Normalization](/src/Core/Documentation/Pipline/Normalization.md)

---

## Design philosophy

The repository separates:

- key derivation

- stream management

- data normalization before conversion

- transport representation

into independent layers that can be combined when needed.

---

This repository consists of three integrated components:

- KeyStream()  standalone stream and derived key provider

- PswKey()  deterministic base conversion driven by KeyStream()

- OneTimePad()  XOR and digit-based OTP for intermediate steps powered by KeyStream()

Components:

### KeyStream()

Handles stream and derived key generation.

Keys are exposed through callbacks only and are cleared as quickly as possible after use.

Built on Libsodium and intended for encryption-related workflows.

### PswKey()

Provides deterministic base conversion using shuffled alphabets driven by KeyStream().

Supports:

- system-defined alphabets (always shuffled)

- custom-defined alphabets (with optional alphabet shuffling)

PswKey() uses KeyStream() through dependency injection and is intended for deterministic transport representation, not encryption.

### OneTimePad()

Provides XOR and digit-based OTP operations using derived stream keys.

OneTimePad() also depends on KeyStream() and can be used as a preprocessing step before deterministic transport conversion.

---

## Inputs PswKey

Base10, Base100 and Base256 represent canonical input formats.

�! See: [Input/output encoding](/src/Core/Documentation/Format/Encoding.md)

These formats are used as the source or target for conversion.

Base32, Base58, Base62 and Base64 represent encoded symbol formats used during decoding.

A typical flow is:

`php

->from(100)->to(N)

->from(N)->to(100)

`

�! See: [system-defined](/src/Core/Documentation/Format/System.md)

Note: when used for security reason, do not provide structured or human-readable input. Use high-entropy data or an intermediate transformation step instead.

### Custom-defined

Custom-defined conversion follows a simple directional model:

- customTo(x, y, z) is used for encode

- customFrom(x, y, z) is used for decode

A typical flow is:

`php

->from(100)->customTo($alfabet, X, true)

->customFrom($alfabet, X, true)->to(100)

`

�! See: [Custom-defined](/src/Core/Documentation/Format/Custom.md)

---

## Usage

### Common Use

Convert 100,000 random bytes into a deterministic Base32 representation and decode it back to the original byte sequence.

`php

use PswKey\Service\KeyStream;

use PswKey\Service\PswKey;

//Time-based key

$date = new DateTime();

$key = \strtotime($date->format('Y-m-d H:i:s')) . $date->format('u');

//Derived stream provider

$keyStream = new KeyStream("Service=README.md : user=536984 : alias=VisalStudio", $key);

//Deterministic converter

$pswkey = new PswKey($keyStream);

//Generate input bytes

$randomBytes = randombytes(100000);

//Conversion to encode

$encode = $pswkey->from(256)->to(32)->convert($randomBytes);

//Encode status

$status = $pswkey->status();

if($status->valid) { //$encode !== null => is also possible

//Encoded output must differ from the original input

if($encode !== $randomBytes) {

echo "RandomBytes is not equal as Encode \n";

}

//Conversion to decode

$decode = $pswkey->from(32)->to(256)->convert($encode);

//Decode status

$newStatus = $pswkey->status();

if($newStatus->valid) {

//Decoded output must match the original input

if($decode === $randomBytes) {

echo "Decode is equal as RandomBytes \n";

}

}

else {

//Public/client-safe message

echo $status->clientMessage;

}

}

else {

//Internal/dev-only message

echo $status->internalMessage;

}

`

---

One-time-pad digit stream conversion with reverse flow.

`php

use PswKey\Service\KeyStream;

use PswKey\Service\OneTimePad;

//Digit number

$originalDigits = "0931024538975689521014785";

// Example workflow (a possible path):

// - Base100/Base256 �! Base10

// - OneTimePad digit transformation

// - Base10 �! BaseX conversion

// - Reverse flow for decoding

//Time-based key

$date = new DateTime();

$key = \strtotime($date->format('Y-m-d H:i:s')) . $date->format('u');

//Derived stream provider

$keyStream = new KeyStream("Service=README.md : user=5236947 : alias=VisalStudio", $key);

//OTP instance

$oneTimePad = new OneTimePad($keyStream);

//Using any numeric identifier and 8-byte derivation context

$encode = $oneTimePad->digit($originalDigits, 5236947, "MyDigits");

if($encode !== $originalDigits) {

echo "Encode is not equal as originalDigits \n";

}

$status = $oneTimePad->status();

if($status->valid) {

//Decode into orginal digits

$decode = $oneTimePad->digit($encode, 5236947, "MyDigits");

if($decode === $originalDigits) {

echo "Decode is equal as originalDigits \n";

}

}

else {

echo $status->internalMessage;

}

`

---

### Advanced Use Case

Create a derived transport key from a user password and store a secure password hash in the database.

`php

use PswKey\Service\KeyStream;

use PswKey\Service\PswKey;

use PswKey\Util\Secure\Memezero;

try {

//User credentials

$email = "info@pswkey.com";

$password = "My_PswKey�2025!";

//Derived stream provider

$keyStream = new KeyStream(

"Service=README.md | emailadress={$email}" //Seedphrase can be anything related to your service

);

//Attach password as custom key

$keyStream->setCustomKey($password);

//Generated outputs

$transportkey = "";

$passwordHash = "";

$keyStream->byteStream(

function($entropyPassword) use (&$transportkey, &$passwordHash, &$keyStream) {

$pswKey = new PswKey($keyStream);

//Derived password => transport-safe Base32 representation

$transportkey = $pswKey->from(256)->to(32)->convert($entropyPassword);

//Derived password => password hash for database storage

$passwordHash = passwordhash($entropyPassword, PASSWORDDEFAULT);

unset($pswKey);

},

64, //Entropy password length

"MySecret" //Your service-specific derivation context (must be 8 bytes)

);

echo $transportkey . "\n <br>";

echo $passwordHash . "\n <br>";

//To validate:

//regenerate the "derived password" from the incoming password

//and compare it with the stored database hash

//Example password hash:

//$2y$10$WiLT89W8P60h9mZgqU3TweFT9EjFB57iv05kzvMsd1hEJ6R53vBJe

//Optional "transport key" representation:

//(cookies, transport identifiers, login flows, etc.)

//Example transport key:

//mdvWkllAVlVULqMLBsGWL2BVm4bkz14UgMgUAmUBBZdG7m4kBVGLg4LWRBtsq1Aes4yegyL1WzUggq4lsMbRVveMq

//MGRgAlKgm2gBBL7sMzWh2Mqnkdk1tUsl4GG

}

finally {

//Clear sensitive data

Memezero::overwriteString($password);

unset($keyStream);

}

`

Validate a transport key by decoding it into its derived password representation and comparing it against the stored password hash.

`php

use PswKey\Service\KeyStream;

use PswKey\Service\PswKey;

use PswKey\Util\Secure\Memezero;

try {

//User credentials

$email = "info@pswkey.com";

//Incoming transport key

$transportKey = "gUi0zrccwPdLL88IvwUwB2eMO2UtP0UvvNcITTgOv8cNl0W0o8lgPwQtoNTTlTgAA8l0P2vBl2WtAU"

. "twANtOfIpoovpyO2UfOlUTWMUHBNvicA2OfvzfO8UANeoz";

//Derived stream provider

$keyStream = new KeyStream("Service=README.md | emailadress={$email}");

$pswKey = new PswKey($keyStream);

//Decoded transport key into derived password bytes

$entropyPsw = $pswKey->from(32)->to(256)->convert($transportKey);

//Validate transport key conversion

if($entropyPsw !== null) {

//Retrieve stored password hash only after successful transport-key validation

$dbHashed = "\$2y\$10\$RGbITslA7qBNeiJ8/Zk3A.t7sOXpOLHqTgqT5.mtSmrGpIL9c75jG";

//Compare derived password against stored hash

if (password_verify($entropyPsw, $dbHashed)) {

echo 'Password is valid!';

} else {

echo 'Invalid password.';

}

}

}

finally {

//Clear sensitive data

Memezero::overwriteString($entropyPsw);

unset($keyStream, $pswKey);

}

`

---

## Core System Documentation

�! complete: [Technical documentation](/src/Core/Documentation)