move password encoding in separate class

fix PHPCS errors
add documentation
add sample

docs/general.rst

@@ -271,3 +271,14 @@ points to twips.
  $sectionStyle->setMarginLeft(\PhpOffice\PhpWord\Shared\Converter::inchToTwip(.5));
  // 2 cm right margin
  $sectionStyle->setMarginRight(\PhpOffice\PhpWord\Shared\Converter::cmToTwip(2));
+
+Document protection
+-------------------
+
+The document (or parts of it) can be password protected.
+
+.. code-block:: php
+
+ $documentProtection = $phpWord->getSettings()->getDocumentProtection();
+ $documentProtection->setEditing(DocProtect::READ_ONLY);
+ $documentProtection->setPassword('myPassword');

samples/Sample_38_Protection.php

@@ -0,0 +1,21 @@
+<?php
+use PhpOffice\PhpWord\SimpleType\DocProtect;
+
+include_once 'Sample_Header.php';
+
+// New Word Document
+echo date('H:i:s') , ' Create new PhpWord object' , EOL;
+$phpWord = new \PhpOffice\PhpWord\PhpWord();
+
+$documentProtection = $phpWord->getSettings()->getDocumentProtection();
+$documentProtection->setEditing(DocProtect::READ_ONLY);
+$documentProtection->setPassword('myPassword');
+
+$section = $phpWord->addSection();
+$section->addText('this document is password protected');
+
+// Save file
+echo write($phpWord, basename(__FILE__, '.php'), $writers);
+if (!CLI) {
+ include_once 'Sample_Footer.php';
+}

src/PhpWord/Metadata/Protection.php

@@ -17,6 +17,8 @@
 
 namespace PhpOffice\PhpWord\Metadata;
 
+use PhpOffice\PhpWord\SimpleType\DocProtect;
+
 /**
  * Document protection class
  *
@@ -38,28 +40,28 @@ class Protection
  *
  * @var string
  */
- private $password = '';
+ private $password;
 
  /**
- * Number of hashing iterations
+ * Iterations to Run Hashing Algorithm
  *
  * @var int
  */
  private $spinCount = 100000;
 
  /**
- * Algorithm-SID (see to \PhpOffice\PhpWord\Writer\Word2007\Part\Settings::$algorithmMapping)
+ * Cryptographic Hashing Algorithm (see to \PhpOffice\PhpWord\Writer\Word2007\Part\Settings::$algorithmMapping)
  *
  * @var int
  */
  private $mswordAlgorithmSid = 4;
 
  /**
- * salt
+ * Salt for Password Verifier
  *
  * @var string
  */
