|
1 |
| -# CLI # |
| 1 | +# Command-Line Interface # |
2 | 2 |
|
3 |
| -The CLI requires a few dependencies and C extensions that can be installed with |
4 |
| -`pip install securesystemslib[crypto,pynacl]`. |
| 3 | +The TUF command-line interface (CLI) requires a full |
| 4 | +[TUF installation](INSTALLATION.rst). Be sure to include the installation of |
| 5 | +extra dependencies and C extensions ( |
| 6 | +```pip install securesystemslib[crypto,pynacl]```). |
5 | 7 |
|
6 |
| -[CLI_EXAMPLES.md](CLI_EXAMPLES.md) covers more complex examples. |
| 8 | +The use of the CLI is documented with examples below. |
7 | 9 |
|
8 | 10 | ----
|
| 11 | +# Basic Examples # |
| 12 | + |
9 | 13 | ## Create a repository ##
|
10 | 14 |
|
11 | 15 | Create a TUF repository in the current working directory. A cryptographic key
|
@@ -235,3 +239,211 @@ $ repo.py --clean
|
235 | 239 | $ repo.py --clean --path </path/to/dirty/repo>
|
236 | 240 | ```
|
237 | 241 | ----
|
| 242 | + |
| 243 | + |
| 244 | + |
| 245 | + |
| 246 | + |
| 247 | + |
| 248 | + |
| 249 | + |
| 250 | +# Further Examples # |
| 251 | + |
| 252 | +## Basic Update Delivery ## |
| 253 | + |
| 254 | +Steps: |
| 255 | + |
| 256 | +(1) initialize a repo. |
| 257 | + |
| 258 | +(2) delegate trust of target files to another role. |
| 259 | + |
| 260 | +(3) add a trusted file to the delegated role. |
| 261 | + |
| 262 | +(4) fetch the trusted file from the delegated role. |
| 263 | + |
| 264 | +```Bash |
| 265 | +Step (1) |
| 266 | +$ repo.py --init |
| 267 | + |
| 268 | +Step (2) |
| 269 | +$ repo.py --key ed25519 --filename mykey |
| 270 | +$ repo.py --delegate "README.*" --delegatee myrole --pubkeys tufkeystore/mykey.pub |
| 271 | +$ repo.py --sign tufkeystore/mykey --role myrole |
| 272 | +Enter a password for the encrypted key (tufkeystore/mykey): |
| 273 | +$ echo "my readme text" > README.txt |
| 274 | + |
| 275 | +Step (3) |
| 276 | +$ repo.py --add README.txt --role myrole --sign tufkeystore/mykey |
| 277 | +Enter a password for the encrypted key (tufkeystore/mykey): |
| 278 | +``` |
| 279 | + |
| 280 | +Serve the repo |
| 281 | +```Bash |
| 282 | +$ cd tufrepo/ |
| 283 | +$ python -m SimpleHTTPServer 8001 |
| 284 | +``` |
| 285 | + |
| 286 | +```Bash |
| 287 | +Step (4) |
| 288 | +$ client.py --repo http://localhost:8001 README.txt |
| 289 | +$ tree . |
| 290 | +. |
| 291 | +├── tuf.log |
| 292 | +├── tufrepo |
| 293 | +│ └── metadata |
| 294 | +│ ├── current |
| 295 | +│ │ ├── 1.root.json |
| 296 | +│ │ ├── myrole.json |
| 297 | +│ │ ├── root.json |
| 298 | +│ │ ├── snapshot.json |
| 299 | +│ │ ├── targets.json |
| 300 | +│ │ └── timestamp.json |
| 301 | +│ └── previous |
| 302 | +│ ├── 1.root.json |
| 303 | +│ ├── root.json |
| 304 | +│ ├── snapshot.json |
| 305 | +│ ├── targets.json |
| 306 | +│ └── timestamp.json |
| 307 | +└── tuftargets |
| 308 | + └── README.txt |
| 309 | + |
| 310 | + 5 directories, 13 files |
| 311 | +``` |
| 312 | + |
| 313 | + |
| 314 | +## Correcting a Key ## |
| 315 | +The filename of the top-level keys must be "root_key," "targets_key," |
| 316 | +"snapshot_key," and "root_key." The filename can vary for any additional |
| 317 | +top-level key. |
| 318 | + |
| 319 | +Steps: |
| 320 | + |
| 321 | +(1) initialize a repo containing default keys for the top-level roles. |
| 322 | +(2) distrust the default key for the root role. |
| 323 | +(3) create a new key and trust its use with the root role. |
| 324 | +(4) sign the root metadata file. |
| 325 | + |
| 326 | +```Bash |
| 327 | +Step (1) |
| 328 | +$ repo.py --init |
| 329 | + |
| 330 | +Step (2) |
| 331 | +$ repo.py --distrust --pubkeys tufkeystore/root_key.pub --role root |
| 332 | + |
| 333 | +Step (3) |
| 334 | +$ repo.py --key ed25519 --filename root_key |
| 335 | +$ repo.py --trust --pubkeys tufkeystore/root_key.pub --role root |
| 336 | + |
| 337 | +Step (4) |
| 338 | +$ repo.py --sign tufkeystore/root_key --role root |
| 339 | +Enter a password for the encrypted key (tufkeystore/root_key): |
| 340 | +``` |
| 341 | + |
| 342 | + |
| 343 | +## More Update Delivery ## |
| 344 | + |
| 345 | +Steps: |
| 346 | + |
| 347 | +(1) create a bare repo. |
| 348 | + |
| 349 | +(2) add keys to the top-level roles. |
| 350 | + |
| 351 | +(3) delegate trust of particular target files to another role X, where role X |
| 352 | +has a signature threshold 2 and is marked as a terminating delegation. The |
| 353 | +keys for role X and Y should be created prior to performing the delegation. |
| 354 | + |
| 355 | +(4) Delegate from role X to role Y. |
| 356 | + |
| 357 | +(5) have role X sign for a file also signed by the Targets role, to demonstrate |
| 358 | +the expected file that should be downloaded by the client. |
| 359 | + |
| 360 | +(6) perform an update. |
| 361 | + |
| 362 | +(7) halt the server, add README.txt to the Targets role, restart the server, |
| 363 | +and fetch the Target's role README.txt. |
| 364 | + |
| 365 | +(8) Add LICENSE to 'role_y' and demonstrate that the client must not fetch it |
| 366 | +because 'role_x' is a terminating delegation (and hasn't signed for it). |
| 367 | + |
| 368 | +```Bash |
| 369 | +Steps (1) and (2) |
| 370 | +$ repo.py --init --consistent --bare |
| 371 | +$ repo.py --key ed25519 --filename root_key |
| 372 | +$ repo.py --trust --pubkeys tufkeystore/root_key.pub --role root |
| 373 | +$ repo.py --key ecdsa --filename targets_key |
| 374 | +$ repo.py --trust --pubkeys tufkeystore/targets_key.pub --role targets |
| 375 | +$ repo.py --key rsa --filename snapshot_key |
| 376 | +$ repo.py --trust --pubkeys tufkeystore/snapshot_key.pub --role snapshot |
| 377 | +$ repo.py --key ecdsa --filename timestamp_key |
| 378 | +$ repo.py --trust --pubkeys tufkeystore/timestamp_key.pub --role timestamp |
| 379 | +$ repo.py --sign tufkeystore/root_key --role root |
| 380 | +Enter a password for the encrypted key (tufkeystore/root_key): |
| 381 | +$ repo.py --sign tufkeystore/targets_key --role targets |
| 382 | +Enter a password for the encrypted key (tufkeystore/targets_key): |
| 383 | +``` |
| 384 | + |
| 385 | +```Bash |
| 386 | +Steps (3) and (4) |
| 387 | +$ repo.py --key ed25519 --filename key_x |
| 388 | +$ repo.py --key ed25519 --filename key_x2 |
| 389 | + |
| 390 | +$ repo.py --delegate "README.*" "LICENSE" --delegatee role_x --pubkeys |
| 391 | + tufkeystore/key_x.pub tufkeystore/key_x2.pub --threshold 2 --terminating |
| 392 | +$ repo.py --sign tufkeystore/key_x tufkeystore/key_x2 --role role_x |
| 393 | + |
| 394 | +$ repo.py --key ed25519 --filename key_y |
| 395 | + |
| 396 | +$ repo.py --delegate "README.*" "LICENSE" --delegatee role_y --role role_x |
| 397 | + --pubkeys tufkeystore/key_y.pub --sign tufkeystore/key_x tufkeystore/key_x2 |
| 398 | + |
| 399 | +$ repo.py --sign tufkeystore/key_y --role role_y |
| 400 | +``` |
| 401 | + |
| 402 | +```Bash |
| 403 | +Steps (5) and (6) |
| 404 | +$ echo "role_x's readme" > README.txt |
| 405 | +$ repo.py --add README.txt --role role_x --sign tufkeystore/key_x tufkeystore/key_x2 |
| 406 | +``` |
| 407 | + |
| 408 | +Serve the repo |
| 409 | +```Bash |
| 410 | +$ cd tufrepo/ |
| 411 | +$ python -m SimpleHTTPServer 8001 |
| 412 | +``` |
| 413 | + |
| 414 | +Fetch the role x's README.txt |
| 415 | +```Bash |
| 416 | +$ client.py --repo http://localhost:8001 README.txt |
| 417 | +$ cat tuftargets/README.txt |
| 418 | +role_x's readme |
| 419 | +``` |
| 420 | +
|
| 421 | +
|
| 422 | +```Bash |
| 423 | +Step (7) |
| 424 | +halt the server... |
| 425 | +
|
| 426 | +$ echo "Target role's readme" > README.txt |
| 427 | +$ repo.py --add README.txt |
| 428 | +
|
| 429 | +restart the server... |
| 430 | +``` |
| 431 | +
|
| 432 | +```Bash |
| 433 | +$ rm -rf tuftargets/ tuf.log |
| 434 | +$ client.py --repo http://localhost:8001 README.txt |
| 435 | +$ cat tuftargets/README.txt |
| 436 | +Target role's readme |
| 437 | +``` |
| 438 | +
|
| 439 | +```Bash |
| 440 | +Step (8) |
| 441 | +$ echo "role_y's license" > LICENSE |
| 442 | +$ repo.py --add LICENSE --role role_y --sign tufkeystore/key_y |
| 443 | +``` |
| 444 | +
|
| 445 | +```Bash |
| 446 | +$ rm -rf tuftargets/ tuf.log |
| 447 | +$ client.py --repo http://localhost:8001 LICENSE |
| 448 | +Error: 'LICENSE' not found. |
| 449 | +``` |
0 commit comments