# RFC: HashContext as Object

- Status: Implemented (PHP 7.2)
- Authors: Sara Golemon pollita@php.net, with initial implementation from Rouven Weßling me@rouvenwessling.de
- Date: 2016-12-26
- Version: 1.0
- Original: https://wiki.php.net/rfc/hash-context.as-resource
- Page: https://externals.io/rfc/hash-context.as-resource
- More for agents: search with https://externals.io/search.md?q={query} · RFCs at https://externals.io/rfc.md · JSON API at https://externals.io/api · documentation at https://externals.io/llms.txt

## Votes

### Change HashContext to an object (closed)

Yes: 15 · No: 0

Voters: ashnazg (Yes), auroraeosrose (Yes), bishop (Yes), bwoebi (Yes), guilhermeblanco (Yes), leigh (Yes), marcio (Yes), mariano (Yes), mike (Yes), nikic (Yes), ocramius (Yes), pollita (Yes), sammyk (Yes), trowski (Yes), zimt (Yes)

### Merge one or both diffs (closed)

Frozen: 9 · Reentrant: 6

Voters: ashnazg (Reentrant), auroraeosrose (Reentrant), bishop (Reentrant), bwoebi (Frozen), derick (Reentrant), guilhermeblanco (Reentrant), krakjoe (Frozen), leigh (Frozen), marcio (Frozen), mariano (Frozen), mike (Frozen), nikic (Frozen), ocramius (Reentrant), pollita (Frozen), trowski (Frozen)

## Discussions on the mailing list

- [\[RFC\] HashContext as Object](https://externals.io/message/97468.md) — started on 2016-12-27, 4 messages
- [\[RFC\]\[Vote\] HashContext using Objects](https://externals.io/message/97842.md) — started on 2017-01-17, 2 messages
- [\[RFC\]\[Accepted\] HashContext as Object](https://externals.io/message/98103.md) — started on 2017-02-01, 1 messages
- [Convert ext/xml to use an object instead of resource](https://externals.io/message/104361.md) — started on 2019-02-12, 13 messages

---

## Introduction

Since PHP5, objects have been the preferred structure for wrapping internal data, however some clod created the hash extension to use resources. This RFC seeks to rectify that error by migrating the Hash extension to use an object implementation for hash contexts instead of a resource.

## Proposal

Convert the opaque resource to an opaque object. This is the lightest touch change to ensure that existing code should continue to function unless it has explicit is\_resource() checks. These checks can be easily replaced with is\_resource\|is\_object checks instead.

## Future Scope

- Actual oop interface in the form of a few methods: HashContext::\_\_construct() mirroring hash\_init, HashContext::update() mirroring hash\_update, etc...
- String casting to invoke &#96;-&gt;final()&#96; - Probably a bad idea as the object becomes immutable once it is finalized.
- Comparison overloading - Handy, but should explicitly use hash\_equals() algorithm to avoid timing attacks.
- Operator overloading (e.g. &#96;$b = $a + 'foo';&#96; ~= &#96;$b = clone $a; $b-&gt;update('foo');&#96; - Probably a bad idea, but included for completeness.
- Serialization/Deserialization - Potential (but unconfirmed) security issues as the internal hash state becomes visible and previously impossible replays may become available.

## Backward Incompatible Changes

Any userspace code which explicitly type checks HashContext values using is\_resource()/get\_resource\_type()

## Proposed PHP Version(s)

PHP 7.next

## Open Issues

Finalizing a hash context currenly invalidates the resource via &#96;zend\_list\_close()&#96; making all future operations on that value fail. This patch emulates this by clearing the internal value &#96;context&#96; and verifying it in all function invocations using the value. This isn't typical object behavior, but minimizes BC breakage. We could potentially invoke hash\_copy() to save the context prior to finalization, finalize it, then revert to the prior state by restoring the saved context. This makes sense to me, but introduces a change to behavior which needs to be discussed.

## Proposed Voting Choices

Include one or both patches at <https://github.com/php/php-src/pull/2309> 50%+1 required.

This primary vote is to determine, overall, if the “hash context” resource used by hash\_init/hash\_update/hash\_final should be changed to an object.

**Vote: Change HashContext to an object** — Yes: 15 · No: 0 (closed)

This second vote, contingent on passing the first vote, determines which behavior the new HashContext will adopt (per the “Open Issue” above).

- “Frozen”: Only apply [ the original patch](https://github.com/php/php-src/pull/2309/commits/e29923471b54b5b0712978274404c37f34d34ea6) which will invalidate the HashContext object upon calling hash\_final(). This is consistent with the current behavior of the resource, but inconsistent with most class/object definitions in PHP.
- “Reentrant”: Apply both diffs in [PR#2309](https://github.com/php/php-src/pull/2309) which will allow contexts to continue functioning after calling hash\_final() by effectively performing: $saved = hash\_copy($ctx); $ret = hash\_final($ctx); $ctx = $saved;

**Vote: Merge one or both diffs** — Frozen: 9 · Reentrant: 6 (closed)

Voting opened: 2017-01-17 22:50:00 UTC 
Voting closes: 2017-01-31 23:59:59 UTC

## Patches and Tests

- Implementation for PHP 7.2 <https://github.com/php/php-src/pull/2309>
- Original PR by Rouven Weßling: <https://github.com/php/php-src/pull/660>
