Download the PHP package oire/iridium without Composer

Iridium, a Security Library for Encrypting Data, Hashing Passwords and Managing Secure Tokens

Welcome to Iridium, a security library for encrypting data, hashing passwords and managing secure tokens! This library consists of several classes, or modules, and can be used for hashing and verifying passwords, encrypting and decrypting data, as well as for managing secure tokens suitable for authentication cookies, password reset, API access and various other tasks.

Requirements

Requires PHP 8.3 or later with PDO, _pdomysql, Mbstring, OpenSSL and Sodium enabled.

For local development, Docker and Docker Compose are used to provide a FrankenPHP + MariaDB environment.

Installation

Install via Composer:

Running Tests

Running Psalm Analysis

🖇 Base64 Handling, URL-safe Way

The Base64 module encodes data to Base64 URL-safe way and decodes encoded data.

Usage Examples

This will output:

By default, the encode() method truncates padding = signs as PHP's built-in decoder handles this correctly. However, if the second parameter is given and set to true, = signs will be replaced with tildes (~), i.e.:

This will output:

To decode the data, simply call Base64::decode():

This will output:

Methods

The Base64 class has the following methods:

• static encode(string $data, bool $preservePadding = false): string — Encodes provided data into URL-safe Base64. If preservePadding is set to true, the padding = signs will be replaced by tildes (~). If set to false (default), padding signs will be truncated.
• static decode(string $encodedData): string — decodes provided Base64 data and returns the original string.

🗝 Crypt

The Crypt module is used to encrypt and decrypt data. Note! Do not use this for managing passwords! Passwords must not be encrypted, they must be hashed instead. To manage passwords, use the Password module (see below). Currently the Crypt module supports only shared key encryption, i.e., encryption and decryption is performed with one single key.

As of v3.0, Crypt uses AES-256-GCM (authenticated encryption with associated data) for new encryptions. Data encrypted with the previous AES-256-CTR + HMAC-SHA384 scheme (v1) is still transparently decrypted for backward compatibility. The swapKey() method automatically migrates v1 ciphertext to v2 (GCM) when re-encrypting.

🔑 Shared Key

This objects holds a key used to encrypt and decrypt data with the Crypt module. First you need to create a key and save it somewhere (i.e., in a .env file):

This will output a readable and storable string, something similar to this:

SharedKey Methods

Generally, you will only need the getKey() method for storing the key in a safe place. You can also benefit from using the __toString() method and treat the key object as a string. However, let's describe all the methods for the sake of completeness:

• __construct(string|null $key = null) — Class constructor. If a key is provided, it will be applied to create a new SharedKey instance. If not, a random key will be generated instead.
• static create(string|null $key = null): self — Static factory method. Creates a new SharedKey instance. If a key is provided, it will be validated and used. If not, a random key will be generated.
• getRawKey(): string — Returns the key in raw binary form. Needed mostly for internal use.
• getKey(): string — Returns the key in readable and storable form. Use this to retrieve a newly generated random key.
• deriveKeys(string|null $salt = null): DerivedKeys — Uses hash key derivation function to derive encryption and authentication keys and returns a DerivedKeys object, see below. Use this only if you really know what you are doing. It is used internally by the Crypt module. If the salt is provided, derives the keys based on that salt (used for decryption). In 99,(9)% of cases you don't need to use this method directly.
• __toString(): string — Returns the readable and storable key when the object is called as a string.

Derived Keys

The DerivedKeys object holds the keys derived by the deriveKeys() method of the shared key. Again, in 99,(9)% of cases you don't want to use it, but let's enumerate its methods.

• __construct(string $salt, string $encryptionKey, string $authenticationKey) — Class constructor. Is instantiated by the deriveKeys() method of the SharedKey object.
• getSalt(): string — Gets the encryption salt.
• getEncryptionKey(): string — Gets the derived encryption key.
• getAuthenticationKey(): string — Gets the derived authentication key.
• areValid(): bool — Checks if the derived keys are valid. Returns true if the keys are valid, false otherwise.

Crypt Usage Examples

If you created a shared key as shown above, you can encrypt your data with this key:

That's it, you may store your encrypted data in a database or perform other actions with them. To decrypt the data with the same key, use the following:

Exceptions

Crypt throws EncryptionException, DecryptionException and sometimes a more general CryptException. If something is wrong with the key, a SharedKeyException is thrown.

