diff --git a/tuf/repository_tool.py b/tuf/repository_tool.py index 5527de04..b1a7f9c3 100755 --- a/tuf/repository_tool.py +++ b/tuf/repository_tool.py @@ -462,7 +462,7 @@ def unmark_dirty(self, roles): @staticmethod def get_filepaths_in_directory(files_directory, recursive_walk=False, - followlinks=True): + followlinks=True): """ Walk the given 'files_directory' and build a list of target files found. @@ -1789,8 +1789,8 @@ def add_paths(self, paths, child_rolename): 'Django' in 'unclaimed'). - securesystemslib.exceptions.Error, if a delegated path in 'paths' is not - a string path, or if 'child_rolename' has not been delegated yet. + securesystemslib.exceptions.Error, if a path or glob pattern in 'paths' + is not a string, or if 'child_rolename' has not been delegated yet. Modifies this Targets' delegations field. @@ -1806,8 +1806,8 @@ def add_paths(self, paths, child_rolename): securesystemslib.formats.PATHS_SCHEMA.check_match(paths) tuf.formats.ROLENAME_SCHEMA.check_match(child_rolename) - # A list of relative and verified paths to be added to the child role's - # entry in the parent's delegations field. + # A list of relative and verified paths or glob patterns to be added to the + # child role's entry in the parent's delegations field. relative_paths = [] # Ensure that 'child_rolename' exists, otherwise it will not have an entry @@ -1817,11 +1817,14 @@ def add_paths(self, paths, child_rolename): ' not exist.') for path in paths: - # Do the delegated paths fall under the repository's targets directory? - # Append a trailing path separator with os.path.join(path, ''). + # Are the delegated paths or glob patterns located in the repository's + # targets directory? If so, log it - the paths don't necessarily need to + # be located in the repository's directory. + # Append a trailing path separator with + # os.path.join(path, ''). targets_directory = os.path.join(self._targets_directory, '') if not path.startswith(targets_directory): - logger.debug(repr(path) + ' does not live under the' + logger.debug(repr(path) + ' is not located in the' ' repository\'s targets' ' directory: ' + repr(self._targets_directory)) @@ -1851,8 +1854,8 @@ def add_paths(self, paths, child_rolename): def add_target(self, filepath, custom=None): """ - Add a filepath (must be under the repository's targets directory) to the - Targets object. + Add a filepath (must be located in the repository's targets directory) to + the Targets object. This method does not actually create 'filepath' on the file system. 'filepath' must already exist on the file system. If 'filepath' @@ -1875,7 +1878,7 @@ def add_target(self, filepath, custom=None): securesystemslib.exceptions.FormatError, if 'filepath' is improperly formatted. - securesystemslib.exceptions.Error, if 'filepath' is not found under the + securesystemslib.exceptions.Error, if 'filepath' is not located in the repository's targets directory. @@ -1899,10 +1902,10 @@ def add_target(self, filepath, custom=None): filepath = os.path.abspath(filepath) - # Ensure 'filepath' is found under the repository's targets directory. + # Ensure 'filepath' is located in the repository's targets directory. if not filepath.startswith(self._targets_directory): - raise securesystemslib.exceptions.Error(repr(filepath) + ' does not exist' - ' under the repository\'s targets directory:' + raise securesystemslib.exceptions.Error(repr(filepath) + ' is not located' + ' in the repository\'s targets directory:' ' ' + repr(self._targets_directory)) # Add 'filepath' (i.e., relative to the targets directory) to the role's @@ -1956,8 +1959,8 @@ def add_targets(self, list_of_targets): formatted. securesystemslib.exceptions.Error, if any of the paths listed in - 'list_of_targets' is not found under the repository's targets directory - or is invalid. + 'list_of_targets' is not located in the repository's targets directory or + is invalid. This Targets' roleinfo is updated with the paths in 'list_of_targets'. @@ -1976,18 +1979,18 @@ def add_targets(self, list_of_targets): targets_directory_length = len(self._targets_directory) relative_list_of_targets = [] - # Ensure the paths in 'list_of_targets' are valid and fall under the + # Ensure the paths in 'list_of_targets' are valid and are located in the # repository's targets directory. The paths of 'list_of_targets' will be # verified as allowed paths according to this Targets parent role when - # write() is called. Not verifying filepaths here allows the freedom to add - # targets and parent restrictions in any order, and minimize the number of - # times these checks are performed. + # write() or writeall() is called. Not verifying filepaths here allows the + # freedom to add targets and parent restrictions in any order, and minimize + # the number of times these checks are performed. for target in list_of_targets: filepath = os.path.abspath(target) if not filepath.startswith(self._targets_directory+os.sep): raise securesystemslib.exceptions.Error(repr(filepath) + ' is not' - ' under the Repository\'s targets' + ' located in the Repository\'s targets' ' directory: ' + repr(self._targets_directory)) if os.path.isfile(filepath): @@ -2031,7 +2034,7 @@ def remove_target(self, filepath): securesystemslib.exceptions.FormatError, if 'filepath' is improperly formatted. - securesystemslib.exceptions.Error, if 'filepath' is not under the + securesystemslib.exceptions.Error, if 'filepath' is not located in the repository's targets directory, or not found. @@ -2050,10 +2053,10 @@ def remove_target(self, filepath): filepath = os.path.abspath(filepath) targets_directory_length = len(self._targets_directory) - # Ensure 'filepath' is under the repository targets directory. + # Ensure 'filepath' is located in the repository targets directory. if not filepath.startswith(self._targets_directory + os.sep): - raise securesystemslib.exceptions.Error(repr(filepath) + ' is not under' - ' the Repository\'s targets directory: ' + repr(self._targets_directory)) + raise securesystemslib.exceptions.Error(repr(filepath) + ' is not located' + ' in the Repository\'s targets directory: ' + repr(self._targets_directory)) # The relative filepath is listed in 'paths'. relative_filepath = filepath[targets_directory_length:] @@ -2155,9 +2158,9 @@ def delegate(self, rolename, public_keys, paths, threshold=1, ED25519KEY_SCHEMA, etc. paths: - The delegated paths, or glob patterns, for 'rolename'. Any - target paths added to 'rolename' must match one of the glob patterns - in 'paths'. + The paths, or glob patterns, delegated to 'rolename'. Any targets + added to 'rolename' must match one of the paths or glob patterns in + 'paths'. threshold: The threshold number of keys of 'rolename'. @@ -2176,8 +2179,8 @@ def delegate(self, rolename, public_keys, paths, threshold=1, list_of_targets: A list of target filepaths that are added to the paths of 'rolename'. 'list_of_targets' is a list of target filepaths, can be empty, and each - filepath must full under the repository's targets directory. The list - of targets should also exist at the specified paths, otherwise + filepath must be located in the repository's targets directory. The + list of targets should also exist at the specified paths, otherwise non-existent target paths might not be added when the targets file is written to disk with writeall() or write(). @@ -2191,9 +2194,9 @@ def delegate(self, rolename, public_keys, paths, threshold=1, securesystemslib.exceptions.FormatError, if any of the arguments are improperly formatted. - securesystemslib.exceptions.Error, if the delegated role already exists or - if any of the arguments is an invalid path (i.e., not under the - repository's targets directory). + securesystemslib.exceptions.Error, if the delegated role already exists + or if any target in 'list_of_targets' is an invalid path (i.e., not + located in the repository's targets directory). A new Target object is created for 'rolename' that is accessible to the @@ -2241,8 +2244,8 @@ def delegate(self, rolename, public_keys, paths, threshold=1, keydict.update(new_keydict) keyids.append(keyid) - # Ensure the paths of 'list_of_targets' all fall under the repository's - # targets. + # Ensure the paths of 'list_of_targets' are located in the repository's + # targets directory. relative_targetpaths = {} targets_directory_length = len(self._targets_directory) @@ -2250,20 +2253,20 @@ def delegate(self, rolename, public_keys, paths, threshold=1, for target in list_of_targets: target = os.path.abspath(target) if not target.startswith(self._targets_directory + os.sep): - raise securesystemslib.exceptions.Error(repr(target) + ' is not under' - ' the repository\'s targets' + raise securesystemslib.exceptions.Error(repr(target) + ' is not' + ' located in the repository\'s targets' ' directory: ' + repr(self._targets_directory)) relative_targetpaths.update({target[targets_directory_length:]: {}}) - # Verify whether each path in 'paths' falls under the repository's targets - # directory. + # Verify whether each path in 'paths' is located in the repository's + # targets directory. relative_paths = [] if paths is not None: for path in paths: if not path.startswith(self._targets_directory + os.sep): - logger.debug(repr(path) + ' is not under the repository\'s targets' + logger.debug(repr(path) + ' is not loated in the repository\'s targets' ' directory: ' + repr(self._targets_directory)) # Append a trailing path separator with os.path.join(path, ''). @@ -2439,7 +2442,7 @@ def delegate_hashed_bins(self, list_of_targets, keys_of_hashed_bins, formatted. securesystemslib.exceptions.Error, if 'number_of_bins' is not a power of - 2, or one of the targets in 'list_of_targets' is not located under the + 2, or one of the targets in 'list_of_targets' is not located in the repository's targets directory. @@ -2489,17 +2492,17 @@ def delegate_hashed_bins(self, list_of_targets, keys_of_hashed_bins, for bin_index in six.moves.xrange(total_hash_prefixes): target_paths_in_bin[bin_index] = [] - # Assign every path to its bin. Ensure every target is located under the + # Assign every path to its bin. Ensure every target is located in the # repository's targets directory. for target_path in list_of_targets: target_path = os.path.abspath(target_path) if not target_path.startswith(self._targets_directory + os.sep): raise securesystemslib.exceptions.Error('A path in "list of' - ' targets" does not live under the repository\'s targets' + ' targets" is not located in the repository\'s targets' ' directory: ' + repr(target_path)) else: - logger.debug(repr(target_path) + ' lives under the repository\'s' + logger.debug(repr(target_path) + ' is located in the repository\'s' ' targets directory.') # Determine the hash prefix of 'target_path' by computing the digest of @@ -2566,19 +2569,19 @@ def delegate_hashed_bins(self, list_of_targets, keys_of_hashed_bins, def add_target_to_bin(self, target_filepath): """ - Add the fileinfo of 'target_filepath' to the expected hashed bin, if - the bin is available. The hashed bin should have been created by - {targets_role}.delegate_hashed_bins(). Assuming the target filepath - falls under the repository's targets directory, determine the filepath's + Add the fileinfo of 'target_filepath' to the expected hashed bin, if the + bin is available. The hashed bin should have been created by + {targets_role}.delegate_hashed_bins(). Assuming the target filepath is + located in the repository's targets directory, determine the filepath's hash prefix, locate the expected bin (if any), and then add the fileinfo - to the expected bin. Example: 'targets/foo.tar.gz' may be added to - the 'targets/unclaimed/58-5f.json' role's list of targets by calling this + to the expected bin. Example: 'targets/foo.tar.gz' may be added to the + 'targets/unclaimed/58-5f.json' role's list of targets by calling this method. target_filepath: The filepath of the target to be added to a hashed bin. The filepath - must fall under repository's targets directory. + must be located in the repository's targets directory. securesystemslib.exceptions.FormatError, if 'target_filepath' is @@ -2611,17 +2614,17 @@ def remove_target_from_bin(self, target_filepath): Remove the fileinfo of 'target_filepath' from the expected hashed bin, if the bin is available. The hashed bin should have been created by - {targets_role}.delegate_hashed_bins(). Assuming the target filepath - falls under the repository's targets directory, determine the filepath's + {targets_role}.delegate_hashed_bins(). Assuming the target filepath is + located in the repository's targets directory, determine the filepath's hash prefix, locate the expected bin (if any), and then remove the fileinfo from the expected bin. Example: 'targets/foo.tar.gz' may be - removed from the '58-5f.json' role's list of targets by - calling this method. + removed from the '58-5f.json' role's list of targets by calling this + method. target_filepath: The filepath of the target to be added to a hashed bin. The filepath - must fall under repository's targets directory. + must be located in the repository's targets directory. securesystemslib.exceptions.FormatError, if 'target_filepath' is @@ -2652,7 +2655,7 @@ def remove_target_from_bin(self, target_filepath): def _locate_and_update_target_in_bin(self, target_filepath, method_name): """ - Assuming the target filepath falls under the repository's targets + Assuming the target filepath are located in the repository's targets directory, determine the filepath's hash prefix, locate the expected bin (if any), and then call the 'method_name' method of the expected hashed bin role. @@ -2660,7 +2663,8 @@ def _locate_and_update_target_in_bin(self, target_filepath, method_name): target_filepath: The filepath of the target that may be specified in one of the hashed - bins. 'target_filepath' must fall under repository's targets directory. + bins. 'target_filepath' must be located in the repository's targets + directory. method_name: A supported method, in string format, of the Targets() class. For @@ -2707,11 +2711,12 @@ def _locate_and_update_target_in_bin(self, target_filepath, method_name): raise securesystemslib.exceptions.Error(self.rolename + ' has not' ' delegated to hashed bins.') - # Ensure the filepath falls under the repository's targets directory. + # Ensure 'target_filepath' is located in the repository's targets + # directory. filepath = os.path.abspath(target_filepath) if not filepath.startswith(self._targets_directory + os.sep): - raise securesystemslib.exceptions.Error(repr(filepath) + ' is not under' - ' the Repository\'s targets directory: ' + repr(self._targets_directory)) + raise securesystemslib.exceptions.Error(repr(filepath) + ' is not located' + ' in the repository\'s targets directory: ' + repr(self._targets_directory)) # Determine the hash prefix of 'target_path' by computing the digest of # its path relative to the targets directory. Example: