Skip to content

Latest commit

 

History

History
79 lines (60 loc) · 4.04 KB

README.md

File metadata and controls

79 lines (60 loc) · 4.04 KB

IDMask

IDMask is an implementation of IDMask in PHP.

IDMask is a PHP library for masking internal IDs (e.g. from your DB) when they need to be publicly published to hide their actual value and to prevent forging. This should make it very hard for an attacker to understand provided IDs (e.g. by witnessing a sequence, deducting how many orders you had, etc.) and prevent guessing of possible valid ones. Masking is fully reversible and also supports optional randomization for e.g. shareable links or one-time tokens.
It has a wide support for various data types including (big) integers, UUIDs and arbitrary strings. This library bases its security on strong cryptographic primitives (AES, HMAC, HKDF) to create a secure encryption schema. It was inspired by HashIds, but tries to tackle most of its shortcomings.

Feature Overview

  • Secure: Creates encrypted IDs with proper cryptography (AES, HKDF) including forgery protection (HMAC)
  • Wide range of data types supported: Masks IDs from integers, UUIDs, strings, or byte sequences
  • Full support of types: Has no arbitrary restrictions like "only positive numbers", etc.
  • ID randomization: If enabled, IDs are generated which appear uncorrelated with the same underlying value.
  • No collisions possible: As IDs are not hashed or otherwise compressed, collisions are impossible.
  • Lightweight & Easy-to-use: Has only minimal dependencies and a straight forward API.
  • Supports multiple encodings: Depending on your requirement (short IDs vs. readability vs. should not contain words) multiple encodings are available including Base64, Base32 and Hex with the option of providing a custom one.

Installation

Install IDMask from Composer:

composer require matchory/id-mask

Quickstart

use Matchory\IdMask\IdMask;
use Matchory\IdMask\KeyManagement\KeyStore;
use Matchory\IdMask\KeyManagement\SecretKey;

$keyStore = KeyStore::with(SecretKey::generate())
$mask = IdMask::forInteger($keyStore)->mask('foo');

assert('foo' === IdMask::forInteger($keyStore)->unmask($mask))

TODO: More content will be available as the library gets fully implemented.

Further Reading

Main Article

Discussions

Similar Libraries

Contributing

Submit a pull request or open an issue on GitHub. We welcome contributions from all kinds of people!