shawm11/hawk-auth

PHP implementation of the Hawk HTTP authentication scheme

1.0.9 2024-11-13 02:26 UTC

Requires

• php: >=5.5.0

Requires (Dev)

• php: >=7.3.0
• codeception/assert-throws: ^1.0
• codeception/specify: ^2.0
• codeception/verify: ^3.2
• consolidation/robo: ^4.0
• marcocesarato/php-conventional-changelog: ^1.17
• phpstan/phpstan: ^2.0
• phpunit/phpunit: ^9.0
• squizlabs/php_codesniffer: ^3.2

MIT

README

Hawk Authentication PHP

A PHP implementation of the 9.0.2 version of the Hawk HTTP authentication scheme.

Important

Hawk is one of those rare projects that can be considered "complete". According to its README, the protocol and documentation are considered complete. This means that changes to this repository be infrequent because only the development dependencies may need to be updated once every few years.

If there is a bug or error in the documentation, please create an issue. The issue will receive a response or be resolved as soon as possible.

Table of Contents

• What is Hawk?
• Getting Started
  • Prerequisites
  • Installation
• Usage Examples
• API References
• Security Considerations
• Related Projects
• Contributing/Development
• Versioning
• License

What is Hawk?

According to the Hawk's API documentation:

Hawk is an HTTP authentication scheme providing mechanisms for making authenticated HTTP requests with partial cryptographic verification of the request and response, covering the HTTP method, request URI, host, and optionally the request payload.

Note that Hawk is not a complete replacement of OAuth. It is candidly stated in the Frequently Asked Questions section of the Hawk API documentation that:

Hawk was originally proposed as the OAuth MAC Token specification. However, the OAuth working group in its consistent incompetence failed to produce a final, usable solution to address one of the most popular use cases of OAuth 1.0 - using it to authenticate simple client-server transactions (i.e. two-legged). As you can guess, the OAuth working group is still hard at work to produce more garbage.

Hawk provides a simple HTTP authentication scheme for making client-server requests. It does not address the OAuth use case of delegating access to a third party. If you are looking for an OAuth alternative, check out Oz.

More more information about Hawk, check out its API documentation

Getting Started

Prerequisites

• Git 2.9+
• PHP 5.5.0+
• OpenSSL PHP Extension
• JSON PHP Extension
• Composer

Installation

Download and install using Composer:

composer require shawm11/hawk-auth

Usage Examples

The examples in this section do not work without modification. However, these examples should be enough to demonstrate how to use this package. Because PHP is a language most commonly used for server logic, the "Server" usage is more common than the "Client" usage.

• Server Example
• Client Example

API References

• Server API — API reference for the classes in the Shawm11\Hawk\Server namespace
• Client API — API reference for the classes in the Shawm11\Hawk\Client namespace
• Utils API — API reference for the classes in the Shawm11\Hawk\Utils namespace
• Crypto API — API reference for the classes in the Shawm11\Hawk\Crypto namespace

Security Considerations

See the Security Considerations section of Hawk's API documentation.

Related Projects

• Oz PHP Implementation — Oz is a web authorization protocol that is an alternative to OAuth 1.0a and OAuth 2.0 three-legged authorization. Oz utilizes both Hawk and iron.
• Iron PHP Implementation — iron (spelled with all lowercase), a cryptographic utility for sealing a JSON object into an encapsulated token. iron can be considered as an alternative to JSON Web Tokens (JWT).

Contributing/Development

Please read CONTRIBUTING.md for details on coding style, Git commit message guidelines, and other development information.

Versioning

This project uses SemVer for versioning. For the versions available, see the tags on this repository.

License

This project is open-sourced software licensed under the MIT license.