- private $salt = '';
+ private $salt;
 
  /**
  * Create a new instance
@@ -68,7 +70,9 @@ class Protection
  */
  public function __construct($editing = null)
  {
- $this->setEditing($editing);
+ if ($editing != null) {
+ $this->setEditing($editing);
+ }
  }
 
  /**
@@ -84,11 +88,12 @@ public function getEditing()
  /**
  * Set editing protection
  *
- * @param string $editing
+ * @param string $editing Any value of \PhpOffice\PhpWord\SimpleType\DocProtect
  * @return self
  */
  public function setEditing($editing = null)
  {
+ DocProtect::validate($editing);
  $this->editing = $editing;
 
  return $this;
@@ -177,12 +182,12 @@ public function getSalt()
  * Set salt. Salt HAS to be 16 characters, or an exception will be thrown.
  *
  * @param $salt
- * @return self
  * @throws \InvalidArgumentException
+ * @return self
  */
  public function setSalt($salt)
  {
- if ($salt !== null && strlen($salt) !== 16){
+ if ($salt !== null && strlen($salt) !== 16) {
  throw new \InvalidArgumentException('salt has to be of exactly 16 bytes length');
  }
 

src/PhpWord/Shared/Microsoft/PasswordEncoder.php

@@ -0,0 +1,205 @@
+<?php
+/**
+ * This file is part of PHPWord - A pure PHP library for reading and writing
+ * word processing documents.
+ *
+ * PHPWord is free software distributed under the terms of the GNU Lesser
+ * General Public License version 3 as published by the Free Software Foundation.
+ *
+ * For the full copyright and license information, please read the LICENSE
+ * file that was distributed with this source code. For the full list of
+ * contributors, visit https://github.com/PHPOffice/PHPWord/contributors.
+ *
+ * @see https://github.com/PHPOffice/PHPWord
+ * @copyright 2010-2017 PHPWord contributors
+ * @license https://www.gnu.org/licenses/lgpl.txt LGPL version 3
+ */
+
+namespace PhpOffice\PhpWord\Shared\Microsoft;
+
+/**
+ * Password encoder for microsoft office applications
+ */
+class PasswordEncoder
+{
+ private static $algorithmMapping = array(
+ 1 => 'md2',
+ 2 => 'md4',
+ 3 => 'md5',
+ 4 => 'sha1',
+ 5 => '', // 'mac' -> not possible with hash()
+ 6 => 'ripemd',
+ 7 => 'ripemd160',
+ 8 => '',
+ 9 => '', //'hmac' -> not possible with hash()
+ 10 => '',
+ 11 => '',
+ 12 => 'sha256',
+ 13 => 'sha384',
+ 14 => 'sha512',
+ );
+
+ private static $initialCodeArray = array(
+ 0xE1F0,
+ 0x1D0F,
+ 0xCC9C,
+ 0x84C0,
+ 0x110C,
+ 0x0E10,
+ 0xF1CE,
+ 0x313E,
+ 0x1872,
+ 0xE139,
+ 0xD40F,
+ 0x84F9,
+ 0x280C,
+ 0xA96A,
+ 0x4EC3,
+ );
+
+ private static $encryptionMatrix = array(
+ array(0xAEFC, 0x4DD9, 0x9BB2, 0x2745, 0x4E8A, 0x9D14, 0x2A09),
+ array(0x7B61, 0xF6C2, 0xFDA5, 0xEB6B, 0xC6F7, 0x9DCF, 0x2BBF),
+ array(0x4563, 0x8AC6, 0x05AD, 0x0B5A, 0x16B4, 0x2D68, 0x5AD0),
+ array(0x0375, 0x06EA, 0x0DD4, 0x1BA8, 0x3750, 0x6EA0, 0xDD40),
+ array(0xD849, 0xA0B3, 0x5147, 0xA28E, 0x553D, 0xAA7A, 0x44D5),
+ array(0x6F45, 0xDE8A, 0xAD35, 0x4A4B, 0x9496, 0x390D, 0x721A),
+ array(0xEB23, 0xC667, 0x9CEF, 0x29FF, 0x53FE, 0xA7FC, 0x5FD9),
+ array(0x47D3, 0x8FA6, 0x0F6D, 0x1EDA, 0x3DB4, 0x7B68, 0xF6D0),
+ array(0xB861, 0x60E3, 0xC1C6, 0x93AD, 0x377B, 0x6EF6, 0xDDEC),
+ array(0x45A0, 0x8B40, 0x06A1, 0x0D42, 0x1A84, 0x3508, 0x6A10),
+ array(0xAA51, 0x4483, 0x8906, 0x022D, 0x045A, 0x08B4, 0x1168),
+ array(0x76B4, 0xED68, 0xCAF1, 0x85C3, 0x1BA7, 0x374E, 0x6E9C),
+ array(0x3730, 0x6E60, 0xDCC0, 0xA9A1, 0x4363, 0x86C6, 0x1DAD),
+ array(0x3331, 0x6662, 0xCCC4, 0x89A9, 0x0373, 0x06E6, 0x0DCC),
+ array(0x1021, 0x2042, 0x4084, 0x8108, 0x1231, 0x2462, 0x48C4),
+ );
+
+ private static $passwordMaxLength = 15;
+
+ /**
+ * Create a hashed password that MS Word will be able to work with
+ * @see https://blogs.msdn.microsoft.com/vsod/2010/04/05/how-to-set-the-editing-restrictions-in-word-using-open-xml-sdk-2-0/
+ *
+ * @param string $password
+ * @param number $algorithmSid
+ * @param string $salt
+ * @param number $spinCount
+ * @return string
+ */
+ public static function hashPassword($password, $algorithmSid = 4, $salt = null, $spinCount = 10000)
+ {
+ $origEncoding = mb_internal_encoding();
+ mb_internal_encoding('UTF-8');
+
+ $password = mb_substr($password, 0, min(self::$passwordMaxLength, mb_strlen($password)));
+
+ // 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.
+ $passUtf8 = mb_convert_encoding($password, 'UCS-2LE', 'UTF-8');
+ $byteChars = array();
+ for ($i = 0; $i < mb_strlen($password); $i++) {
+ $byteChars[$i] = ord(substr($passUtf8, $i * 2, 1));
+ if ($byteChars[$i] == 0) {
+ $byteChars[$i] = ord(substr($passUtf8, $i * 2 + 1, 1));
+ }
+ }
+
+ // build low-order word and hig-order word and combine them
+ $combinedKey = self::buildCombinedKey($byteChars);
+ // build reversed hexadecimal string
+ $hex = str_pad(strtoupper(dechex($combinedKey & 0xFFFFFFFF)), 8, '0', \STR_PAD_LEFT);
+ $reversedHex = $hex[6] . $hex[7] . $hex[4] . $hex[5] . $hex[2] . $hex[3] . $hex[0] . $hex[1];
+
+ $generatedKey = mb_convert_encoding($reversedHex, 'UCS-2LE', 'UTF-8');
+
+ // Implementation Notes List:
+ // 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 = self::getAlgorithm($algorithmSid);
+ $generatedKey = hash($algorithm, $salt . $generatedKey, true);
+
+ for ($i = 0; $i < $spinCount; $i++) {
+ $generatedKey = hash($algorithm, $generatedKey . pack('CCCC', $i, $i >> 8, $i >> 16, $i >> 24), true);
+ }
+ $generatedKey = base64_encode($generatedKey);
+
+ mb_internal_encoding($origEncoding);
+
+ return $generatedKey;
+ }
+
+ /**
+ * Get algorithm from self::$algorithmMapping
+ *
+ * @param int $sid
+ * @return string
+ */
+ private static function getAlgorithm($sid)
+ {
+ $algorithm = self::$algorithmMapping[$sid];
+ if ($algorithm == '') {
+ $algorithm = 'sha1';
+ }
+
+ return $algorithm;
+ }
+
+ /**
+ * Build combined key from low-order word and high-order word
+ *
+ * @param array $byteChars byte array representation of password
+ * @return int
+ */
+ private static function buildCombinedKey($byteChars)
+ {
+ // Compute the high-order word
+ // Initialize from the initial code array (see above), depending on the passwords length.
+ $highOrderWord = self::$initialCodeArray[count($byteChars) - 1];
+
+ // For each character in the password:
+ // For every bit in the character, starting with the least significant and progressing to (but excluding)
+ // the most significant, if the bit is set, XOR the key’s high-order word with the corresponding word from
+ // the Encryption Matrix
+ for ($i = 0; $i < count($byteChars); $i++) {
+ $tmp = self::$passwordMaxLength - count($byteChars) + $i;
+ $matrixRow = self::$encryptionMatrix[$tmp];
+ for ($intBit = 0; $intBit < 7; $intBit++) {
+ if (($byteChars[$i] & (0x0001 << $intBit)) != 0) {
+ $highOrderWord = ($highOrderWord ^ $matrixRow[$intBit]);
+ }
+ }
+ }
+
+ // Compute low-order word
+ // Initialize with 0
+ $lowOrderWord = 0;
+ // For each character in the password, going backwards
+ for ($i = count($byteChars) - 1; $i >= 0; $i--) {
+ // low-order word = (((low-order word SHR 14) AND 0x0001) OR (low-order word SHL 1) AND 0x7FFF)) XOR character
+ $lowOrderWord = (((($lowOrderWord >> 14) & 0x0001) | (($lowOrderWord << 1) & 0x7FFF)) ^ $byteChars[$i]);
+ }
+ // Lastly, low-order word = (((low-order word SHR 14) AND 0x0001) OR (low-order word SHL 1) AND 0x7FFF)) XOR strPassword length XOR 0xCE4B.
+ $lowOrderWord = (((($lowOrderWord >> 14) & 0x0001) | (($lowOrderWord << 1) & 0x7FFF)) ^ count($byteChars) ^ 0xCE4B);
+
+ // Combine the Low and High Order Word
+ return self::int32(($highOrderWord << 16) + $lowOrderWord);
+ }
+
+ /**
+ * Simulate behaviour of (signed) int32
+ *
+ * @param int $value
+ * @return int
+ */
+ private static function int32($value)
+ {
+ $value = ($value & 0xFFFFFFFF);
+
+ if ($value & 0x80000000) {
+ $value = -((~$value & 0xFFFFFFFF) + 1);
+ }
+
+ return $value;
+ }
+}

src/PhpWord/SimpleType/DocProtect.php

@@ -0,0 +1,55 @@
+<?php
+/**
+ * This file is part of PHPWord - A pure PHP library for reading and writing
+ * word processing documents.
+ *
+ * PHPWord is free software distributed under the terms of the GNU Lesser
+ * General Public License version 3 as published by the Free Software Foundation.
+ *
+ * For the full copyright and license information, please read the LICENSE
+ * file that was distributed with this source code. For the full list of
+ * contributors, visit https://github.com/PHPOffice/PHPWord/contributors.
+ *
+ * @see https://github.com/PHPOffice/PHPWord
+ * @copyright 2010-2017 PHPWord contributors
+ * @license https://www.gnu.org/licenses/lgpl.txt LGPL version 3
+ */
+
+namespace PhpOffice\PhpWord\SimpleType;
+
+use PhpOffice\PhpWord\Shared\AbstractEnum;
+
+/**
+ * Document Protection Types
+ *
+ * @since 0.14.0
+ *
+ * @see https://www.datypic.com/sc/ooxml/t-w_ST_DocProtect.html
+ */
+final class DocProtect extends AbstractEnum
+{
+ /**
+ * No Editing Restrictions
+ */
+ const NONE = 'none';
+
+ /**
+ * Allow No Editing
+ */
+ const READ_ONLY = 'readOnly';
+
+ /**
+ * Allow Editing of Comments
+ */
+ const COMMENTS = 'comments';
+
+ /**
+ * Allow Editing With Revision Tracking
+ */
+ const TRACKED_CHANGES = 'trackedChanges';
+
+ /**
+ * Allow Editing of Form Fields
+ */
+ const FORMS = 'forms';
+}