Download the PHP package bigcommerce-labs/hawk without Composer

Hawk — A PHP Implementation

Hawk is an HTTP authentication scheme using a message authentication code (MAC) algorithm to provide partial HTTP request cryptographic verification. — hawk README

Installation

Through Composer as dflydev/hawk.

Client

Building a Client

The Client has a few required dependencies. It is generally easier to construct a Client by using the ClientBuilder. A Client can be built without setting anything to get sane defaults.

Simple ClientBuilder Example

Complete ClientBuilderExample

Creating a Request

In order for a client to be able to sign a request, it needs to know the credentials for the user making the request, the URL, method, and optionally payload and content type of the request.

All available options include:

• payload: The body of the request
• content_type: The content-type for the request
• nonce: If a specific nonce should be used in favor of one being generated automatically by the nonce provider.
• ext: An ext value specific for this request
• app: The app for this request (Oz specific)
• dlg: The delegated-by value for this request (Oz specific)

Create Request Example

The Client Request Object

The Request represents everything the client needs to know about a request including a header and the artifacts that were used to create the request.

• header(): A Header instance that represents the request
• artifacts(): An Artifacts instance that contains the values that were used in creating the request

The header is required to be able to get the properly formatted Hawk authorization header to send to the server. The artifacts are useful in the case that authentication will be done on the server response.

Authenticate Server Response

Hawk provides the ability for the client to authenticate a server response to ensure that the response sent back is from the intended target.

All available options include:

• payload: The body of the response
• content_type: The content-type for the response

Authenticate Response Example

Complete Client Example

Bewit

Hawk supports a method for granting third-parties temporary access to individual resources using a query parameter called bewit.

The return value is a string that represents the bewit. This string should be added to a requested URI by appending it to the end of the URI. If the URI has query parameters already, the bewit should have &bewit= appended to the front of it. If the URI does not have query parameters already, the bewit should have ?bewit= appended to the front of it.

Client Bewit Example

Server

Building a Server

The Server has a few required dependencies. It is generally easier to construct a Server by using the ServerBuilder. A Server can be built without setting anything but the credentials provider to get sane defaults.

Simple ServerBuilder Example

Complete ServerBuilderExample

Authenticating a Request

In order for a server to be able to authenticate a request, it needs to be able to build the same MAC that the client did. It does this by getting the same information about the request that the client knew about when it signed the request.

In particular, the authorization header should include the ID. This ID is used to retrieve the credentials (notably the key) in order to calculate the MAC based on the rest of the request information.

Authenticate Example

The Server Response Object

The Response represents everything the server needs to know about a request including the credentials and artifacts that are associated with the request.

• credentials()
• artifacts()

Creating a Response Header

Hawk provides the ability for the server to sign the response to provide the client with a way to authenticate a server response.

All available options include:

• payload: The body of the request
• content_type: The content-type for the request
• ext: An ext value specific for this request

Create Response Header Example

Complete Server Example

Bewit

Hawk supports a method for granting third-parties temporary access to individual resources using a query parameter called bewit.

Bewit authentication should only occur for GET and HEAD requests. The return value of an authenticated bewit is a Server Response object.

Server Bewit Example

Crypto

Dflydev\Hawk\Crypto\Crypto

Tools for calculation of and comparison of MAC values.

• calculatePayloadHash($payload, $algorithm, $contentType)
• calculateMac($type, CredentialsInterface $credentials, Artifacts $attributes)
• calculateTsMac($ts, CredentialsInterface $credentials)
• fixedTimeComparison($a, $b)
  Used to ensure that the comparing two strings will always take the same amount of time regardless of whether they are the same or not.

Dflydev\Hawk\Crypto\Artifacts

A container for all of the pieces of data that may go into the creation of a MAC.

Credentials

Dflydev\Hawk\Credentials\CredentialsInterface

Represents a valid set of credentials.

• key(): Used to calculate the MAC
• algorithm(): The algorithm used to calculate hashes
• id(): An identifier (e.g. username) for whom the key belongs

In some contexts only the key may be known.

Dflydev\Hawk\Credentials\Credentials

A simple implementation of CredentialsInterface.

Header

Dflydev\Hawk\Header\Header

• fieldName(): The name for the header field
• fieldValue(): The value for the header field
• attributes(): The attributes used to build the field value

Dflydev\Hawk\Header\HeaderFactory

• create($fieldName, array $attributes = null)
  Creates a Hawk header for a given field name for a set of attributes.

• createFromString($fieldName, $fieldValue, array $requiredKeys = null)
  Creates a Hawk header for a given field name from a Hawk value string. For example, 'Hawk id="foo", mac="1234"' would be an example of a Hawk value string. This is useful for converting a header value coming in off the wire.

  Throws:

  • Dflydev\Hawk\Header\FieldValueParserException
  • Dflydev\Hawk\Header\NotHawkAuthorizationException

Dflydev\Hawk\Header\HeaderParser

• parseFieldValue($fieldValue, array $requiredKeys = null)
  Parses a field value string into an associative array of attributes.

  Throws:

  • Dflydev\Hawk\Header\FieldValueParserException
  • Dflydev\Hawk\Header\NotHawkAuthorizationException

Dflydev\Hawk\Header\FieldValueParserException

Indicates that a string claims to be a Hawk string but it cannot be completely parsed. This is mostly a sign of a corrupted or malformed header value.

Dflydev\Hawk\Header\NotHawkAuthorizationException

Indicates that the string has nothing to do with Hawk. Currently means that the string does not start with 'Hawk'.

License

MIT, see LICENSE.

Community

If you have questions or want to help out, join us in #dflydev on irc.freenode.net.