moodle/mod/quiz/accessrule/seb/classes/property_list.php

<?php
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.

/**
 * Wrapper for CFPropertyList to handle low level iteration.
 *
 * @package    quizaccess_seb
 * @author     Andrew Madden <andrewmadden@catalyst-au.net>
 * @copyright  2019 Catalyst IT
 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */

namespace quizaccess_seb;

use CFPropertyList\CFArray;
use CFPropertyList\CFBoolean;
use CFPropertyList\CFData;
use CFPropertyList\CFDate;
use CFPropertyList\CFDictionary;
use CFPropertyList\CFNumber;
use CFPropertyList\CFPropertyList;
use CFPropertyList\CFString;
use CFPropertyList\CFType;
use \Collator;
use \DateTime;


/**
 * Wrapper for CFPropertyList to handle low level iteration.
 *
 * @copyright  2020 Catalyst IT
 * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */
class property_list {

    /** A random 4 character unicode string to replace backslashes during json_encode. */
    private const BACKSLASH_SUBSTITUTE = "ؼҷҍԴ";

    /** @var CFPropertyList $cfpropertylist */
    private $cfpropertylist;

    /**
     * property_list constructor.
     *
     * @param string $xml A Plist XML string.
     */
    public function __construct(string $xml = '') {
        $this->cfpropertylist = new CFPropertyList();

        if (empty($xml)) {
            // If xml not provided, create a blank PList with root dictionary set up.
            $this->cfpropertylist->add(new CFDictionary([]));
        } else {
            // Parse the XML into a PList object.
            $this->cfpropertylist->parse($xml, CFPropertyList::FORMAT_XML);
        }
    }

    /**
     * Add a new element to the root dictionary element.
     *
     * @param string $key Key to assign to new element.
     * @param CFType $element The new element. May be a collection such as an array.
     */
    public function add_element_to_root(string $key, CFType $element) {
        // Get the PList's root dictionary and add new element.
        $this->cfpropertylist->getValue()->add($key, $element);
    }

    /**
     * Get value of element identified by key.
     *
     * @param string $key Key of element.
     * @return mixed Value of element found, or null if none found.
     */
    public function get_element_value(string $key) {
        $result = null;
        $this->plist_map( function($elvalue, $elkey, $parent) use ($key, &$result) {
            // Convert date to iso 8601 if date object.
            if ($key === $elkey) {
                $result = $elvalue->getValue();
            }
        }, $this->cfpropertylist->getValue());

        if (is_array($result)) {
            // Turn CFType elements in PHP elements.
            $result = $this->array_serialize_cftypes($result);
        }
        return $result;
    }

    /**
     * Update the value of any element with matching key.
     *
     * Only allow string, number and boolean elements to be updated.
     *
     * @param string $key Key of element to update.
     * @param mixed $value Value to update element with.
     */
    public function update_element_value(string $key, $value) {
        if (is_array($value)) {
            throw new \invalid_parameter_exception('Use update_element_array to update a collection.');
        }
        $this->plist_map( function($elvalue, $elkey, $parent) use ($key, $value) {
            // Set new value.
            if ($key === $elkey) {
                $element = $parent->get($elkey);
                // Limit update to boolean and strings types, and check value matches expected type.
                if (($element instanceof CFString && is_string($value))
                        || ($element instanceof CFNumber && is_numeric($value))
                        || ($element instanceof CFBoolean && is_bool($value))) {
                    $element->setValue($value);
                } else {
                    throw new \invalid_parameter_exception(
                            'Only string, number and boolean elements can be updated, or value type does not match element type: '
                            . get_class($element));
                }
            }
        }, $this->cfpropertylist->getValue());
    }

    /**
     * Update the array of any dict or array element with matching key.
     *
     * Will replace array.
     *
     * @param string $key Key of element to update.
     * @param array $value Array to update element with.
     */
    public function update_element_array(string $key, array $value) {
        // Validate new array.
        foreach ($value as $element) {
            // If any element is not a CFType instance, then throw exception.
            if (!($element instanceof CFType)) {
                throw new \invalid_parameter_exception('New array must only contain CFType objects.');
            }
        }
        $this->plist_map( function($elvalue, $elkey, $parent) use ($key, $value) {
            if ($key === $elkey) {
                $element = $parent->get($elkey);
                // Replace existing element with new element and array but same key.
                if ($element instanceof CFDictionary) {
                    $parent->del($elkey);
                    $parent->add($elkey, new CFDictionary($value));
                } else if ($element instanceof CFArray) {
                    $parent->del($elkey);
                    $parent->add($elkey, new CFArray($value));
                }
            }
        }, $this->cfpropertylist->getValue());
    }