Methods

The Crypt class has the following methods:

• static encrypt(string $data, SharedKey $key): string — Encrypts given data with a given key. Returns the encrypted data in readable and storable form.
• static decrypt(string $encryptedData, SharedKey $key): string — Decrypts previously encrypted data with the same key they were encrypted with and returns the original string.
• static swapKey(string $data, SharedKey $oldKey, SharedKey $newKey): string — Reencrypts encrypted data with a different key and returns the newly encrypted data.

🔒 Password

The Password class is used to hash passwords and verify that a provided hash is valid.

Usage Examples

To lock, i.e., hash a password, use the following:

Then you can store your password in the database. To check whether a provided password is valid, use the following:

To check if a stored password hash needs rehashing (for example, after PHP upgrades its default algorithm parameters):

You can also use Crypt to reencrypt the password with another key, just use Crypt::swapKey() and provide your password hash to it. Remember that you cannot "decrypt" a password and obviously must not store unhashed plain-text passwords, this poses a huge security risk.

Methods

The Password class has the following methods:

• static lock(string $password, SharedKey $key): string — Locks, i.e., hashes a password and encrypts it with a given key. Returns the encrypted hash in readable and storable format. A hashed password cannot be restored, so it is safe to be stored in a database.
• static check(string $password, string $encryptedHash, SharedKey $key): bool — Verifies whether a given password matches the provided hash. Returns true on success and false on failure.
• static needsRehash(string $encryptedHash, SharedKey $key): bool — Checks if a stored password hash needs rehashing (e.g., because PHP's default algorithm parameters have changed). Returns true if the hash should be re-locked, false otherwise.

🍪 SplitToken, Simple Yet Secure Token Suitable for Authentication Cookies and Password Recovery

SplitToken is a class inside Iridium that can be used for generating and validating secure tokens suitable for authentication cookies, password recovery, API keys and various other tasks.

The Split Tokens Concept

You can read everything about the split tokens authentication in this 2017 article by Paragon Initiatives. Iridium implements the idea outlined in that article in PHP.

Storage Interface

As of v3.0, SplitToken is decoupled from PDO via the TokenStorageInterface. The library ships with PdoTokenStorage for MySQL/MariaDB, but you can implement the interface for any backend.

TokenStorageInterface Methods

• persist(string $selector, string $hashedVerifier, ?int $userId, ?int $tokenType, ?string $additionalInfo, ?int $expirationTime): void — Store a token.
• retrieve(string $selector): array|false — Retrieve a token record by selector.
• updateExpiration(string $selector, int $expirationTime): void — Update the expiration time.
• delete(string $selector): void — Delete a token by selector.
• clearExpired(): int — Delete all expired tokens. Returns the count of deleted tokens.

ListableTokenStorageInterface

Single-use tokens such as password reset links never need to be enumerated: the user clicks the link, and the token is spent. Long-lived tokens are different. If you issue personal access tokens for an API, the owner has to be able to see what they issued and revoke one of them, and neither is possible with the methods above. ListableTokenStorageInterface extends TokenStorageInterface with the four operations that need:

• findByUserId(int $userId): list<StoredToken> — Every token belonging to a user, oldest first.
• findBySelector(string $selector): ?StoredToken — One token, for display or administration. Unlike retrieve(), which exists to feed fromString(), this returns a value object.
• touch(string $selector, int $usedAt): void — Record that a token was used. Throttle this yourself; a chatty API client would otherwise force a write on every request.
• clearExpiredBefore(int $expiredBefore): int — Delete tokens that expired at or before a cutoff. See Clear Expired Tokens below for why the cutoff matters.

StoredToken is a readonly value object carrying id, userId, selector, tokenType, additionalInfo, expirationTime, createdAt and lastUsedAt, plus isEternal(), isExpired() and getExpirationDate(). It deliberately carries neither the token nor the verifier: a listing is something you show a user, and neither of those halves belongs on a screen.

Both bundled storages implement this interface. It needs two extra columns — see Create a Table below.

PdoTokenStorage

DoctrineDbalTokenStorage

For applications already using Doctrine. doctrine/dbal is a suggested dependency only, so the library itself stays dependency-free — install it yourself if you use this storage.

Usage Examples

Each time you use SplitToken::create() to generate a new token or SplitToken::fromString() to instantiate a new SplitToken object from a user-provided token, you need to provide a TokenStorageInterface instance. The bundled PdoTokenStorage wraps a PDO connection.

Create a Table

First you need to create the iridium_tokens table. For MySQL/MariaDB the statement is as follows:

If you want to use ListableTokenStorageInterface, add two more columns:

You may need to adjust the syntax to suit your particular database driver, as well as add foreign key constraints to match your users table.

Create a Token

First you need to create a token. There are some parameters you can set, but only the storage is required, all the other parameters have default values.

• storage — Storage backend, as a TokenStorageInterface instance.
• expirationTime — Time when the token expires. Stored as timestamp (big integer), but can be set either as an integer or as a string. If you provide a string, it will be fed to the DateTimeImmutable constructor. There is also a special value 0 (zero). If you set the expiration time to 0, the default expiration time will be used, it is equal to current time plus one hour. If expirationTime is set to null, the token is eternal, i.e., it never expires. The default value is 0, i.e., expiration in one hour.
• userId — ID of the user the token belongs to, as an unsigned integer. If it is set and is 0 or less, an exception will be thrown.
• tokenType — If you want to perform an additional check of the token (say, separate password recovery tokens from e-mail change tokens), you may set a token type as an integer. In the examples throughout this file we'll use plain numbers, but we suggest using an enum instead.
• additionalInfo — Any additional information you want to convey with the token, as string. For instance, you can pass some JSON data here. The information can be additionally encrypted. Note again! Do not use this to store passwords, even obsolete ones, this can be decrypted.
• additionalInfoKey — an Iridium shared key used to encrypt the additional info.

To create a token for user with ID of 123 and with token type of 3 expiring in half an hour, and store it into the database, do the following. You can of course use named arguments:

Use $splitToken->getToken() to actually get the newly created token as a string. If you want to create a non-expirable token, explicitly set expirationTime to null.

Set and Validate a User-Provided Token

If you received an Iridium token from the user, you also need to instantiate SplitToken and validate the token. To do this, use SplitToken::fromString() instead of create(). You don't need to set all the properties as their values are taken from the database. This method takes three parameters: the token as string, a TokenStorageInterface instance, and optionally the additional info decryption key as Iridium shared key.

Note! As of v3.1 an expired token is rejected, and so is a revoked one, because revocation is stored as an expiration in the past. Before v3.1 fromString() returned such tokens and left the check to you, which meant that a caller who did not know to call isExpired() authenticated revoked tokens by default.

If you need the object in order to report on it — to tell a user when their password reset link died, say — pass allowExpired: true. Never do this to authenticate:

Revoke a Token

After a token is used once for authentication, password reset and other sensitive operation, is expired or compromised, you must revoke, i.e., invalidate it. If you use Iridium tokens as API keys, tokens for unsubscribing from email lists and so on, you can make your token eternal or set the expiration time far in the future and not revoke the token after first use, certainly. If an eternal token is compromised, you must revoke it, also. The revokeToken() method returns a SplitToken instance with the token-related parameters set to null. When revoking a token, you have two possibilities:

• Setting the expiration time for the token in the past (default);
• Deleting the token from the database whatsoever. To do this, pass true as the parameter to the revokeToken() method:

Revoking by Selector

revokeToken() is an instance method, and the only way to obtain an instance is fromString(), which needs the plaintext token. For a long-lived token that plaintext is exactly what nobody has any more: the owner was shown it once and told it would never be shown again. Revoking such a token from a management screen is therefore impossible through revokeToken().

Use the static revokeBySelector() instead, with a selector taken from getSelector() or from a listing:

Clear Expired Tokens

From time to time you will need to delete all expired tokens from the database to reduce the table size and search times. There is a method to do this. It is static, so you have to provide your TokenStorageInterface instance as its parameter. It returns the number of tokens deleted from the database.

Note! This deletes revoked tokens too, since revocation is stored as an expiration in the past. Running it erases the record of what was revoked and when. Where that history matters — and for API keys it usually does — use a cutoff instead, which sweeps only what expired long enough ago to be uninteresting:

Notes on Expiration Times

• All expiration times are internally stored as UTC timestamps.
• Expiration times are set, compared and formatted according to the time of the PHP server, so you won't be in trouble even if your database server time is slightly off for some reason.
• Expiration time with value 0 (zero) sets the default value, i.e., the token will expire in an hour. Since a bare 0 reads like "no expiration" and silently gives you an hour instead, prefer the SplitToken::EXPIRATION_DEFAULT constant when you mean it.
• If expiration time is set to null, the token is eternal and never expires. This is what you want for API keys, and it must be passed explicitly — the default is one hour.
• Microseconds for expiration times are ignored for now, their support is planned for a future version.

Error Handling

SplitToken throws two types of exceptions:

• InvalidTokenException is thrown when something really wrong happens to the token itself or to SQL queries related to the token (for example, a token is not found, it has been tampered with, its length is invalid or a PDO statement cannot be executed);
• SplitTokenException is thrown in most cases when you do something erroneously (for example, try to store an empty token into the database, try to set a negative user ID etc.).

Methods

Below all of the SplitToken public methods are outlined.

• static create(TokenStorageInterface $storage, int|string|null $expirationTime = SplitToken::EXPIRATION_DEFAULT, int|null $userId = null, int|null $tokenType = null, string|null $additionalInfo = null, Oire\Iridium\Key\SharedKey|null $additionalInfoKey = null): self — Generate a new token. All the parameters are described above, only the storage is required. Expiration time is by default set to 0 which means the token expires in one hour. If $additionalInfoKey is not null, the additional info is encrypted with this key. Throws SplitTokenException if trying to set a non-positive user ID.
• static fromString(string $token, TokenStorageInterface $storage, Oire\Iridium\Key\SharedKey|null $additionalInfoKey = null, bool $allowExpired = false): self — Set and validate a user-provided token. If $additionalInfoKey is not null, decrypts the additional info stored in the database with this key. Throws InvalidTokenException if the token is expired or revoked, unless $allowExpired is true.
• getToken(): ?string — Get the token for the current SplitToken instance as a string, or null if the token was revoked.
• getSelector(): ?string — Get the selector, i.e., the public half of the token used to look its record up, or null if the token was revoked. Needed by anything that acts on a stored token without holding its plaintext.
• getUserId(): ?int — Get the ID of the user the token belongs to, or null if not set.
• getExpirationTime(): ?int — Get expiration time for the token as raw timestamp, or null if the token is eternal.
• getExpirationDate(): ?DateTimeImmutable — Get expiration time for the token as a DateTimeImmutable object. Returns the date in the current time zone of your PHP server, or null if the token is eternal.
• getExpirationDateFormatted(string $format = 'Y-m-d H:i:s'): ?string — Get expiration time for the token as date string, or null if the token is eternal. The default format is 2020-11-15 12:34:56. The $format parameter must be a valid date format.
• isEternal(): bool — check if the token is eternal and never expires. Returns true if the token is eternal, false if it has expiration time set in the future or already expired.
• isExpired(): bool — Check if the token is expired. Returns true if the token has already expired, false otherwise.
• getTokenType(): int|null — Get the type for the current token. Returns integer if the token type was set before, or null if the token has no type.
• getAdditionalInfo(): string|null — Get additional info for the token. Returns string or null, if additional info was not set before.
• persist(): self — Store the token into the database. Returns $this for chainability.
• revokeToken(bool $deleteToken = false): self — Revoke. i.e., invalidate the current token after it is used. If the $deleteToken parameter is set to true, the token will be deleted from the database, and getToken() will return null. If it is set to false (default), the expiration time for the token will be updated and set to a value in the past. Returns $this for chainability.
• static revokeBySelector(TokenStorageInterface $storage, string $selector, bool $deleteToken = false): void — Revoke a token identified by its selector. This is the only revocation route open to a token whose plaintext nobody holds.
• static clearExpiredTokens(TokenStorageInterface $storage): int — Delete all expired tokens from the database. Receives the storage instance as parameter. Returns the number of deleted tokens, as integer. Note that this deletes revoked tokens too.

Changes and Bugfixes

See changelog.

Contributing

All contributions are welcome. Please fork, make a feature branch, hack on the code, commit, push your branch and send a pull request.

Before committing, don't forget to run all the needed checks, otherwise the CI will complain afterwards:

If PHP CS Fixer finds any code style errors, fix them in your code. When your pull request is submitted, make sure all checks passed on CI.

License

Copyright © 2021-2026 André Polykanine, Oire Software. This software is licensed under the Apache License, Version 2.0. See LICENSE for details.