@@ -2349,6 +2349,12 @@ def _ensure_not_expired(self, metadata_object, metadata_rolename):
2349
2349
def all_targets (self ):
2350
2350
"""
2351
2351
<Purpose>
2352
+
2353
+ NOTE: This function is deprecated. Its behavior with regard to which
2354
+ delegating Targets roles are trusted to determine how to validate a
2355
+ delegated Targets role is NOT WELL DEFINED. Please transition to use of
2356
+ get_one_valid_targetinfo()!
2357
+
2352
2358
Get a list of the target information for all the trusted targets on the
2353
2359
repository. This list also includes all the targets of delegated roles.
2354
2360
Targets of the list returned are ordered according the trusted order of
@@ -2558,6 +2564,12 @@ def _targets_of_role(self, rolename, targets=None, skip_refresh=False):
2558
2564
def targets_of_role (self , rolename = 'targets' ):
2559
2565
"""
2560
2566
<Purpose>
2567
+
2568
+ NOTE: This function is deprecated. Use with rolename 'targets' is secure
2569
+ and the behavior well-defined, but use with any delegated targets role is
2570
+ not. Please transition use for delegated targets roles to
2571
+ get_one_valid_targetinfo(). More information is below.
2572
+
2561
2573
Return a list of trusted targets directly specified by 'rolename'.
2562
2574
The returned information is a list conformant to
2563
2575
'tuf.formats.TARGETINFOS_SCHEMA', and has the form:
@@ -2603,7 +2615,25 @@ def targets_of_role(self, rolename='targets'):
2603
2615
# Raise 'securesystemslib.exceptions.FormatError' if there is a mismatch.
2604
2616
securesystemslib .formats .RELPATH_SCHEMA .check_match (rolename )
2605
2617
2606
- self ._refresh_targets_metadata (refresh_all_delegated_roles = True )
2618
+ # If we've been given a delegated targets role, we don't know how to
2619
+ # validate it without knowing what the delegating role is -- there could
2620
+ # be several roles that delegate to the given role. Behavior of this
2621
+ # function for roles other than Targets is not well defined as a result.
2622
+ # This function is deprecated, but:
2623
+ # - Usage of this function or a future successor makes sense when the
2624
+ # role of interest is Targets, since we always know exactly how to
2625
+ # validate Targets (We use root.).
2626
+ # - Until it's removed (hopefully soon), we'll try to provide what it has
2627
+ # always provided. To do this, we fetch and "validate" all delegated
2628
+ # roles listed by snapshot. For delegated roles only, the order of the
2629
+ # validation impacts the security of the validation -- the most-
2630
+ # recently-validated role delegating to a role you are currently
2631
+ # validating determines the expected keyids and threshold of the role
2632
+ # you are currently validating. That is NOT GOOD. Again, please switch
2633
+ # to get_one_valid_targetinfo, which is well-defined and secure.
2634
+ if rolename != 'targets' :
2635
+ self ._refresh_targets_metadata (refresh_all_delegated_roles = True )
2636
+
2607
2637
2608
2638
if not tuf .roledb .role_exists (rolename , self .repository_name ):
2609
2639
raise tuf .exceptions .UnknownRoleError (rolename )
0 commit comments