Skip to end of metadata
Go to start of metadata

<ac:macro ac:name="unmigrated-inline-wiki-markup"><ac:plain-text-body><![CDATA[

<ac:macro ac:name="unmigrated-inline-wiki-markup"><ac:plain-text-body><![CDATA[

Zend Framework: Zend_Crypt Component Proposal

Proposed Component Name Zend_Crypt
Developer Notes http://framework.zend.com/wiki/display/ZFDEV/Zend_Crypt
Proposers Pádraic Brady
Dmitry Stogov, Zend liaison
Revision 1.1 - 12 September 2007 (wiki revision: 7)

Table of Contents

1. Overview

The purpose of Zend_Crypt is to offer PHP5 implemented cryptographic and encryption algorithms for use by other components (e.g. Zend_Mail, Zend_OpenId) and application developers themselves. In proposing Zend_Crypt, a primary goal is to reduce reliance on disparate implementations within the framework by offering very flexible implementations which will utilise available PHP5 core extensions. This reduces duplication and centralises maintenance of essential core cryptographic algorithms.

The two initial Zend_Crypt implementations of the Hashed Message Authentication Code (HMAC; RFC 2104) and Diffie-Hellman Key Exchange (DH; RFC 2631) are proposed first since they are required algorithms of the OpenID 2.0 Authentication Specification which is being implemented as Zend_OpenId. Others will follow should the proposal be accepted.

A base Zend_Crypt class will additionally collate static methods for common tasks such as hashing and random number generation which may rely on more than one PHP extensions or functions.

2. References

Related PEAR proposals for PHP5/PEAR2

RFC References

3. Component Requirements, Constraints, and Acceptance Criteria

  • Must be accompanied by comprehensive unit tests reflecting any RFCs which illustrate a testing framework
  • Must implement Hashed Message Authentication Code (RFC2104)
  • Must implement Diffie-Hellman Key Exchange (RFC2631)
  • Must implement Math methods for enabling big integer (> 32 bit) support and methods for transforming big integer strings to binary forms, and vice versa.
  • Must contain ability to use future ext/openssl support for Diffie-Hellman computations.

4. Dependencies on Other Framework Components

  • Zend_Exception

5. Theory of Operation

Zend_Crypt will form a collection of cryptographic and encryption classes. As such each component can be used in isolation, or to perform aggregate operations (e.g. using Diffie-Hellman to negotiate an HMAC). Operation is intended to be flexible, with support for input and output (where warranted) forms like big integers and binary. General purpose static methods will be contained in a base Zend_Crypt class.

Part of each class's responsibility will be to implement each algorithm with support for a range of PHP extensions. This will increase support coverage for all PHP5.1+ versions where arbritrary precision math and hashing extensions may vary widely. At a minimum support for ext/hash, ext/mhash, ext/bcmath, ext/openssl (from PHP 5.3) and ext/gmp will be implemented.

Please refer to Use Cases for additional API overviews.

6. Milestones / Tasks

  • Milestone 1: Implement Hashed-Message-Authentication-Code (HMAC) and Diffie-Hellman-Key-Exchange (DH)
  • Milestone 2: Verify operation using Unit Tests based on RFC test examples and which test both standard and binary output.
  • Milestone 3: Documentation

7. Class Index

  • Zend_Crypt
  • Zend_Crypt_Hmac
  • Zend_Crypt_DiffieHellman
  • Zend_Crypt_Math

8. Use Cases

  • All use cases take the form of Unit Tests*
  • Zend_Crypt_Hmac *

Please note that these simple Unit Tests are matched with far more realistic tests using big integers. The above are simple test cases used for illustrative purposes. HMAC tests in particular follow an RFC which defines the test data and expected results.

  • Zend_Crypt_DiffieHellman *

Diffie-Hellman Key Exchange involved two parties, communicating across an insecure communication channel, negotiating a shared secret key which cannot be guessed or reverse engineered by a third party. If it looks a bit unintuitive - bear in mind the private keys are never exchanged. Without the private keys, a third party can have every single piece of data but remain unable to re-perform the shared key computation.

Please note that these simple Unit Tests are matched with far more realistic tests using big integers. The above are simple test cases used for illustrative purposes.

9. Class Skeletons

Zend_Crypt_Hmac

Zend_Crypt_DiffieHellman

]]></ac:plain-text-body></ac:macro>

]]></ac:plain-text-body></ac:macro>

Labels:
None
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.

16 Comments

