From 39f2628b79cc1adb20845d89ca253d632dfa3054 Mon Sep 17 00:00:00 2001 From: Sergi Delgado Segura Date: Thu, 2 Apr 2020 15:15:34 +0200 Subject: [PATCH] Fixes docs and adds register help --- cli/help.py | 20 +++++++++++++---- cli/teos_cli.py | 59 ++++++++++++++++++++++++++++++------------------- 2 files changed, 52 insertions(+), 27 deletions(-) diff --git a/cli/help.py b/cli/help.py index 3b079ad..4ecf172 100644 --- a/cli/help.py +++ b/cli/help.py @@ -3,6 +3,7 @@ def show_usage(): "USAGE: " "\n\tpython teos_cli.py [global options] command [command options] [arguments]" "\n\nCOMMANDS:" + "\n\tregister \tRegisters your user public key with the tower." "\n\tadd_appointment \tRegisters a json formatted appointment with the tower." "\n\tget_appointment \tGets json formatted data about an appointment from the tower." "\n\thelp \t\t\tShows a list of commands or help for a specific command." @@ -14,12 +15,23 @@ def show_usage(): ) +def help_register(): + return ( + "NAME:" + "\n\n\tregister" + "\n\nUSAGE:" + "\n\n\tpython teos_cli.py register" + "\n\nDESCRIPTION:" + "\n\n\tRegisters your user public key with the tower." + ) + + def help_add_appointment(): return ( "NAME:" - "\tpython teos_cli add_appointment - Registers a json formatted appointment to the tower." + "\n\tadd_appointment - Registers a json formatted appointment to the tower." "\n\nUSAGE:" - "\tpython teos_cli add_appointment [command options] appointment/path_to_appointment_file" + "\n\tpython teos_cli.py add_appointment [command options] appointment/path_to_appointment_file" "\n\nDESCRIPTION:" "\n\n\tRegisters a json formatted appointment to the tower." "\n\tif -f, --file *is* specified, then the command expects a path to a json file instead of a json encoded " @@ -33,9 +45,9 @@ def help_add_appointment(): def help_get_appointment(): return ( "NAME:" - "\tpython teos_cli get_appointment - Gets json formatted data about an appointment from the tower." + "\n\tget_appointment - Gets json formatted data about an appointment from the tower." "\n\nUSAGE:" - "\tpython teos_cli get_appointment appointment_locator" + "\n\tpython teos_cli.py get_appointment appointment_locator" "\n\nDESCRIPTION:" "\n\n\tGets json formatted data about an appointment from the tower.\n" ) diff --git a/cli/teos_cli.py b/cli/teos_cli.py index 498ead5..b53f8c3 100644 --- a/cli/teos_cli.py +++ b/cli/teos_cli.py @@ -10,7 +10,7 @@ from getopt import getopt, GetoptError from requests import ConnectTimeout, ConnectionError from requests.exceptions import MissingSchema, InvalidSchema, InvalidURL -from cli.help import show_usage, help_add_appointment, help_get_appointment +from cli.help import show_usage, help_add_appointment, help_get_appointment, help_register from cli import DEFAULT_CONF, DATA_DIR, CONF_FILE_NAME, LOG_PREFIX import common.cryptographer @@ -21,14 +21,26 @@ from common.appointment import Appointment from common.config_loader import ConfigLoader from common.cryptographer import Cryptographer from common.tools import setup_logging, setup_data_folder -from common.tools import check_sha256_hex_format, check_locator_format, compute_locator, check_compressed_pk_format +from common.tools import is_256b_hex_str, is_locator, compute_locator, is_compressed_pk logger = Logger(actor="Client", log_name_prefix=LOG_PREFIX) common.cryptographer.logger = Logger(actor="Cryptographer", log_name_prefix=LOG_PREFIX) def register(compressed_pk, teos_url): - if not check_compressed_pk_format(compressed_pk): + """ + Registers the user to the tower. + + Args: + compressed_pk (:obj:`str`): a 33-byte hex-encoded compressed public key representing the user. + teos_url (:obj:`str`): the teos base url. + + Returns: + :obj:`dict` or :obj:`None`: a dictionary containing the tower response if the registration succeeded. ``None`` + otherwise. + """ + + if not is_compressed_pk(compressed_pk): logger.error("The cli public key is not valid") return None @@ -45,8 +57,7 @@ def register(compressed_pk, teos_url): def add_appointment(appointment_data, cli_sk, teos_pk, teos_url, appointments_folder_path): """ - Manages the add_appointment command, from argument parsing, trough sending the appointment to the tower, until - saving the appointment receipt. + Manages the add_appointment command. The life cycle of the function is as follows: - Check that the given commitment_txid is correct (proper format and not missing) @@ -58,8 +69,6 @@ def add_appointment(appointment_data, cli_sk, teos_pk, teos_url, appointments_fo - Check the tower's response and signature - Store the receipt (appointment + signature) on disk - If any of the above-mentioned steps fails, the method returns false, otherwise it returns true. - Args: appointment_data (:obj:`dict`): a dictionary containing the appointment data. cli_sk (:obj:`PrivateKey`): the client's private key. @@ -69,7 +78,7 @@ def add_appointment(appointment_data, cli_sk, teos_pk, teos_url, appointments_fo Returns: - :obj:`bool`: True if the appointment is accepted by the tower and the receipt is properly stored, false if any + :obj:`bool`: True if the appointment is accepted by the tower and the receipt is properly stored. False if any error occurs during the process. """ @@ -77,7 +86,7 @@ def add_appointment(appointment_data, cli_sk, teos_pk, teos_url, appointments_fo logger.error("The provided appointment JSON is empty") return False - if not check_sha256_hex_format(appointment_data.get("tx_id")): + if not is_256b_hex_str(appointment_data.get("tx_id")): logger.error("The provided txid is not valid") return False @@ -141,13 +150,13 @@ def get_appointment(locator, cli_sk, teos_pk, teos_url): teos_url (:obj:`str`): the teos base url. Returns: - :obj:`dict` or :obj:`None`: a dictionary containing thew appointment data if the locator is valid and the tower + :obj:`dict` or :obj:`None`: a dictionary containing the appointment data if the locator is valid and the tower responds. ``None`` otherwise. """ # FIXME: All responses from the tower should be signed. Not using teos_pk atm. - valid_locator = check_locator_format(locator) + valid_locator = is_locator(locator) if not valid_locator: logger.error("The provided locator is not valid", locator=locator) @@ -171,13 +180,14 @@ def load_keys(teos_pk_path, cli_sk_path, cli_pk_path): Loads all the keys required so sign, send, and verify the appointment. Args: - teos_pk_path (:obj:`str`): path to the TEOS public key file. + teos_pk_path (:obj:`str`): path to the tower public key file. cli_sk_path (:obj:`str`): path to the client private key file. cli_pk_path (:obj:`str`): path to the client public key file. Returns: - :obj:`tuple` or ``None``: a three item tuple containing a teos_pk object, cli_sk object and the cli_sk_der - encoded key if all keys can be loaded. ``None`` otherwise. + :obj:`tuple` or ``None``: a three-item tuple containing a ``PrivateKey``, a ``PublicKey`` and a ``str`` + representing the tower pk, user sk and user compressed pk respectively if all keys can be loaded. + ``None`` otherwise. """ if teos_pk_path is None: @@ -228,7 +238,7 @@ def post_request(data, endpoint): Returns: :obj:`dict` or ``None``: a json-encoded dictionary with the server response if the data can be posted. - None otherwise. + ``None`` otherwise. """ try: @@ -251,14 +261,14 @@ def post_request(data, endpoint): def process_post_response(response): """ - Processes the server response to an post request. + Processes the server response to a post request. Args: - response (:obj:`requests.models.Response`): a ``Response`` object obtained from the sent request. + response (:obj:`requests.models.Response`): a ``Response`` object obtained from the request. Returns: - :obj:`dict` or :obj:`None`: a dictionary containing the tower's response data if it can be properly parsed and - the response type is ``HTTP_OK``. ``None`` otherwise. + :obj:`dict` or :obj:`None`: a dictionary containing the tower's response data if the response type is + ``HTTP_OK`` and the response can be properly parsed. ``None`` otherwise. """ if not response: @@ -287,8 +297,8 @@ def parse_add_appointment_args(args): Parses the arguments of the add_appointment command. Args: - args (:obj:`list`): a list of arguments to pass to ``parse_add_appointment_args``. Must contain a json encoded - appointment, or the file option and the path to a file containing a json encoded appointment. + args (:obj:`list`): a list of command line arguments that must contain a json encoded appointment, or the file + option and the path to a file containing a json encoded appointment. Returns: :obj:`dict` or :obj:`None`: A dictionary containing the appointment data if it can be loaded. ``None`` @@ -332,7 +342,7 @@ def parse_add_appointment_args(args): def save_appointment_receipt(appointment, signature, appointments_folder_path): """ - Saves an appointment receipt to disk. A receipt consists in an appointment and a signature from the tower. + Saves an appointment receipt to disk. A receipt consists of an appointment and a signature from the tower. Args: appointment (:obj:`Appointment `): the appointment to be saved on disk. @@ -340,7 +350,7 @@ def save_appointment_receipt(appointment, signature, appointments_folder_path): appointments_folder_path (:obj:`str`): the path to the appointments folder. Returns: - :obj:`bool`: True if the appointment if properly saved, false otherwise. + :obj:`bool`: True if the appointment if properly saved. False otherwise. Raises: IOError: if an error occurs whilst writing the file on disk. @@ -420,6 +430,9 @@ def main(args, command_line_conf): if args: command = args.pop(0) + if command == "register": + sys.exit(help_register()) + if command == "add_appointment": sys.exit(help_add_appointment())