Code Review; minor changes to salt handling, corrected some comments

Author: Lenz Weber

src/PhpWord/Metadata/Protection.php

@@ -34,7 +34,7 @@ class Protection
     private $editing;
 
     /**
-     * Hashed password
+     * password
      *
      * @var string
      */
@@ -55,7 +55,7 @@ class Protection
     private $mswordAlgorithmSid = 4;
 
     /**
-     * Hashed salt
+     * salt
      *
      * @var string
      */
@@ -95,7 +95,7 @@ public function setEditing($editing = null)
     }
 
     /**
-     * Get password hash
+     * Get password
      *
      * @return string
      */
@@ -164,7 +164,7 @@ public function setMswordAlgorithmSid($mswordAlgorithmSid)
     }
 
     /**
-     * Get salt hash
+     * Get salt
      *
      * @return string
      */
@@ -174,13 +174,18 @@ public function getSalt()
     }
 
     /**
-     * Set salt hash
+     * Set salt. Salt HAS to be 16 characters, or an exception will be thrown.
      *
      * @param $salt
      * @return self
+     * @throws \InvalidArgumentException
      */
     public function setSalt($salt)
     {
+        if ($salt !== null && strlen($salt) !== 16){
+            throw new \InvalidArgumentException('salt has to be of exactly 16 bytes length');
+        }
+
         $this->salt = $salt;
 
         return $this;

src/PhpWord/Writer/Word2007/Part/Settings.php

@@ -225,8 +225,8 @@ private function getProtection()
                         'w:cryptAlgorithmType' => 'typeAny',
                         'w:cryptAlgorithmSid' => $protection->getMswordAlgorithmSid(),
                         'w:cryptSpinCount' => $protection->getSpinCount(),
-                        'w:hash' => $this->getPasswordHash($protection),
-                        'w:salt' => $this->getSaltHash($protection->getSalt()),
+                        'w:hash' => $this->getEncodedPasswordHash($protection),
+                        'w:salt' => base64_encode($protection->getSalt()),
                     )
                 );
             }
@@ -255,19 +255,19 @@ private function getCompatibility()
 
     /**
      * Create a hashed password that MS Word will be able to work with
+     * @link https://blogs.msdn.microsoft.com/vsod/2010/04/05/how-to-set-the-editing-restrictions-in-word-using-open-xml-sdk-2-0/
      *
      * @param \PhpOffice\PhpWord\Metadata\Protection $protection
      * @return string
      */
-    private function getPasswordHash($protection)
+    private function getEncodedPasswordHash($protection)
     {
         $orig_encoding = mb_internal_encoding();
         mb_internal_encoding("UTF-8");
 
         $password = $protection->getPassword();
         $password = mb_substr($password, 0, min(self::$passwordMaxLength, mb_strlen($password)));
 
-        // Construct a new NULL-terminated string consisting of single-byte characters:
         //   Get the single-byte values by iterating through the Unicode characters of the truncated password.
         //   For each character, if the low byte is not equal to 0, take it. Otherwise, take the high byte.
         $pass_utf8 = mb_convert_encoding($password, 'UCS-2LE', 'UTF-8');
@@ -291,7 +291,7 @@ private function getPasswordHash($protection)
         //   Word requires that the initial hash of the password with the salt not be considered in the count.
         //   The initial hash of salt + key is not included in the iteration count.
         $algorithm    = $this->getAlgorithm($protection->getMswordAlgorithmSid());
-        $generatedKey = hash($algorithm, base64_decode($this->getSaltHash($protection->getSalt())) . $generatedKey, true);
+        $generatedKey = hash($algorithm, $protection->getSalt() . $generatedKey, true);
 
         for ($i = 0; $i < $protection->getSpinCount(); $i++) {
             $generatedKey = hash($algorithm, $generatedKey . pack("CCCC", $i, $i >> 8, $i >> 16, $i >> 24), true);
@@ -319,17 +319,6 @@ private function getAlgorithm($sid)
         return $algorithm;
     }
 
-    /**
-     * Get salt hash
-     *
-     * @param string $salt
-     * @return string
-     */
-    private function getSaltHash($salt)
-    {
-        return base64_encode(str_pad(substr($salt, 0, 16), 16, '1'));
-    }
-
     /**
      * Build combined key from low-order word and high-order word
      *
@@ -372,7 +361,7 @@ private function buildCombinedKey($byteChars)
     }
 
     /**
-     * Simulate behaviour of int32
+     * Simulate behaviour of (signed) int32
      *
      * @param int $value
      * @return int