comments.show.hide

  1. Jul 17, 2007

    Till Klampaeckel

    <p>First off, this looks really good and especially thanks for the inline documentation. <ac:emoticon ac:name="smile" /></p>

    <p>The only thing I am not sure off is wether all your variables should be really "private". I think "protected" would work better (also in terms of if I wanted to extend your class in my own app etc.).</p>

  2. Jul 18, 2007

    Pádraic Brady

    <p>Hi Till,</p>

    <p>I'll make some more vars protected - I think it's on my todo list from the PEAR comments too.</p>

  3. Jul 18, 2007

    Simon Mundy

    <p>Just a thought - would be possible to add a static method that provides the hash as a straight conversion (a-la Zend_Filter) if an instance is not required?</p>

    <p>E.g.</p>
    <ac:macro ac:name="code"><ac:plain-text-body><![CDATA[
    $hash = Zend_Crypt_Hmac::generate($key, 'Md5', $data);
    ]]></ac:plain-text-body></ac:macro>

  4. Jul 19, 2007

    Pádraic Brady

    <p>So long as you don't mind it instantiating the object internally. I added a static method to svn - see if it floats your boat. Also fixed a small Zend_Math bug about an undefined variable. Somehow missed it in the unit tests.</p>

  5. Jul 23, 2007

    Dmitry Stogov

    <p>I don't see big problems with this proposal. The only thing that I don't like is an overhead. Many tasks that require just one function call are done using object instantiation ...<br />
    I would prefer simple static method</p>
    <ac:macro ac:name="code"><ac:plain-text-body><![CDATA[
    Zend_Crypt::hmac($data, $key, $hash);
    ]]></ac:plain-text-body></ac:macro>
    <p>instead of longer and slower</p>
    <ac:macro ac:name="code"><ac:plain-text-body><![CDATA[
    $hmac = new Zend_Crypt_Hmac($key, $hash);
    $hmac->hash($data);
    ]]></ac:plain-text-body></ac:macro>
    <p>But I can live with such design too.</p>

    <p>Also I didn't understand why Zend_Crypt_DiffieHellman::computeSecretKey() returns object but not the 'secret' itself and what is the neediness in separate method Zend_Crypt_DiffieHellman::getSharedSecretKey()</p>

    1. Aug 03, 2007

      Stanislav Malyshev

      <p>I agree with the argument about static methods. We should have short methods for often-used operations - no need to create an object if we do one-time operation. </p>

      <p>It is not completely clear what is the number storage formats used everywhere - i.e. is it bit stream, hex text representation or something else? </p>

      <p>I see that supported algorithms are listed statically - shouldn't they be somehow dynamically acquired from the extensions instead? </p>

  6. Sep 12, 2007

    Pádraic Brady

    <p>The proposal has been updated following comments and a review by Dmitri.</p>

    <p>The main changes are as follows:</p>

    <ul>
    <li>Zend_Crypt_Hmac contains a single compute() static method for calculating a MAC digest.</li>
    <li>Zend_Crypt_DiffieHellman has some small API updates, and will include support for Dmitry's ext/openssl patch which in PHP 5.3 will include support for generating Diffie-Hellman keys far more efficiently than using BCMath alone.</li>
    <li>A Zend_Crypt base class will be added and contain some common tasks such as random number generation (whether by simulaton, or the Linux kernals RNG at /dev/random), and hashing methods (esp. for those not supported by native PHP functions like Whirlpool).</li>
    <li>The current Zend_Math being a simple wrapper around BCMath, GMP will be moved to Zend_Crypt_Math (as with the PEAR Crypt_DiffieHellman package)</li>
    </ul>

  7. Feb 08, 2008

    Steven Brown

    <p>I would suggest the addition of classes for the following algorithms:</p>

    <ul>
    <li>RSA</li>
    <li>DES</li>
    <li>3DES (TripleDES)</li>
    <li>AES</li>
    </ul>

    <p>You might also consider:</p>

    <ul>
    <li>RC4</li>
    <li>RC5</li>
    <li>Twofish</li>
    <li>Blowfish</li>
    </ul>

    <p>I also wonder if you may have to look at a more secure random number generator.</p>

    <p>A long term goal may be to create a PHP version of <a class="external-link" href="http://bouncycastle.org/">http://bouncycastle.org/</a> I have used that on Java projects and it has a lot of algorithms and seems popular.</p>

    1. Dec 05, 2009

      hotning

      <p>If you want a PHP version of bouncycastle check out phpseclib:</p>

      <p><a class="external-link" href="http://phpseclib.sourceforge.net/">http://phpseclib.sourceforge.net/</a></p>

  8. Feb 09, 2008

    Pádraic Brady

    <p>Hi Steven,</p>

    <p>Once the component reaches Core, the floor will be open for sub-components. I use several of the mentioned functions so there is lot's of scope for additional proposals.</p>

  9. Oct 15, 2008

    Svetoslav Marinov

    <p>What is the status of the component ?</p>

  10. Feb 13, 2009

    Jon Whitcraft

    <p>Pining to find out the status of this. I need the HMAC support for Zend_Service_Amazon_Sqs. What needs to be done to get this into 1.8?</p>

  11. Mar 18, 2009

    Wil Sinclair

    <p>It seems that there is a new use case for finishing this proposal. Paddy, what is the status? I could potentially get some resources to help with this.</p>

    1. Mar 24, 2009

      Jon Whitcraft

      <p>I agree with Wil. I am willing to help write some unit test and such to get this proposal included in 1.8.</p>

      1. Sep 17, 2009

        Acorn

        <p>If work on this is to continue, here's an idea: replace Zend_Crypt_Math_BigInteger with phpseclib's Math_BigInteger:</p>

        <p>http://phpseclib.cvs.sourceforge.net/viewvc/*checkout*/phpseclib/phpseclib/Math/BigInteger.php?revision=1.5</p>

        <p>The problem is that Zend_Crypt_Math_BigInteger requires the bcmath or gmp extensions be installed, which, on a host you don't control, might not be the case. phpseclib's Math_BigInteger, however, has a pure-PHP implementation. It uses gmp and bcmath, if they're available, and it's own internal pure-PHP implementation, otherwise.</p>

        <p>Since it's written using the Zend coding standards, adapting it over shouldn't be too difficult.</p>

  12. Feb 22, 2011

    Benoît Durand

    <p>What is the status of this proposal?</p>