From 8a5475eb8808b0778696343f4a3df8a3d2593733 Mon Sep 17 00:00:00 2001 From: Vladimir Diaz Date: Fri, 19 Jan 2018 14:20:38 -0500 Subject: [PATCH 1/4] Remove or edit remaining instances of 'restricted paths' Signed-off-by: Vladimir Diaz --- tests/test_repository_tool.py | 14 +++++++------- tuf/README-developer-tools.md | 34 +++++++++++++++++----------------- tuf/README.md | 6 +++--- 3 files changed, 27 insertions(+), 27 deletions(-) diff --git a/tests/test_repository_tool.py b/tests/test_repository_tool.py index eb16ac8d..e4716415 100755 --- a/tests/test_repository_tool.py +++ b/tests/test_repository_tool.py @@ -1460,17 +1460,17 @@ def test_add_paths(self): self.targets_object.delegate(rolename, public_keys, [], threshold, list_of_targets=None, path_hash_prefixes=None) - # Delegate an extra role for test coverage (i.e., check that restricted - # paths are not added to a child role not requested.) + # Delegate an extra role for test coverage (i.e., to later verify that + # delegated paths are not added to a child role that was not requested). self.targets_object.delegate('junk_role', public_keys, []) - restricted_path = os.path.join(self.targets_directory, 'tuf_files') - os.mkdir(restricted_path) - paths = [restricted_path + '/*'] + delegated_path = os.path.join(self.targets_directory, 'tuf_files') + os.mkdir(delegated_path) + paths = [delegated_path + '/*'] self.targets_object.add_paths(paths, 'tuf') - # Retrieve 'targets_object' roleinfo, and verify the roleinfo contains - # the expected restricted paths of the delegated role. Only + # Retrieve 'targets_object' roleinfo, and verify the roleinfo contains the + # expected delegated paths of the delegated role. targets_object_roleinfo = tuf.roledb.get_roleinfo(self.targets_object.rolename, 'test_repository') diff --git a/tuf/README-developer-tools.md b/tuf/README-developer-tools.md index 09fdd7c2..36974113 100644 --- a/tuf/README-developer-tools.md +++ b/tuf/README-developer-tools.md @@ -12,7 +12,7 @@ - [Managing Targets](#managing_targets) -## Overview +## Overview The Update Framework (TUF) is a Python-based security system for software updates. In order to prevent your users from downloading vulnerable or malicious code disguised as updates to your software, TUF requires that each update you @@ -56,7 +56,7 @@ is the private key. >>> generate_and_write_rsa_keypair("path/to/key") Enter a password for the RSA key: Confirm: ->>> +>>> ``` We can also use the bits parameter to set a different key length (the default @@ -131,7 +131,7 @@ public key by the server (upon uploading) and by the clients (when updating). ### Signing and Writing the Metadata ### -In order to sign the metadata, we need to import the private key corresponding +In order to sign the metadata, we need to import the private key corresponding to the public key we added to the project. One the key is loaded to the project, it will automatically be used to sign the metadata whenever it is written. @@ -160,14 +160,14 @@ several contributors, you may want to consider adding ## Loading an Existing Project -To make changes to existing metadata, we will need the Project again. We can -restore it with the load_project() function. +To make changes to existing metadata, we will need the Project again. We can +restore it with the load_project() function. ``` >>> from tuf.developer_tool import * >>> project = load_project("local/path/to/metadata") ``` -Each time the project is loaded anew, the necessary private keys must also be +Each time the project is loaded anew, the necessary private keys must also be loaded in order to sign metadata. ``` @@ -205,21 +205,21 @@ contain any number of public keys. We can also add keys to the role after creating it using the [add\_verification\_key()](#adding_a_key_to_a_delegation) method. -### Restricted Paths +### Delegated Paths By default, a delegated role is permitted to add and modify targets anywhere in -the Project's targets directory. We can assign restricted paths to a delegated -role to limit this permission. +the Project's targets directory. We can delegate trust of paths to a role to +limit this permission. ``` ->>> project.add_restricted_paths(["restricted/filepath"], "newrole") +>>> project.add_paths(["delegated/filepath"], "newrole") ``` This will prevent the delegated role from signing targets whose local filepaths -do not begin with "restricted/filepath". We can assign several restricted -filepaths to a role by adding them to the list in the first parameter, or by -invoking the method again. A role with multiple restricted paths can add -targets to any of them. +do not begin with "delegated/filepath". We can delegate several filepaths to a +role by adding them to the list in the first parameter, or by invoking the +method again. A role with multiple delegated paths can add targets to any of +them. Note that this method is invoked from the parent role (in this case, the Project) and takes the delegated role name as an argument. @@ -248,16 +248,16 @@ Delegations can be revoked, removing the delegated role from the project. ``` -## Managing Keys +## Managing Keys This section describes the key-related functions and parameters not covered in the [Creating a Simple Project](#creating_a_simple_project) section. ### Additional Parameters for Key Generation -When generating keys, it is possible to specify the length of the key in bits +When generating keys, it is possible to specify the length of the key in bits and its password as parameters: ``` ->>> generate_and_write_rsa_keypair("path/to/key",bits=2048, password="pw") +>>> generate_and_write_rsa_keypair("path/to/key", bits=2048, password="pw") ``` The bits parameter defaults to 3072, and values below 2048 will raise an error. The password parameter is only intended to be used in scripts. diff --git a/tuf/README.md b/tuf/README.md index 50f046d7..a35db893 100644 --- a/tuf/README.md +++ b/tuf/README.md @@ -585,9 +585,9 @@ The `delegate_hashed_bins()` method has the following form: delegate_hashed_bins(list_of_targets, keys_of_hashed_bins, number_of_bins) ``` -A complete example of retrieving target paths to add to hashed bins, -performing the hashed bin delegations, signing them, and finally adding -restricted paths for some role is provided next. +We next provide a complete example of retrieving target paths to add to hashed +bins, performing the hashed bin delegations, signing them, and delegating paths +to some role. ```Python # Get a list of target paths for the hashed bins. >>> targets = \ From 81db8ebb8eee51dd5d6d5d97c1868c244879587e Mon Sep 17 00:00:00 2001 From: Vladimir Diaz Date: Fri, 19 Jan 2018 14:39:03 -0500 Subject: [PATCH 2/4] List FormatError in add_path()'s docstring Signed-off-by: Vladimir Diaz --- tuf/repository_tool.py | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/tuf/repository_tool.py b/tuf/repository_tool.py index 85966eb2..9db07122 100755 --- a/tuf/repository_tool.py +++ b/tuf/repository_tool.py @@ -1787,8 +1787,12 @@ def add_paths(self, paths, child_rolename): 'Django' in 'unclaimed'). - securesystemslib.exceptions.Error, if a path or glob pattern in 'paths' - is not a string, or if 'child_rolename' has not been delegated yet. + securesystemslib.exceptions.FormatError, if a path or glob pattern in + 'paths' is not a string, or if 'child_rolename' is not a formatted + rolename. + + securesystemslib.exceptions.Error, if 'child_rolename' has not been + delegated yet. Modifies this Targets' delegations field. @@ -1797,7 +1801,7 @@ def add_paths(self, paths, child_rolename): None. """ - # Does 'filepath' have the correct format? + # Do the argument have the correct format? # Ensure the arguments have the appropriate number of objects and object # types, and that all dict keys are properly named. # Raise 'securesystemslib.exceptions.FormatError' if there is a mismatch. From 019498607aa5011b4b1d6c41efe583d484769285 Mon Sep 17 00:00:00 2001 From: Vladimir Diaz Date: Fri, 19 Jan 2018 15:28:38 -0500 Subject: [PATCH 3/4] Remove 'if X is not None' instances and refactor add_paths() Signed-off-by: Vladimir Diaz --- tuf/repository_tool.py | 46 ++++++++++++++++++++---------------------- 1 file changed, 22 insertions(+), 24 deletions(-) diff --git a/tuf/repository_tool.py b/tuf/repository_tool.py index 9db07122..8c37d319 100755 --- a/tuf/repository_tool.py +++ b/tuf/repository_tool.py @@ -1765,12 +1765,12 @@ def target_files(self): def add_paths(self, paths, child_rolename): """ - Add 'paths' to the delegated paths for 'child_rolename'. 'paths' can be - a list of either file paths or glob patterns. The updater client - verifies the target paths specified by child roles, and searches for - targets by visiting these delegated paths. A child role may only provide - targets specifically listed in the delegations field of the parent role, - or a target that matches a delegated path. + Add 'paths' to the delegated paths of 'child_rolename'. 'paths' can be a + list of either file paths or glob patterns. The updater client verifies + the target paths specified by child roles, and searches for targets by + visiting these delegated paths. A child role may only provide targets + specifically listed in the delegations field of the delegating role, or a + target that matches a delegated path. >>> >>> @@ -1821,9 +1821,8 @@ def add_paths(self, paths, child_rolename): for path in paths: # 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, ''). + # 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) + ' is not located in the' @@ -1839,14 +1838,14 @@ def add_paths(self, paths, child_rolename): # Update the delegated paths of 'child_rolename' to add relative paths. for role in roleinfo['delegations']['roles']: if role['name'] == child_rolename: - delegated_paths = role['paths'] - - for relative_path in relative_paths: - if relative_path not in delegated_paths: - delegated_paths.append(relative_path) + for relative_path in relative_paths: + if relative_path not in role['paths']: + role['paths'].append(relative_path) + else: + logger.debug(repr(relative_path) + ' is already a delegated path.') else: - logger.debug(repr(relative_path) + ' is already a delegated path.') + logger.debug(repr(role['name']) + ' does not match child rolename.') tuf.roledb.update_roleinfo(self._rolename, roleinfo, repository_name=self._repository_name) @@ -2265,14 +2264,13 @@ def delegate(self, rolename, public_keys, paths, threshold=1, # 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 loated in the repository\'s' - ' targets directory: ' + repr(self._targets_directory)) + for path in paths: + if not path.startswith(self._targets_directory + os.sep): + 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, ''). - relative_paths.append(path[targets_directory_length:]) + # Append a trailing path separator with os.path.join(path, ''). + relative_paths.append(path[targets_directory_length:]) # Create a new Targets object for the 'rolename' delegation. An initial # expiration is set (3 months from the current time). @@ -2303,10 +2301,10 @@ def delegate(self, rolename, public_keys, paths, threshold=1, 'terminating': terminating, 'paths': list(roleinfo['paths'].keys())} - if paths is not None: + if paths: roleinfo['paths'] = relative_paths - if path_hash_prefixes is not None: + if path_hash_prefixes: roleinfo['path_hash_prefixes'] = path_hash_prefixes # A role in a delegations must list either 'path_hash_prefixes' # or 'paths'. From 0e12cfa9a473284ec399590865f98f4f198adc9c Mon Sep 17 00:00:00 2001 From: Vladimir Diaz Date: Fri, 19 Jan 2018 15:51:21 -0500 Subject: [PATCH 4/4] Revise a couple comments in repository_tool.py Signed-off-by: Vladimir Diaz --- tuf/repository_tool.py | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/tuf/repository_tool.py b/tuf/repository_tool.py index 8c37d319..ec638e9f 100755 --- a/tuf/repository_tool.py +++ b/tuf/repository_tool.py @@ -2160,8 +2160,11 @@ def delegate(self, rolename, public_keys, paths, threshold=1, 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'. + added to 'rolename', via add_targets() or 'list_of_targets', must + match one of the paths or glob patterns in 'paths'. Apart from the + public keys of 'rolename', the delegated 'paths' is often known and + specified when a delegation is first performed. If the delegator + is unsure of which 'paths' to delegate, 'paths' can be set to ['']. threshold: The threshold number of keys of 'rolename'. @@ -2178,7 +2181,7 @@ def delegate(self, rolename, public_keys, paths, threshold=1, file specified by 'target/other_role'. list_of_targets: - A list of target filepaths that are added to the paths of 'rolename'. + A list of target filepaths that are added to 'rolename'. 'list_of_targets' is a list of target filepaths, can be empty, and each filepath must be located in the repository's targets directory. The list of targets should also exist at the specified paths, otherwise