Download the PHP package snicco/signed-url without Composer

A secure, modular and framework-agnostic PHP library to sign and verify urls.

Table of contents

1. Motivation
2. Installation
3. Usage
   1. Creating a secret
   2. Creating a signed-url
   3. Validating a signed url
      1. PSR-15 middleware
      2. Other PHP applications
   4. Storage types
      1. Session
      2. Null
      3. InMemory
      4. PSR-16
      5. Implement your own
4. Contributing
5. Issues and PR's
6. Security

Motivation

While developing the Snicco project we couldn't find any good standalone PHP-libraries for signing urls. We needed this functionality in a couple of places, so we decided to roll our own implementation.

Features:

• Uses strong, random secrets, generated by a CSPRNG and secure hash functions.
• Validates the signature, the expiration and an enforced usage-limit on a per url basis.
• PSR-7/15 compatible. No hidden dependencies on PHP super globals.
• Protects against timing based side-channel attacks
• Permanently invalidates a signed-url after the max usage. (Rotating your secret invalidates all signed-urls)
• Defensively programmed, making incorrect usage very hard.
• Support for multiple storage backends.
• A properly tested and straightforward API.

While the term signed-url is technically incorrect (this package uses HMACs, not asymmetric signatures), we chose to stick to the way Symfony and Laravel name it.

Installation

Usage

Creating a secret

Run the following command from your project root and store the generated secret in a secure location that is outside your web root.

This will output a random, hex-encoded secret that looks like this: 32|1e21be67f2279e485c7c5e8291d05edda7e76ffb01ddb8eb290ce826528ad2ff

This secret should NEVER be stored in version control.

In your application, load the secret from an environment variable in your application using something like symfony/dotenv.

Creating a signed-url

Validating a signed-url

Validation of signed-urls should be performed in a middleware to avoid boilerplate.

The code samples below describe the manual way to validate urls in any PHP application.

PSR-15 middleware

If your favorite framework is PSR-7/PSR-15 compatible and supports middleware on a per-route basis, you can use our PSR-15 middleware bridge which makes this dead simple.

All PHP apps

Storage types

The Snicco\SignedUrl\Contracts\SingedUrlStorage keeps an identifier for each signed-url that is created and ensures that your max usage limits are enforced.

Without some form of backend storage, signed-urls are valid any number of times until the expiration timestamp is passed. (If this is what you want you can use the NullStorage).

SessionStorage (included):

The SessionStorage accepts an array or any object that implements ArrayAccess (passed by reference).

NullStorage (included)

The NullStorage does nothing. No signed-urls will be stored and no usage limits are enforced. Use this only if your signed-urls should be valid any number of times before expiring.

Validity of a signed-url will be based solely on the correct signature and expriation timestamp.

InMemory (included):

You can use the InMemoryStorage during unit tests.

PSR16-Cache (bridge package):

We have a dedicated PSR-16 bridge that will allow you to use any PSR-16 cache as a storage.

Implementing your own storage:

Implementing your own storage is very easy. You only have to implement the simple SingedUrlStorage interface.

Use the snicco/signed-url-testing package to test your implementation against the contract of the interface.

Contributing

This repository is a read-only split of the development repo of the Snicco project.

This is how you can contribute.

Reporting issues and sending pull requests

Please report issues in the Snicco monorepo.

Security

If you discover a security vulnerability, please follow our disclosure procedure.