    /**
     * Delete any element with a matching key.
     *
     * @param string $key Key of element to delete.
     */
    public function delete_element(string $key) {
        $this->plist_map( function($elvalue, $elkey, $parent) use ($key) {
            // Convert date to iso 8601 if date object.
            if ($key === $elkey) {
                $parent->del($key);
            }
        }, $this->cfpropertylist->getValue());
    }

    /**
     * Helper function to either set or update a CF type value to the plist.
     *
     * @param string $key
     * @param CFType $input
     */
    public function set_or_update_value(string $key, CFType $input) {
        $value = $this->get_element_value($key);
        if (empty($value)) {
            $this->add_element_to_root($key, $input);
        } else {
            $this->update_element_value($key, $input->getValue());
        }
    }

    /**
     * Convert the PList to XML.
     *
     * @return string XML ready for creating an XML file.
     */
    public function to_xml() : string {
        return $this->cfpropertylist->toXML();
    }

    /**
     * Return a JSON representation of the PList. The JSON is constructed to be used to generate a SEB Config Key.
     *
     * See the developer documention for SEB for more information on the requirements on generating a SEB Config Key.
     * https://safeexambrowser.org/developer/seb-config-key.html
     *
     * 1. Don't add any whitespace or line formatting to the SEB-JSON string.
     * 2. Don't add character escaping (also backshlashes "\" as found in URL filter rules should not be escaped).
     * 3. All <dict> elements from the plist XML must be ordered (alphabetically sorted) by their key names. Use a
     * recursive method to apply ordering also to nested dictionaries contained in the root-level dictionary and in
     * arrays. Use non-localized (culture invariant), non-ASCII value based case insensitive ordering. For example the
     * key <key>allowWlan</key> comes before <key>allowWLAN</key>. Cocoa/Obj-C and .NET/C# usually use this case
     * insensitive ordering as default, but PHP for example doesn't.
     * 4. Remove empty <dict> elements (key/value). Current versions of SEB clients should anyways not generate empty
     * dictionaries, but this was possible with outdated versions. If config files have been generated that time, such
     * elements might still be around.
     * 5. All string elements must be UTF8 encoded.
     * 6. Base16 strings should use lower-case a-f characters, even though this isn't relevant in the current
     * implementation of the Config Key calculation.
     * 7. <data> plist XML elements must be converted to Base64 strings.
     * 8. <date> plist XML elements must be converted to ISO 8601 formatted strings.
     *
     * @return string A json encoded string.
     */
    public function to_json() : string {
        // Create a clone of the PList, so main list isn't mutated.
        $jsonplist = new CFPropertyList();
        $jsonplist->parse($this->cfpropertylist->toXML(), CFPropertyList::FORMAT_XML);

        // Pass root dict to recursively convert dates to ISO 8601 format, encode strings to UTF-8,
        // lock data to Base 64 encoding and remove empty dictionaries.
        $this->prepare_plist_for_json_encoding($jsonplist->getValue());

        // Serialize PList to array.
        $plistarray = $jsonplist->toArray();

        // Sort array alphabetically by key using case insensitive, natural sorting. See point 3 for more information.
        $plistarray = $this->array_sort($plistarray);

        // Encode in JSON with following rules from SEB docs.
        // 1. Don't add any whitespace or line formatting to the SEB-JSON string.
        // 2. Don't add unicode or slash escaping.
        $json = json_encode($plistarray, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE );

        // There is no way to prevent json_encode from escaping backslashes. We replace each backslash with a unique string
        // prior to encoding in prepare_plist_for_json_encoding(). We can then replace the substitute with a single backslash.
        $json = str_replace(self::BACKSLASH_SUBSTITUTE, "\\", $json);
        return $json;
    }

    /**
     * Recursively convert PList date values from unix to iso 8601 format, and ensure strings are UTF 8 encoded.
     *
     * This will mutate the PList.
     */

