From ffe2c11fcfed5e2a137e01ffaef2585e23c4dc95 Mon Sep 17 00:00:00 2001 From: Kairo de Araujo Date: Mon, 15 Nov 2021 09:11:00 +0100 Subject: [PATCH] WIP: TUF Python Client Example/Tutorial It is a simple example of TUF ngclient implementation. This example contains a README.rst that is a tutorial/how-to-use this simple client using static test data from TUF repository. The code aims to be straightforward implementation, using basic concepts from Python and Command Line Interface. This is part of theupdateframework#1518 Signed-off-by: Kairo de Araujo --- examples/client_example/1.root.json | Bin 0 -> 3396 bytes examples/client_example/README.rst | 92 ++++++++++++++ examples/client_example/client_example.py | 145 ++++++++++++++++++++++ 3 files changed, 237 insertions(+) create mode 100644 examples/client_example/1.root.json create mode 100644 examples/client_example/README.rst create mode 100755 examples/client_example/client_example.py diff --git a/examples/client_example/1.root.json b/examples/client_example/1.root.json new file mode 100644 index 0000000000000000000000000000000000000000..214d8db01b6ce52ef48cefbbe3d59c65a59b59b1 GIT binary patch literal 3396 zcmd5;*-j%#7JaX;u>49_6Z=xqJlKgbn~gDxp_&nj<%ak4lF4FP_3wStrh4d+db(PS zG=q(>Ba_Gz=bm%V{q<9=UW|viD<9WT)W6hz`Bba@iodn`6gK0CD|G={>j)$=Et8GR zNMmBOjw+%;(87QeCRt$2D{ZCM!SkeevW9S(g0KIy-47pA?dCYwQE}V~Vr1Za3Q+|H zNd@C<;NBY^IQZTxJk_69SqqC(Ivx)!6$-?Ca4&Mj?`<#B5=yV#u%LmLHfX? z14q5Gk%07;S{o2?l6ZqKNJvTwiHMXrO}UB$Q3-FIM}%4i&hSK72oY7nhv5e#pIS-q zW+^>ZOM4Go>i~oqyyCHZTq~=*A(99ZfC}Ncf+3#xV8F9j!7-5vNh20WgQ{L!Auots1ZjzLRsu0RSS&hfiixNV@}$6P zr%?f10*b;pE;->OXq%Ms+&hc>(BwQ8FC;J);b1)wUxk>5Cu1# z`a`){LS>QlVo`2QQxA*07#Ahv^XYXA7VKcvN^wu99My?n=xY=;A9+#u}_YP9^k7DFdnmhCFzDmlf)7Q3# ze`_(npSf^vw^ohk$<4ka#(!Nt`q?;C%zUnXnyvP6x7NFEo*iek)7IT~@jmYyA2%11 zMz=Yfu13>w+dh+K8N#i__}%7Ofq3f_PC)oe|+hMlgF>At3)RgW^q34?+w^|C6*mY$M^Zm zJhtV_`zbR^K}+XI>=^a=lZHSTa|Vr;jBpeV!yR$UhlnT;&MR8z3aWbc~*?e z&3&FOF7&lJJI{IRF59f9N0N@d?#HLoOf2kG@2+$6(uHusvopFP>;mm}GTTg=SC1Wj z8&`$9&+~Y7w79+O_vZ80VRN6xv;810CY?N6Jg-j&M9mM+R<_@`YahFlLF(+2%&*T+ zmNy5}#?`zPkjc1gpWGd!!G6)dcIb*YV}E{gpTAnszAc8E*G6}fUD;KCa&&ue@XF@Xv(=tGX5-VcwQ?=!g+c$3 zAF2MC8!bEgS1*UJ&&r6q`@ApoGu*}l2)*vhU^5U*l9Kzt$*C-TQRk|2mh|Gop8TxqYSkjMlj!bwQxn@J}-;n^PAu+h41dGOY1~T zRg0qrEJW=*5UoTYUT80vAXYNxNTeFuve$+S?B5#u5+@9s>F*xch4FvQY!I20)c%0s z0Fw+`J#$3I0GuZsw9(wTlrWbtjTiyP39d;kFzI;J!V~_{AfgNL&uIIO;2l{?Qcanp z&f?~n|DMw-ZYjr*51#0xa0CGXo>~N-mEF}R)1yqxz z4kU8MaH0qaXCoYDd?HTKK(#dg2V}7jaJoaeGiwq~96mXMqaX&YGR6wvMB;&hMgkMT zLpoq!F`ogQ;*pW*nhHGd4pcn(GB=F9(p`_. + + +Preparing +========= + +To have the example working in your machine, clone the ``python-tuf`` in your +system. + +.. code:: console + + $ git clone git@github.com:theupdateframework/python-tuf.git + + +Repository +========== + +As this example demonstrates how to use the ``python-tuf`` to build a +client application, the repository will use static files. + +The static files are available in the ``python-tuf`` repository, same as this. +The static repository files are in +``tests/repository_data/repository``. + +Run the repository using the Python3 built-in HTTP module, and keep this +session running. + +.. code:: console + + $ python3 -m http.server -d tests/repository_data/repository + Serving HTTP on :: port 8000 (http://[::]:8000/) ... + + +Client Example +============== + +The `source code is available entirely <./client_example.py>`_ in this +repository. + +How to use the Client Example: + +1. Initialize the Client + + .. code:: console + + $ ./client_example.py --init + + + This action is to create the client infrastructure properly. + + This infrastructure consists in: + - Metadata repository + - Download folder for targets + - Bootstrap 1.root.json + + +2. Download the ``file1.txt`` + + .. code:: console + + $ ./client_example.py download file1.txt + [INFO] Top-level metadata is refreshed. + [INFO] Target info gotten. + [INFO] File downloaded available in ./downloads/file2.txt. + + +3. Download a not available ``file_na.txt`` + + .. code:: console + + $ ./client_example.py download file_na.txt + [INFO] Top-level metadata is refreshed. + [INFO] Target info gotten. + [ERROR] Target file not found. + +4. Download again ``file1.txt`` + + .. code:: console + + $ ./client_example.py download file1.txt + [INFO] Top-level metadata is refreshed. + [INFO] Target info gotten. + [INFO] File is already available in ./downloads/file1.txt. diff --git a/examples/client_example/client_example.py b/examples/client_example/client_example.py new file mode 100755 index 00000000..2a59b853 --- /dev/null +++ b/examples/client_example/client_example.py @@ -0,0 +1,145 @@ +#!/usr/bin/env python +import argparse +import os +import shutil +import sys +from logging import exception +from pathlib import Path + +from requests.exceptions import ConnectionError + +from tuf.ngclient import Updater + +# define directory constants +HOME_DIR = Path.home() # user home dir +DOWNLOAD_DIR = "./downloads" # download dir +METADATA_DIR = f"{HOME_DIR}/.local/share/tuf_metadata_example" # metadata dir +CLIENT_EXAMPLE_DIR = os.path.dirname(os.path.abspath(__file__)) # example dir + + +def init(): + """ + Initialize the TUF Client infrastructure + + This function initializes the creation of the download and TUF metadata + directory. + """ + + if not os.path.isdir(DOWNLOAD_DIR): + os.mkdir(DOWNLOAD_DIR) + + print(f"[INFO] Download directory [{DOWNLOAD_DIR}] is created.") + + if not os.path.isdir(METADATA_DIR): + os.makedirs(METADATA_DIR) + + print(f"[INFO] Metadata folder [{METADATA_DIR}] is created.") + + if not os.path.isfile(f"{METADATA_DIR}/root.json"): + shutil.copy( + f"{CLIENT_EXAMPLE_DIR}/1.root.json", f"{METADATA_DIR}/root.json" + ) + print(f"[INFO] Bootstrap initial root metadata.") + + +def tuf_updater(): + """ + This function implement the ``tuf.ngclient.Updater`` and returns + the updater. + """ + url = "http://127.0.0.1:8000" + + try: + updater = Updater( + repository_dir=METADATA_DIR, + metadata_base_url=f"{url}/metadata/", + target_base_url=f"{url}/targets/", + target_dir=DOWNLOAD_DIR, + ) + + except FileNotFoundError: + print("[ERROR] The Example Client not initiated. Try using '--init'.") + sys.exit(1) + + return updater + + +def download(target): + """ + Download the target file using the TUF ``nglcient`` Updater process. + + The Updater refreshes the top-level metadata, get the target information, + verifies if the target is already cached, and in case it is not cached, + downloads the target file. + """ + + try: + updater = tuf_updater() + + except ConnectionError: + print("[ERROR] Failed to connect http://127.0.0.1:8000") + sys.exit(1) + + updater.refresh() + print("[INFO] Top-level metadata is refreshed.") + + info = updater.get_targetinfo(target) + print("[INFO] Target info gotten.") + + if info is None: + print("[ERROR] Target file not found.") + sys.exit(1) + + path = updater.find_cached_target(info) + if path: + print( + f"[INFO] File is already available in {DOWNLOAD_DIR}/{info.path}." + ) + sys.exit(0) + + path = updater.download_target(info) + + print(f"[INFO] File downloaded available in {DOWNLOAD_DIR}/{info.path}.") + + +if __name__ == "__main__": + + client_args = argparse.ArgumentParser( + description="TUF Python Client Example" + ) + + # Global arguments + client_args.add_argument( + "--init", + default=False, + help="Force register a new Engine.", + action="store_true", + ) + + # Sub commands + sub_commands = client_args.add_subparsers(dest="sub_commands") + + # Download + download_parser = sub_commands.add_parser( + "download", + help="Download a target file", + ) + + download_parser.add_argument( + "target", + metavar="TARGET", + help="Target file", + ) + + command_args = vars(client_args.parse_args()) + sub_commands_args = command_args.get("sub_commands") + + if command_args.get("init") is True: + init() + + elif not sub_commands_args: + client_args.print_help() + + if sub_commands_args == "download": + target = command_args.get("target") + download(target)