Struct RepoBuilder 

pub struct RepoBuilder<'a, D, R, S = Root>
where
    D: Pouf,
    R: RepositoryStorage<D>,
    S: State,
{ /* private fields */ }

This helper builder simplifies the process of creating new metadata.

Implementations

impl<'a, D, R> RepoBuilder<'a, D, R, Root>

where D: Pouf, R: RepositoryStorage<D>,

pub fn create(repo: R) -> Self

Create a RepoBuilder for creating metadata for a new repository.

Examples

let mut repo = EphemeralRepository::<Pouf1>::new();
let _metadata = RepoBuilder::create(&mut repo)
    .trusted_root_keys(&[&key])
    .trusted_targets_keys(&[&key])
    .trusted_snapshot_keys(&[&key])
    .trusted_timestamp_keys(&[&key])
    .commit()
    .await
    .unwrap();

pub fn from_database(repo: R, db: &'a Database<D>) -> Self

Create a RepoBuilder for creating metadata based off the latest metadata in the Database.

Examples

 let mut repo = EphemeralRepository::<Pouf1>::new();
 let metadata1 = RepoBuilder::create(&mut repo)
    .trusted_root_keys(&[&key])
    .trusted_targets_keys(&[&key])
    .trusted_snapshot_keys(&[&key])
    .trusted_timestamp_keys(&[&key])
    .commit()
    .await
    .unwrap();

let database = Database::from_trusted_metadata(&metadata1).unwrap();

let _metadata2 = RepoBuilder::from_database(&mut repo, &database)
    .trusted_root_keys(&[&key])
    .trusted_targets_keys(&[&key])
    .trusted_snapshot_keys(&[&key])
    .trusted_timestamp_keys(&[&key])
    .stage_root()
    .unwrap()
    .commit()
    .await
    .unwrap();

pub fn current_time(self, current_time: DateTime<Utc>) -> Self

Change the time the builder will use to see if metadata is expired, and the base time to use to compute the next expiration.

Default is the current wall clock time in UTC.

pub fn time_versioning(self, time_versioning: bool) -> Self

Create Non-root metadata based off the current UTC timestamp, instead of a monotonic increment.

pub fn root_expiration_duration(self, duration: Duration) -> Self

Sets that the root metadata will expire after this duration past the current time.

Defaults to 365 days.

Note: calling this function will only change what is the metadata expiration we’ll use if we create a new root metadata if we call RepoBuilder::stage_root, or we decide a new one is needed when we call RepoBuilder::stage_root_if_necessary.

pub fn targets_expiration_duration(self, duration: Duration) -> Self

Sets that the targets metadata will expire after after this duration past the current time.

Defaults to 90 days.

Note: calling this function will only change what is the metadata expiration we’ll use if we create a new targets metadata if we call RepoBuilder::stage_targets, or we decide a new one is needed when we call RepoBuilder::stage_targets_if_necessary.

pub fn snapshot_expiration_duration(self, duration: Duration) -> Self

Sets that the snapshot metadata will expire after after this duration past the current time.

Defaults to 7 days.

Note: calling this function will only change what is the metadata expiration we’ll use if we create a new snapshot metadata if we call RepoBuilder::stage_snapshot, or we decide a new one is needed when we call RepoBuilder::stage_snapshot_if_necessary.

pub fn timestamp_expiration_duration(self, duration: Duration) -> Self

Sets that the timestamp metadata will expire after after this duration past the current time.

Defaults to 1 day.

Note: calling this function will only change what is the metadata expiration we’ll use if we create a new timestamp metadata if we call RepoBuilder::stage_timestamp, or we decide a new one is needed when we call RepoBuilder::stage_timestamp_if_necessary.

pub fn signing_root_keys(self, keys: &[&'a dyn PrivateKey]) -> Self

Sign the root metadata with keys, but do not include the keys as trusted root keys in the root metadata. This is typically used to support root key rotation.

pub fn signing_targets_keys(self, keys: &[&'a dyn PrivateKey]) -> Self

Sign the targets metadata with keys, but do not include the keys as trusted targets keys in the root metadata. This is typically used to support targets key rotation.

pub fn signing_snapshot_keys(self, keys: &[&'a dyn PrivateKey]) -> Self

Sign the snapshot metadata with keys, but do not include the keys as trusted snapshot keys in the root metadata. This is typically used to support snapshot key rotation.

pub fn signing_timestamp_keys(self, keys: &[&'a dyn PrivateKey]) -> Self

Sign the timestamp metadata with keys, but do not include the keys as trusted timestamp keys in the root metadata. This is typically used to support timestamp key rotation.

pub fn trusted_root_keys(self, keys: &[&'a dyn PrivateKey]) -> Self

Sign the root metadata with keys, and include the keys as trusted root keys in the root metadata.

pub fn trusted_targets_keys(self, keys: &[&'a dyn PrivateKey]) -> Self

Sign the targets metadata with keys, and include the keys as trusted targets keys in the targets metadata.

pub fn trusted_snapshot_keys(self, keys: &[&'a dyn PrivateKey]) -> Self

Sign the snapshot metadata with keys, and include the keys as trusted snapshot keys in the root metadata.

pub fn trusted_timestamp_keys(self, keys: &[&'a dyn PrivateKey]) -> Self

Sign the timestamp metadata with keys, and include the keys as trusted timestamp keys in the root metadata.

pub fn stage_root(self) -> Result<RepoBuilder<'a, D, R, Targets<D>>>

Stage a root metadata.

If this is a new repository, the root will be staged with:

• version: 1
• consistent_snapshot: true
• expires: 365 days from the current day.
• root_threshold: 1
• targets_threshold: 1
• snapshot_threshold: 1
• timestamp_threshold: 1

Otherwise, it will be staged with:

• version: 1 after the trusted root’s version
• expires: 365 days from the current day.
• consistent_snapshot: match the trusted root’s consistent snapshot
• root_threshold: match the trusted root’s root threshold
• targets_threshold: match the trusted root’s targets threshold
• snapshot_threshold: match the trusted root’s snapshot threshold
• timestamp_threshold: match the trusted root’s timestamp threshold

pub fn stage_root_if_necessary( self, ) -> Result<RepoBuilder<'a, D, R, Targets<D>>>

Stage a new root using the default settings if:

• There is no trusted root metadata.
• The trusted keys are different from the keys that are in the trusted root.
• The trusted root metadata has expired.

pub fn skip_root(self) -> RepoBuilder<'a, D, R, Targets<D>>

Skip creating the root metadata. This may cause commit to fail if this is a new repository.

pub fn stage_root_with_builder<F>( self, f: F, ) -> Result<RepoBuilder<'a, D, R, Targets<D>>>

where F: FnOnce(RootMetadataBuilder) -> RootMetadataBuilder,

Initialize a RootMetadataBuilder and pass it to the closure for further configuration. This builder will then be used to generate and stage a new RootMetadata for eventual commitment to the repository.

If this is a new repository, the builder will be initialized with the following defaults:

• version: 1
• consistent_snapshot: true
• expires: 365 days from the current day.
• root_threshold: 1
• targets_threshold: 1
• snapshot_threshold: 1
• timestamp_threshold: 1

Otherwise, it will be initialized with:

• version: 1 after the trusted root’s version
• expires: 365 days from the current day.
• consistent_snapshot: match the trusted root’s consistent snapshot
• root_threshold: match the trusted root’s root threshold
• targets_threshold: match the trusted root’s targets threshold
• snapshot_threshold: match the trusted root’s snapshot threshold
• timestamp_threshold: match the trusted root’s timestamp threshold

pub async fn add_target<Rd>( self, target_path: TargetPath, reader: Rd, ) -> Result<RepoBuilder<'a, D, R, Targets<D>>>

where Rd: AsyncRead + AsyncSeek + Unpin + Send,

Add a target that’s loaded in from the reader. This will store the target in the repository, and may stage a root metadata if necessary.

This will hash the file with HashAlgorithm::Sha256.

See RepoBuilder<Targets>::add_target for more details.

pub async fn commit(self) -> Result<RawSignedMetadataSet<D>>

Validate and write the metadata to the repository.

This may stage a root, targets, snapshot, and timestamp metadata if necessary.

See RepoBuilder::commit for more details.

impl<'a, D, R> RepoBuilder<'a, D, R, Targets<D>>

where D: Pouf, R: RepositoryStorage<D>,

pub fn target_hash_algorithms(self, algorithms: &[HashAlgorithm]) -> Self

Whether or not to include the length of the targets, and any delegated targets, in the new snapshot.

Default is [HashAlgorithm::Sha256].

pub fn inherit_from_trusted_targets(self, inherit: bool) -> Self

Whether or not the new targets metadata inherits targets and delegations from the trusted targets metadata.

Default is true.

pub fn stage_targets(self) -> Result<RepoBuilder<'a, D, R, Snapshot<D>>>

Stage a targets metadata using the default settings.

pub fn stage_targets_if_necessary( self, ) -> Result<RepoBuilder<'a, D, R, Snapshot<D>>>

Stage a new targets using the default settings if:

• There is no trusted targets metadata.
• The trusted targets metadata has expired.

pub fn skip_targets(self) -> RepoBuilder<'a, D, R, Snapshot<D>>

Skip creating the targets metadata.

pub async fn add_target<Rd>( self, target_path: TargetPath, reader: Rd, ) -> Result<RepoBuilder<'a, D, R, Targets<D>>>

where Rd: AsyncRead + AsyncSeek + Unpin + Send,

Add a target that’s loaded in from the reader. This will store the target in the repository.

This will hash the file with the hash specified in RepoBuilder::target_hash_algorithms. If none was specified, the file will be hashed with HashAlgorithm::Sha256.

pub async fn add_target_with_custom<Rd>( self, target_path: TargetPath, reader: Rd, custom: HashMap<String, Value>, ) -> Result<RepoBuilder<'a, D, R, Targets<D>>>

where Rd: AsyncRead + AsyncSeek + Unpin + Send,

Add a target that’s loaded in from the reader. This will store the target in the repository.

This will hash the file with the hash specified in RepoBuilder::target_hash_algorithms. If none was specified, the file will be hashed with HashAlgorithm::Sha256.

pub fn add_delegation_key(self, key: PublicKey) -> Self

Add a target delegation key.

pub fn add_delegation_role(self, delegation: Delegation) -> Self

Add a target delegation role.

pub fn stage_targets_with_builder<F>( self, f: F, ) -> Result<RepoBuilder<'a, D, R, Snapshot<D>>>

where F: FnOnce(TargetsMetadataBuilder) -> TargetsMetadataBuilder,

Initialize a TargetsMetadataBuilder and pass it to the closure for further configuration. This builder will then be used to generate and stage a new TargetsMetadata for eventual commitment to the repository.

This builder will be initialized with:

• version: 1 if a new repository, otherwise 1 past the trusted targets’s version.
• expires: 90 days from the current day.

pub async fn commit(self) -> Result<RawSignedMetadataSet<D>>

Validate and write the metadata to the repository.

This may stage a targets, snapshot, and timestamp metadata if necessary.

See RepoBuilder::commit for more details.

impl<'a, D, R> RepoBuilder<'a, D, R, Snapshot<D>>

where D: Pouf, R: RepositoryStorage<D>,

pub fn snapshot_includes_length(self, include_targets_lengths: bool) -> Self

Whether or not to include the length of the targets, and any delegated targets, in the new snapshot.

Default is false.

pub fn snapshot_includes_hashes(self, hashes: &[HashAlgorithm]) -> Self

Whether or not to include the hashes of the targets, and any delegated targets, in the new snapshot.

Default is &[].

pub fn inherit_from_trusted_snapshot(self, inherit: bool) -> Self

Whether or not the new snapshot to inherit metafiles from the trusted snapshot.

Default is true.

pub fn stage_snapshot(self) -> Result<RepoBuilder<'a, D, R, Timestamp<D>>>

Stage a snapshot metadata using the default settings.

pub fn stage_snapshot_if_necessary( self, ) -> Result<RepoBuilder<'a, D, R, Timestamp<D>>>

Stage a new snapshot using the default settings if:

• There is no trusted snapshot metadata.
• The trusted snapshot metadata has expired.

pub fn skip_snapshot(self) -> RepoBuilder<'a, D, R, Timestamp<D>>

Skip creating the snapshot metadata.

pub fn stage_snapshot_with_builder<F>( self, f: F, ) -> Result<RepoBuilder<'a, D, R, Timestamp<D>>>

where F: FnOnce(SnapshotMetadataBuilder) -> SnapshotMetadataBuilder,

Initialize a SnapshotMetadataBuilder and pass it to the closure for further configuration. This builder will then be used to generate and stage a new SnapshotMetadata for eventual commitment to the repository.

This builder will be initialized with:

• version: 1 if a new repository, otherwise 1 past the trusted snapshot’s version.
• expires: 7 days from the current day.

pub async fn commit(self) -> Result<RawSignedMetadataSet<D>>

Validate and write the metadata to the repository.

This may stage a snapshot and timestamp metadata if necessary.

See RepoBuilder::commit for more details.

impl<'a, D, R> RepoBuilder<'a, D, R, Timestamp<D>>

where D: Pouf, R: RepositoryStorage<D>,

pub fn timestamp_includes_length(self, include_snapshot_lengths: bool) -> Self

Whether or not to include the length of the snapshot, and any delegated snapshot, in the new snapshot.

pub fn timestamp_includes_hashes(self, hashes: &[HashAlgorithm]) -> Self

Whether or not to include the hashes of the snapshot in the new timestamp.

pub fn stage_timestamp(self) -> Result<RepoBuilder<'a, D, R, Done<D>>>

Stage a timestamp metadata using the default settings.

Note: This will also:

• stage a root metadata with the default settings if necessary.
• stage a targets metadata if necessary.
• stage a snapshot metadata if necessary.

pub fn stage_timestamp_if_necessary( self, ) -> Result<RepoBuilder<'a, D, R, Done<D>>>

Stage a new timestamp using the default settings if:

• There is no trusted timestamp metadata.
• The trusted timestamp metadata has expired.

pub fn skip_timestamp(self) -> RepoBuilder<'a, D, R, Done<D>>

Skip creating the timestamp metadata.

pub fn stage_timestamp_with_builder<F>( self, f: F, ) -> Result<RepoBuilder<'a, D, R, Done<D>>>

where F: FnOnce(TimestampMetadataBuilder) -> TimestampMetadataBuilder,

Initialize a TimestampMetadataBuilder and pass it to the closure for further configuration. This builder will then be used to generate and stage a new TimestampMetadata for eventual commitment to the repository.

This builder will be initialized with:

• version: 1 if a new repository, otherwise 1 past the trusted snapshot’s version.
• expires: 1 day from the current day.

pub async fn commit(self) -> Result<RawSignedMetadataSet<D>>

See RepoBuilder::commit for more details.

impl<D, R> RepoBuilder<'_, D, R, Done<D>>

where D: Pouf, R: RepositoryStorage<D>,

pub async fn commit(self) -> Result<RawSignedMetadataSet<D>>

Commit the metadata for this repository, then write all metadata to the repository. Before writing the metadata to repo, this will test that a client can update to this metadata to make sure it is valid.