Merge pull request #12 from jstruzik/php72-fixes

PHP 7.2 compatibility and adding example usage

Author: jstruzik

.travis.yml

@@ -2,10 +2,8 @@ sudo: false
 
 language: php
 php:
-  - 5.4
-  - 5.5
-  - 5.6
-  - 7.0
+  - 7.1
+  - 7.2
   - nightly
   - hhvm
 
@@ -17,6 +15,7 @@ matrix:
 
 before_install:
    - export ALLOW_FAILURE=1; if [ "$TRAVIS_PHP_VERSION" != "hhvm" ] && [ "$TRAVIS_PHP_VERSION" != "nightly" ]; then export ALLOW_FAILURE=0; fi
+   - if [ "$TRAVIS_PHP_VERSION" == "7.2" ]; then yes '' | pecl install mcrypt-1.0.2; fi
 
 install:
   - composer self-update

README.md

@@ -19,7 +19,7 @@ secure version of a credential for storage (rather than storing passwords in "pl
 ## Requirements
 
 - 64-bit PHP runtime (NTLM negotiation bit flags extend beyond the 32-bit integer size)
-- PHP `>=5.4.0`
+- PHP `>=7.1.0`
 
 
 ## Installation
@@ -29,6 +29,71 @@ secure version of a credential for storage (rather than storing passwords in "pl
 3. Include the [Composer autoloader][composer-documentation-autoloading]
 
 
+## Example Usage
+
+```php
+// Using Guzzle
+$client = new Client();
+$request = new Request('get', 'https://my-exchange-url.com');
+$user_name = 'user_name';
+$password = 'password';
+$target_name = 'target_name';
+$host_name = 'host_name';
+
+$encoding_converter = new MbstringEncodingConverter();
+$random_byte_generator = new NativeRandomByteGenerator();
+$hasher_factory = HasherFactory::createWithDetectedSupportedAlgorithms();
+
+$negotiate_message_encoder = new NegotiateMessageEncoder($encoding_converter);
+$challenge_message_decoder = new ChallengeMessageDecoder();
+
+$keyed_hasher_factory = KeyedHasherFactory::createWithDetectedSupportedAlgorithms();
+
+$nt1_hasher = new NtV1Hasher($hasher_factory, $encoding_converter);
+$nt2_hasher = new NtV2Hasher($nt1_hasher, $keyed_hasher_factory, $encoding_converter);
+
+$authenticate_message_encoder = new NtlmV2AuthenticateMessageEncoder(
+    $encoding_converter,
+    $nt2_hasher,
+    $random_byte_generator,
+    $keyed_hasher_factory
+);
+
+$negotiate_message = $negotiate_message_encoder->encode(
+    $target_name,
+    $host_name
+);
+
+// Send negotiate message
+$request->setHeader('Authorization', sprintf('NTLM %s', base64_encode($negotiate_message)));
+$response = $client->send($request);
+
+// Decode returned challenge message
+$authenticate_headers = $response->getHeaderAsArray('WWW-Authenticate');
+foreach ($authenticate_headers as $header_string) {
+    $ntlm_matches = preg_match('/NTLM( (.*))?/', $header_string, $ntlm_header);
+
+    if (0 < $ntlm_matches && isset($ntlm_header[2])) {
+        $raw_server_challenge = base64_decode($ntlm_header[2]);
+        break;
+    }
+}
+$server_challenge = $challenge_message_decoder->decode($raw_server_challenge);
+
+$authenticate_message = $authenticate_message_encoder->encode(
+    $user_name,
+    $target_name,
+    $host_name,
+    new Password($password),
+    $server_challenge
+);
+
+// Send authenticate message
+$request->setHeader('Authorization', sprintf('NTLM %s', base64_encode($authenticate_message)));
+$client->send($request);
+```
+
+
 ## TODO
 
 - [x] LM hashing
@@ -49,8 +114,7 @@ secure version of a credential for storage (rather than storing passwords in "pl
     - [x] Extended session security (NTLM2 session key) support
     - [ ] \(Add-on) Encrypted session key exchange support
 - [ ] Datagram ("connectionless") support
-- [ ] PHP 5.3.x support
-- [ ] Tests... ugh.
+- [ ] Tests
 
 
 ## License
@@ -59,7 +123,7 @@ secure version of a credential for storage (rather than storing passwords in "pl
 
 --------------------------------------------------------------------------------
 
-Copyright 2015 Robin Powered, Inc.
+Copyright 2019 Robin Powered, Inc.
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.

composer.json

@@ -16,7 +16,7 @@
         "source": "https://github.com/robinpowered/php-ntlm"
     },
     "require": {
-        "php-64bit": ">=5.4.0"
+        "php-64bit": ">=7.1.0"
     },
     "require-dev": {
         "ext-mcrypt": "*",

src/Robin/Ntlm/Crypt/Des/McryptDesEncrypter.php

@@ -2,7 +2,7 @@
 /**
  * Robin NTLM
  *
- * @copyright 2015 Robin Powered, Inc.
+ * @copyright 2019 Robin Powered, Inc.
  * @link https://robinpowered.com/
  */
 
@@ -13,6 +13,10 @@
 use Robin\Ntlm\Crypt\Exception\CryptographicFailureException;
 
 /**
+ * @deprecated Mcrypt has been deprecated from the core PHP library. Use
+ * {@see OpenSslDesEncrypter} as an alternative.
+ * @link https://php.net/manual/en/migration72.other-changes.php#migration72.other-changes.mcrypt
+ *
  * An engine used to encrypt data using the DES standard algorithm and
  * implemented using the PHP "mcrypt" extension.
  *

src/Robin/Ntlm/Crypt/Hasher/AbstractHasher.php

@@ -2,12 +2,15 @@
 /**
  * Robin NTLM
  *
- * @copyright 2015 Robin Powered, Inc.
+ * @copyright 2019 Robin Powered, Inc.
  * @link https://robinpowered.com/
  */
 
+declare(strict_types=1);
+
 namespace Robin\Ntlm\Crypt\Hasher;
 
+use HashContext;
 use InvalidArgumentException;
 
 /**
@@ -28,6 +31,7 @@ abstract class AbstractHasher implements HasherInterface
      *
      * @type string
      */
+
     const HASH_CONTEXT_RESOURCE_TYPE = 'Hash Context';
 
 
@@ -39,7 +43,7 @@ abstract class AbstractHasher implements HasherInterface
      * The incremental hashing context.
      *
      * @link http://php.net/manual/en/hash.resources.php
-     * @type resource
+     * @type resource|HashContext
      */
     private $context;
 
@@ -51,7 +55,7 @@ abstract class AbstractHasher implements HasherInterface
     /**
      * Constructor
      *
-     * @param resource $context The incremental hashing context.
+     * @param resource|HashContext $context The incremental hashing context.
      */
     protected function __construct($context)
     {
@@ -61,7 +65,7 @@ protected function __construct($context)
     /**
      * {@inheritDoc}
      */
-    public function update($data)
+    public function update(string $data): HasherInterface
     {
         hash_update($this->context, $data);
 
@@ -71,7 +75,7 @@ public function update($data)
     /**
      * {@inheritDoc}
      */
-    public function digest()
+    public function digest(): string
     {
         // Copy the context so we can keep using the hasher
         $context_copy = hash_copy($this->context);
@@ -90,14 +94,14 @@ public function digest()
      *
      * @link http://php.net/manual/en/hash.resources.php
      * @param mixed $context The context to validate.
-     * @return resource The incremental hashing context.
+     * @return resource|HashContext The incremental hashing context.
      * @throws InvalidArgumentException If the hash context isn't valid.
      */
     protected function validateHashContext($context)
     {
-        if (false === $context
+        if (!($context instanceof HashContext) && (false === $context
             || !is_resource($context)
-            || (is_resource($context) && static::HASH_CONTEXT_RESOURCE_TYPE !== get_resource_type($context))) {
+            || (is_resource($context) && static::HASH_CONTEXT_RESOURCE_TYPE !== get_resource_type($context)))) {
             throw new InvalidArgumentException(
                 'Unable to initialize hashing context. Your system might not support the supplied algorithm.'
             );

src/Robin/Ntlm/Crypt/Hasher/HasherInterface.php

@@ -2,10 +2,12 @@
 /**
  * Robin NTLM
  *
- * @copyright 2015 Robin Powered, Inc.
+ * @copyright 2019 Robin Powered, Inc.
  * @link https://robinpowered.com/
  */
 
+declare(strict_types=1);
+
 namespace Robin\Ntlm\Crypt\Hasher;
 
 /**
@@ -23,12 +25,12 @@ interface HasherInterface
      * @param string $data The data to add.
      * @return $this
      */
-    public function update($data);
+    public function update(string $data): HasherInterface;
 
     /**
      * Calculates the digest of the message.
      *
      * @return string The message digest as a binary string.
      */
-    public function digest();
+    public function digest(): string;
 }