    /**
     * Recursively convert PList date values from unix to iso 8601 format, and ensure strings are UTF 8 encoded.
     *
     * This will mutate the PList.
     * @param \Iterator $root The root element of the PList. Must be a dictionary or array.
     */
    private function prepare_plist_for_json_encoding($root) {
        $this->plist_map( function($value, $key, $parent) {
            // Convert date to ISO 8601 if date object.
            if ($value instanceof CFDate) {
                $date = DateTime::createFromFormat('U', $value->getValue());
                $date->setTimezone(new \DateTimeZone('UTC')); // Zulu timezone a.k.a. UTC+00.
                $isodate = $date->format('c');
                $value->setValue($isodate);
            }
            // Make sure strings are UTF 8 encoded.
            if ($value instanceof CFString) {
                // As literal backslashes will be lost during encoding, we must replace them with a unique substitute to be
                // reverted after JSON encoding.
                $string = str_replace("\\", self::BACKSLASH_SUBSTITUTE, $value->getValue());
                $value->setValue(mb_convert_encoding($string, 'UTF-8'));
            }
            // Data should remain base 64 encoded, so convert to base encoded string for export. Otherwise
            // CFData will decode the data when serialized.
            if ($value instanceof CFData) {
                $data = trim($value->getCodedValue());
                $parent->del($key);
                $parent->add($key, new CFString($data));
            }
            // Empty dictionaries should be removed.
            if ($value instanceof CFDictionary && empty($value->getValue())) {
                $parent->del($key);
            }
        }, $root);

    }

    /**
     * Iterate through the PList elements, and call the callback on each.
     *
     * @param callable $callback A callback function called for every element.
     * @param \Iterator $root The root element of the PList. Must be a dictionary or array.
     * @param bool $recursive Whether the function should traverse dicts and arrays recursively.
     */
    private function plist_map(callable $callback, \Iterator $root, bool $recursive = true) {
        $root->rewind();
        while ($root->valid()) {
            $value = $root->current();
            $key = $root->key();

            // Recursively traverse all dicts and arrays if flag is true.
            if ($recursive && $value instanceof \Iterator) {
                $this->plist_map($callback, $value);
            }

            // Callback function called for every element.
            $callback($value, $key, $root);

            $root->next();
        }
    }

    /**
     * Recursively sort array alphabetically by key.
     *
     * @link https://safeexambrowser.org/developer/seb-config-key.html
     *
     * @param array $array Top level array to process.
     * @return array Processed array.
     */
    private function array_sort(array $array) {
        foreach ($array as $key => $value) {
            if (is_array($value)) {
                $array[$key] = $this->array_sort($array[$key]);
            }
        }
        // Sort assoc array. From SEB docs:
        //
        // All <dict> elements from the plist XML must be ordered (alphabetically sorted) by their key names. Use
        // a recursive method to apply ordering also to nested dictionaries contained in the root-level dictionary
        // and in arrays. Use non-localized (culture invariant), non-ASCII value based case insensitive ordering.
        // For example the key <key>allowWlan</key> comes before <key>allowWLAN</key>. Cocoa/Obj-C and .NET/C#
        // usually use this case insensitive ordering as default, but PHP for example doesn't.
        if ($this->is_associative_array($array)) {
            // Note this is a pragmatic solution as none of the native PHP *sort method appear to sort strings that
            // differ only in case (e.g. ["allowWLAN", "allowWlan"] is expected to have the lower version first).
            $keys = array_keys($array);
            (new Collator('root'))->asort($keys); // Use Unicode Collation Algorithm (UCA).
            $original = $array;
            $array = [];
            foreach ($keys as $key) {
                $array[$key] = $original[$key];
            }
        }

        return $array;
    }

    /**
     * Recursively remove empty arrays.
     *
     * @param array $array Top level array to process.
     * @return array Processed array.
     */
    private function array_remove_empty_arrays(array $array) {
        foreach ($array as $key => $value) {
            if (is_array($value)) {
                $array[$key] = $this->array_remove_empty_arrays($array[$key]);
            }

            // Remove empty arrays.
            if (is_array($array[$key]) && empty($array[$key])) {
                unset($array[$key]);
            }
        }

        return $array;
    }

    /**
     * If an array contains CFType objects, wrap array in a CFDictionary to allow recursive serialization of data
     * into a standard PHP array.
     *
     * @param array $array Array containing CFType objects.
     * @return array Standard PHP array.
     */
    private function array_serialize_cftypes(array $array) : array {
        $array = new CFDictionary($array); // Convert back to CFDictionary so serialization is recursive.
        return $array->toArray(); // Serialize.
    }

    /**
     * Check if an array is associative or sequential.
     *
     * @param array $array Array to check.
     * @return bool False if not associative.
     */
    private function is_associative_array(array $array) {
        if (empty($array)) {
            return false;
        }
        // Check that all keys are not sequential integers starting from 0 (Which is what PHP arrays have behind the scenes.)
        return array_keys($array) !== range(0, count($array) - 1);
    }
}