def remove_keydb(repository_name):
"""
<Purpose>
Remove a key database for a non-default repository named 'repository_name'.
The 'default' repository cannot be removed.
<Arguments>
repository_name:
The name of the repository to remove. The 'default' repository should
not be removed, so 'repository_name' cannot be 'default'.
<Exceptions>
securesystemslib.exceptions.FormatError, if 'repository_name' is improperly formatted.
securesystemslib.exceptions.InvalidNameError, if 'repository_name' is 'default'.
<Side Effects>
None.
<Returns>
None.
"""
# Is 'repository_name' properly formatted? Raise 'securesystemslib.exceptions.FormatError' if not.
sslib_formats.NAME_SCHEMA.check_match(repository_name)
if repository_name not in _keydb_dict:
logger.warning('Repository name does not exist: ' + repr(repository_name))
return
if repository_name == 'default':
raise sslib_exceptions.InvalidNameError('Cannot remove the default repository:'
' ' + repr(repository_name))
del _keydb_dict[repository_name]
def _check_rolename(rolename, repository_name='default'):
""" Raise securesystemslib.exceptions.FormatError if 'rolename' does not match
'tuf.formats.ROLENAME_SCHEMA',
tuf.exceptions.UnknownRoleError if 'rolename' is not found in the
role database, or securesystemslib.exceptions.InvalidNameError if
'repository_name' does not exist in the role database.
"""
# Does 'rolename' have the correct object format?
# This check will ensure 'rolename' has the appropriate number of objects
# and object types, and that all dict keys are properly named.
formats.ROLENAME_SCHEMA.check_match(rolename)
# Does 'repository_name' have the correct format?
sslib_formats.NAME_SCHEMA.check_match(repository_name)
# Raises securesystemslib.exceptions.InvalidNameError.
_validate_rolename(rolename)
global _roledb_dict
global _dirty_roles
if repository_name not in _roledb_dict or repository_name not in _dirty_roles:
raise sslib_exceptions.InvalidNameError('Repository name does not'
' exist: ' + repository_name)
if rolename not in _roledb_dict[repository_name]:
raise exceptions.UnknownRoleError('Role name does not exist: ' + rolename)
def create_keydb(repository_name):
"""
<Purpose>
Create a key database for a non-default repository named 'repository_name'.
<Arguments>
repository_name:
The name of the repository. An empty key database is created, and keys
may be added to via add_key(keyid, repository_name).
<Exceptions>
securesystemslib.exceptions.FormatError, if 'repository_name' is improperly formatted.
securesystemslib.exceptions.InvalidNameError, if 'repository_name' already exists.
<Side Effects>
None.
<Returns>
None.
"""
# Is 'repository_name' properly formatted? Raise 'securesystemslib.exceptions.FormatError' if not.
sslib_formats.NAME_SCHEMA.check_match(repository_name)
if repository_name in _keydb_dict:
raise sslib_exceptions.InvalidNameError(
'Repository name already exists:'
' ' + repr(repository_name))
_keydb_dict[repository_name] = {}
def _validate_rolename(rolename):
"""
Raise securesystemslib.exceptions.InvalidNameError if 'rolename' is not
formatted correctly. It is assumed 'rolename' has been checked against
'ROLENAME_SCHEMA' prior to calling this function. """
if rolename == '':
raise sslib_exceptions.InvalidNameError('Rolename must *not* be'
' an empty string.')
if rolename != rolename.strip():
raise sslib_exceptions.InvalidNameError('Invalid rolename.'
' Cannot start or end with whitespace: ' + rolename)
if rolename.startswith('/') or rolename.endswith('/'):
raise sslib_exceptions.InvalidNameError('Invalid rolename.'
' Cannot start or end with a "/": ' + rolename)
def get_key(keyid, repository_name='default'):
"""
<Purpose>
Return the key belonging to 'keyid'.
<Arguments>
keyid:
An object conformant to 'securesystemslib.formats.KEYID_SCHEMA'. It is used as an
identifier for keys.
repository_name:
The name of the repository to get the key. If not supplied, the key is
retrieved from the 'default' repository.
<Exceptions>
securesystemslib.exceptions.FormatError, if the arguments do not have the correct format.
tuf.exceptions.UnknownKeyError, if 'keyid' is not found in the keydb database.
securesystemslib.exceptions.InvalidNameError, if 'repository_name' does not exist in the key
database.
<Side Effects>
None.
<Returns>
The key matching 'keyid'. In the case of RSA keys, a dictionary conformant
to 'securesystemslib.formats.RSAKEY_SCHEMA' is returned.
"""
# Does 'keyid' have the correct format?
# This check will ensure 'keyid' has the appropriate number of objects
# and object types, and that all dict keys are properly named.
# Raise 'securesystemslib.exceptions.FormatError' is the match fails.
sslib_formats.KEYID_SCHEMA.check_match(keyid)
# Does 'repository_name' have the correct format?
sslib_formats.NAME_SCHEMA.check_match(repository_name)
if repository_name not in _keydb_dict:
raise sslib_exceptions.InvalidNameError(
'Repository name does not exist:'
' ' + repr(repository_name))
# Return the key belonging to 'keyid', if found in the key database.
try:
return copy.deepcopy(_keydb_dict[repository_name][keyid])
except KeyError as error:
six.raise_from(exceptions.UnknownKeyError('Key: ' + keyid), error)
def remove_key(keyid, repository_name='default'):
"""
<Purpose>
Remove the key belonging to 'keyid'.
<Arguments>
keyid:
An object conformant to 'securesystemslib.formats.KEYID_SCHEMA'. It is used as an
identifier for keys.
repository_name:
The name of the repository to remove the key. If not supplied, the key
is removed from the 'default' repository.
<Exceptions>
securesystemslib.exceptions.FormatError, if the arguments do not have the correct format.
tuf.exceptions.UnknownKeyError, if 'keyid' is not found in key database.
securesystemslib.exceptions.InvalidNameError, if 'repository_name' does not exist in the key
database.
<Side Effects>
The key, identified by 'keyid', is deleted from the key database.
<Returns>
None.
"""
# Does 'keyid' have the correct format?
# This check will ensure 'keyid' has the appropriate number of objects
# and object types, and that all dict keys are properly named.
# Raise 'securesystemslib.exceptions.FormatError' is the match fails.
sslib_formats.KEYID_SCHEMA.check_match(keyid)
# Does 'repository_name' have the correct format?
sslib_formats.NAME_SCHEMA.check_match(repository_name)
if repository_name not in _keydb_dict:
raise sslib_exceptions.InvalidNameError(
'Repository name does not exist:'
' ' + repr(repository_name))
# Remove the key belonging to 'keyid' if found in the key database.
if keyid in _keydb_dict[repository_name]:
del _keydb_dict[repository_name][keyid]
else:
raise exceptions.UnknownKeyError('Key: ' + keyid)
def clear_roledb(repository_name='default', clear_all=False):
"""
<Purpose>
Reset the roledb database.
<Arguments>
repository_name:
The name of the repository to clear. If not supplied, the 'default'
repository is cleared.
clear_all:
Boolean indicating whether to clear the entire roledb.
<Exceptions>
securesystemslib.exceptions.FormatError, if 'repository_name' does not have
the correct format.
securesystemslib.exceptions.InvalidNameError, if 'repository_name' does not
exist in the role database.
<Side Effects>
None.
<Returns>
None.
"""
# Do the arguments have the correct format? If not, raise
# 'securesystemslib.exceptions.FormatError'
sslib_formats.NAME_SCHEMA.check_match(repository_name)
sslib_formats.BOOLEAN_SCHEMA.check_match(clear_all)
global _roledb_dict
global _dirty_roles
if repository_name not in _roledb_dict or repository_name not in _dirty_roles:
raise sslib_exceptions.InvalidNameError('Repository name does not'
' exist: ' + repository_name)
if clear_all:
_roledb_dict = {}
_roledb_dict['default'] = {}
_dirty_roles = {}
_dirty_roles['default'] = set()
return
_roledb_dict[repository_name] = {}
_dirty_roles[repository_name] = set()
def unmark_dirty(roles, repository_name='default'):
"""
<Purpose>
No longer mark the roles in 'roles' as dirty.
<Arguments>
repository_name:
The name of the repository to get the dirty roles. If not supplied, the
'default' repository is searched.
roles:
A list of roles that should no longer be marked as dirty.
<Exceptions>
securesystemslib.exceptions.FormatError, if the arguments are improperly
formatted.
securesystemslib.exceptions.InvalidNameError, if 'repository_name' does not
exist in the role database.
<Side Effects>
None.
<Returns>
None.
"""
# Are the arguments properly formatted? If not, raise
# securesystemslib.exceptions.FormatError.
sslib_formats.NAMES_SCHEMA.check_match(roles)
sslib_formats.NAME_SCHEMA.check_match(repository_name)
global _roledb_dict
global _dirty_roles
if repository_name not in _roledb_dict or repository_name not in _dirty_roles:
raise sslib_exceptions.InvalidNameError('Repository name does'
' not exist: ' + repository_name)
for role in roles:
try:
_dirty_roles[repository_name].remove(role)
except (KeyError, ValueError):
logger.debug(repr(role) + ' is not dirty.')
def remove_roledb(repository_name):
"""
<Purspose>
Remove the roledb belonging to 'repository_name'.
<Arguments>
repository_name:
The name of the repository to remove. 'repository_name' cannot be
'default' because the default repository is expected to always exist.
<Exceptions>
securesystemslib.exceptions.FormatError, if 'repository_name' is improperly
formatted.
securesystemslib.exceptions.InvalidNameError, if 'repository_name' is the
'default' repository name. The 'default' repository name should always
exist.
<Side Effects>
None.
<Returns>
None.
"""
# Is 'repository_name' properly formatted? If not, raise
# 'securesystemslib.exceptions.FormatError'.
sslib_formats.NAME_SCHEMA.check_match(repository_name)
global _roledb_dict
global _dirty_roles
if repository_name not in _roledb_dict or repository_name not in _dirty_roles:
logger.warning('Repository name does not exist:'
' ' + repr(repository_name))
return
if repository_name == 'default':
raise sslib_exceptions.InvalidNameError('Cannot remove the'
' default repository: ' + repr(repository_name))
del _roledb_dict[repository_name]
del _dirty_roles[repository_name]
def clear_keydb(repository_name='default', clear_all=False):
"""
<Purpose>
Clear the keydb key database.
<Arguments>
repository_name:
The name of the repository to clear the key database. If not supplied,
the key database is cleared for the 'default' repository.
clear_all:
Boolean indicating whether to clear the entire keydb.
<Exceptions>
securesystemslib.exceptions.FormatError, if 'repository_name' is improperly formatted.
securesystemslib.exceptions.InvalidNameError, if 'repository_name' does not exist in the key
database.
<Side Effects>
The keydb key database is reset.
<Returns>
None.
"""
# Do the arguments have the correct format? Raise 'securesystemslib.exceptions.FormatError' if
# 'repository_name' is improperly formatted.
sslib_formats.NAME_SCHEMA.check_match(repository_name)
sslib_formats.BOOLEAN_SCHEMA.check_match(clear_all)
global _keydb_dict
if clear_all:
_keydb_dict = {}
_keydb_dict['default'] = {}
if repository_name not in _keydb_dict:
raise sslib_exceptions.InvalidNameError(
'Repository name does not exist:'
' ' + repr(repository_name))
_keydb_dict[repository_name] = {}
def mark_dirty(roles, repository_name='default'):
"""
<Purpose>
Mark the list of 'roles' as dirty.
<Arguments>
repository_name:
The name of the repository to get the dirty roles. If not supplied, the
'default' repository is searched.
roles:
A list of roles that should be marked as dirty.
<Exceptions>
securesystemslib.exceptions.FormatError, if the arguments are improperly
formatted.
securesystemslib.exceptions.InvalidNameError, if 'repository_name' does not
exist in the role database.
<Side Effects>
None.
<Returns>
None.
"""
# Are the arguments properly formatted? If not, raise
# securesystemslib.exceptions.FormatError.
sslib_formats.NAMES_SCHEMA.check_match(roles)
sslib_formats.NAME_SCHEMA.check_match(repository_name)
global _roledb_dict
global _dirty_roles
if repository_name not in _roledb_dict or repository_name not in _dirty_roles:
raise sslib_exceptions.InvalidNameError('Repository name does'
' not' ' exist: ' + repository_name)
_dirty_roles[repository_name].update(roles)
def create_roledb(repository_name):
"""
<Purspose>
Create a roledb for the repository named 'repository_name'. This function
is intended for creation of a non-default roledb.
<Arguments>
repository_name:
The name of the repository to create. An empty roledb is created, and
roles may be added via add_role(rolename, roleinfo, repository_name) or
create_roledb_from_root_metadata(root_metadata, repository_name).
<Exceptions>
securesystemslib.exceptions.FormatError, if 'repository_name' is improperly
formatted.
securesystemslib.exceptions.InvalidNameError, if 'repository_name' already
exists in the roledb.
<Side Effects>
None.
<Returns>
None.
"""
# Is 'repository_name' properly formatted? If not, raise
# 'securesystemslib.exceptions.FormatError'.
sslib_formats.NAME_SCHEMA.check_match(repository_name)
global _roledb_dict
global _dirty_roles
if repository_name in _roledb_dict or repository_name in _dirty_roles:
raise sslib_exceptions.InvalidNameError('Repository name'
' already exists: ' + repr(repository_name))
_roledb_dict[repository_name] = {}
_dirty_roles[repository_name] = set()
def get_dirty_roles(repository_name='default'):
"""
<Purpose>
A function that returns a list of the roles that have been modified. Tools
that write metadata to disk can use the list returned to determine which
roles should be written.
<Arguments>
repository_name:
The name of the repository to get the dirty roles. If not supplied, the
'default' repository is searched.
<Exceptions>
securesystemslib.exceptions.FormatError, if 'repository_name' is improperly
formatted.
securesystemslib.exceptions.InvalidNameError, if 'repository_name' does not
exist in the role database.
<Side Effects>
None.
<Returns>
A sorted list of the roles that have been modified.
"""
# Does 'repository_name' have the correct format? Raise
# 'securesystemslib.exceptions.FormatError' if not.
sslib_formats.NAME_SCHEMA.check_match(repository_name)
global _roledb_dict
global _dirty_roles
if repository_name not in _roledb_dict or repository_name not in _dirty_roles:
raise sslib_exceptions.InvalidNameError('Repository name does'
' not' ' exist: ' + repository_name)
return sorted(list(_dirty_roles[repository_name]))
def get_rolenames(repository_name='default'):
"""
<Purpose>
Return a list of the rolenames found in the role database.
<Arguments>
repository_name:
The name of the repository to get the rolenames. If not supplied, the
'default' repository is searched.
<Exceptions>
securesystemslib.exceptions.FormatError, if 'repository_name' is improperly
formatted.
securesystemslib.exceptions.InvalidNameError, if 'repository_name' does not
exist in the role database.
<Side Effects>
None.
<Returns>
A list of rolenames.
"""
# Does 'repository_name' have the correct format? Raise
# 'securesystemslib.exceptions.FormatError' if it is improperly formatted.
sslib_formats.NAME_SCHEMA.check_match(repository_name)
global _roledb_dict
global _dirty_roles
if repository_name not in _roledb_dict or repository_name not in _dirty_roles:
raise sslib_exceptions.InvalidNameError('Repository name does'
' not' ' exist: ' + repository_name)
return list(_roledb_dict[repository_name].keys())
def add_role(rolename, roleinfo, repository_name='default'):
"""
<Purpose>
Add to the role database the 'roleinfo' associated with 'rolename'.
<Arguments>
rolename:
An object representing the role's name, conformant to 'ROLENAME_SCHEMA'
(e.g., 'root', 'snapshot', 'timestamp').
roleinfo:
An object representing the role associated with 'rolename', conformant to
ROLEDB_SCHEMA. 'roleinfo' has the form:
{'keyids': ['34345df32093bd12...'],
'threshold': 1,
'signatures': ['ab23dfc32']
'paths': ['path/to/target1', 'path/to/target2', ...],
'path_hash_prefixes': ['a324fcd...', ...],
'delegations': {'keys': }
The 'paths', 'path_hash_prefixes', and 'delegations' dict keys are
optional.
The 'target' role has an additional 'paths' key. Its value is a list of
strings representing the path of the target file(s).
repository_name:
The name of the repository to store 'rolename'. If not supplied,
'rolename' is added to the 'default' repository.
<Exceptions>
securesystemslib.exceptions.FormatError, if 'rolename' or 'roleinfo' does
not have the correct object format.
securesystemslib.exceptions.RoleAlreadyExistsError, if 'rolename' has
already been added.
securesystemslib.exceptions.InvalidNameError, if 'rolename' is improperly
formatted, or 'repository_name' does not exist.
<Side Effects>
The role database is modified.
<Returns>
None.
"""
# Does 'rolename' have the correct object format?
# This check will ensure 'rolename' has the appropriate number of objects
# and object types, and that all dict keys are properly named.
formats.ROLENAME_SCHEMA.check_match(rolename)
# Does 'roleinfo' have the correct object format?
formats.ROLEDB_SCHEMA.check_match(roleinfo)
# Is 'repository_name' correctly formatted?
sslib_formats.NAME_SCHEMA.check_match(repository_name)
global _roledb_dict
# Raises securesystemslib.exceptions.InvalidNameError.
_validate_rolename(rolename)
if repository_name not in _roledb_dict:
raise sslib_exceptions.InvalidNameError('Repository name does not exist: ' + repository_name)
if rolename in _roledb_dict[repository_name]:
raise exceptions.RoleAlreadyExistsError('Role already exists: ' + rolename)
_roledb_dict[repository_name][rolename] = copy.deepcopy(roleinfo)
def add_key(key_dict, keyid=None, repository_name='default'):
"""
<Purpose>
Add 'rsakey_dict' to the key database while avoiding duplicates.
If keyid is provided, verify it is the correct keyid for 'rsakey_dict'
and raise an exception if it is not.
<Arguments>
key_dict:
A dictionary conformant to 'securesystemslib.formats.ANYKEY_SCHEMA'.
It has the form:
{'keytype': 'rsa',
'keyid': keyid,
'keyval': {'public': '-----BEGIN RSA PUBLIC KEY----- ...',
'private': '-----BEGIN RSA PRIVATE KEY----- ...'}}
keyid:
An object conformant to 'KEYID_SCHEMA'. It is used as an identifier
for RSA keys.
repository_name:
The name of the repository to add the key. If not supplied, the key is
added to the 'default' repository.
<Exceptions>
securesystemslib.exceptions.FormatError, if the arguments do not have the correct format.
securesystemslib.exceptions.Error, if 'keyid' does not match the keyid for 'rsakey_dict'.
tuf.exceptions.KeyAlreadyExistsError, if 'rsakey_dict' is found in the key database.
securesystemslib.exceptions.InvalidNameError, if 'repository_name' does not exist in the key
database.
<Side Effects>
The keydb key database is modified.
<Returns>
None.
"""
# Does 'key_dict' have the correct format?
# This check will ensure 'key_dict' has the appropriate number of objects
# and object types, and that all dict keys are properly named.
# Raise 'securesystemslib.exceptions.FormatError if the check fails.
sslib_formats.ANYKEY_SCHEMA.check_match(key_dict)
# Does 'repository_name' have the correct format?
sslib_formats.NAME_SCHEMA.check_match(repository_name)
# Does 'keyid' have the correct format?
if keyid is not None:
# Raise 'securesystemslib.exceptions.FormatError' if the check fails.
sslib_formats.KEYID_SCHEMA.check_match(keyid)
# Check if each keyid found in 'key_dict' matches 'keyid'.
if keyid != key_dict['keyid']:
raise sslib_exceptions.Error('Incorrect keyid. Got ' +
key_dict['keyid'] + ' but expected ' +
keyid)
# Ensure 'repository_name' is actually set in the key database.
if repository_name not in _keydb_dict:
raise sslib_exceptions.InvalidNameError(
'Repository name does not exist:'
' ' + repr(repository_name))
# Check if the keyid belonging to 'key_dict' is not already
# available in the key database before returning.
keyid = key_dict['keyid']
if keyid in _keydb_dict[repository_name]:
raise exceptions.KeyAlreadyExistsError('Key: ' + keyid)
_keydb_dict[repository_name][keyid] = copy.deepcopy(key_dict)
def update_roleinfo(rolename, roleinfo, mark_role_as_dirty=True, repository_name='default'):
"""
<Purpose>
Modify 'rolename's _roledb_dict entry to include the new 'roleinfo'.
'rolename' is also added to the _dirty_roles set. Roles added to
'_dirty_roles' are marked as modified and can be used by the repository
tools to determine which roles need to be written to disk.
<Arguments>
rolename:
An object representing the role's name, conformant to 'ROLENAME_SCHEMA'
(e.g., 'root', 'snapshot', 'timestamp').
roleinfo:
An object representing the role associated with 'rolename', conformant to
ROLEDB_SCHEMA. 'roleinfo' has the form:
{'name': 'role_name',
'keyids': ['34345df32093bd12...'],
'threshold': 1,
'paths': ['path/to/target1', 'path/to/target2', ...],
'path_hash_prefixes': ['a324fcd...', ...]}
The 'name', 'paths', and 'path_hash_prefixes' dict keys are optional.
The 'target' role has an additional 'paths' key. Its value is a list of
strings representing the path of the target file(s).
mark_role_as_dirty:
A boolean indicating whether the updated 'roleinfo' for 'rolename' should
be marked as dirty. The caller might not want to mark 'rolename' as
dirty if it is loading metadata from disk and only wants to populate
roledb.py. Likewise, add_role() would support a similar boolean to allow
the repository tools to successfully load roles via load_repository()
without needing to mark these roles as dirty (default behavior).
repository_name:
The name of the repository to update the roleinfo of 'rolename'. If not
supplied, the 'default' repository is searched.
<Exceptions>
securesystemslib.exceptions.FormatError, if 'rolename' or 'roleinfo' does
not have the correct object format.
tuf.exceptions.UnknownRoleError, if 'rolename' cannot be found
in the role database.
securesystemslib.exceptions.InvalidNameError, if 'rolename' is improperly
formatted, or 'repository_name' does not exist in the role database.
<Side Effects>
The role database is modified.
<Returns>
None.
"""
# Does the arguments have the correct object format?
# This check will ensure arguments have the appropriate number of objects
# and object types, and that all dict keys are properly named.
formats.ROLENAME_SCHEMA.check_match(rolename)
sslib_formats.BOOLEAN_SCHEMA.check_match(mark_role_as_dirty)
sslib_formats.NAME_SCHEMA.check_match(repository_name)
# Does 'roleinfo' have the correct object format?
formats.ROLEDB_SCHEMA.check_match(roleinfo)
# Raises securesystemslib.exceptions.InvalidNameError.
_validate_rolename(rolename)
global _roledb_dict
global _dirty_roles
if repository_name not in _roledb_dict or repository_name not in _dirty_roles:
raise sslib_exceptions.InvalidNameError('Repository name does not' ' exist: ' +
repository_name)
if rolename not in _roledb_dict[repository_name]:
raise exceptions.UnknownRoleError('Role does not exist: ' + rolename)
# Update the global _roledb_dict and _dirty_roles structures so that
# the latest 'roleinfo' is available to other modules, and the repository
# tools know which roles should be saved to disk.
_roledb_dict[repository_name][rolename] = copy.deepcopy(roleinfo)
if mark_role_as_dirty:
_dirty_roles[repository_name].add(rolename)
