Skip to content

CLIENT-CLI.md

Latest commit

 

History

History
109 lines (75 loc) · 4.64 KB

CLIENT-CLI.md

File metadata and controls

109 lines (75 loc) · 4.64 KB
Raw

tuf-conformance client-under-test CLI

Before a TUF client can be tested with the tuf-conformance test suite, an executable must be provided that implements this CLI protocol. There are three required commands: init, refresh and download. The executable should operate at a level of verbosity that is useful for debugging.

Commands

Init command

Initialize the clients local trusted metadata.

<client> --metadata-dir <METADATA_DIR> init <TRUSTED_ROOT>

where

  • METADATA_DIR is a directory where the client is expected to store metadata it considers valid
  • TRUSTED_ROOT is a file that contains initial root.json content

Client must initialize with the given trusted root (this may involve simply copying the trusted root into METADATA_DIR: no checks are expected). No requests should be made to the repository at this point. Client must use exit code 0 if the initialization succeeded and exit code 1 otherwise.

This command will be called only once for a specific test.

Example

my-tuf-client --metadata-dir /tmp/metadata init ./initial_root.json

Refresh command

Update local metadata from the repository.

<client> --metadata-dir <METADATA_DIR> --metadata-url <METADATA_URL> refresh

where

  • METADATA_DIR is a directory where the client is expected to read and write trusted local metadata
  • METADATA_URL is a URL to the repository metadata store

Client must update its top-level metadata according to the TUF client workflow. Client must use exit code 0 if the refresh succeeded fully and exit code 1 if any part of the refresh failed.

Client must use non-versioned filenames for metadata in METADATA_DIR (so "root.json" instead of "1.root.json").

This command may be called multiple times in a test.

Example

my-tuf-client \
    --metadata-dir /tmp/metadata \
    --metadata-url http://localhost:8888/test-repo/metadata \
    refresh`

Download command

Download an artifact from repository, store it in local disk.

<client> --metadata-dir <METADATA_DIR> --metadata-url <METADATA_URL> --target-name <TARGET_PATH> --target-base-url <TARGET_URL> --target-dir <TARGET_DIR> download

where

  • METADATA_DIR is a directory where the client is expected to store metadata it considers valid
  • METADATA_URL is a URL to the repository metadata store
  • TARGET_PATH is the TUF targetpath of an artifact that should be downloaded. --target-name may be repeated: targets must be processed in argument order using the same client/updater instance, and the command must stop and return exit code 1 if any target fails.
  • TARGET_URL is the base URL for repository target store
  • TARGET_DIR: is a directory where the client should store downloaded and verified files

Client must download the given artifact (targetpath) according to TUF client workflow, and store it in given targets directory. Client must ensure that metadata is up-to-date before downloading artifacts (see Refresh command for rules on metadata storage in METADATA_DIR). Client must use exit code 0 if the download succeeded fully and exit code 1 if any part of the download failed.

Client should support artifact caching: if client is requested to download an artifact that has already been downloaded (with matching hashes), it should not download the artifact again.

Client may use any filename or directory structure it wants within TARGET_DIR: The expectation is that if an artifact is downloaded twice (because the artifact content changed) it is stored in TARGET_DIR with the same filename.

This command may be called multiple times in a test.

Example

my-tuf-client \
    --metadata-dir /tmp/metadata \
    --metadata-url http://localhost:8888/test-repo/metadata \
    --target-name path/to/artifact.txt \
    --target-base-url http://localhost:8888/test-repo/targets \
    --target-dir /tmp/targets
    download

What does the test suite measure?

The test suite has limited visibility into client decisions so uses various signals to measure conformance:

  • Client command success/failure
  • The metadata the client considers trusted (METADATA_DIR)
  • The artifacts the client downloads (TARGET_DIR)
  • The HTTP requests made by the client to the repository

Sometimes test suite expectations exist to make measurement possible or are not even strictly part of TUF specification. Examples:

  • a specific sequence of metadata HTTP requests is expected to assert that the client handled delegations correctly.
  • metadata and artifacts are expected to be stored in files -- the client implementation is free to use e.g. a database internally but in that case the client-under-test CLI should make copies available in METADATA_DIR and TARGET_DIR for the test suite