Client topic

delivery3/features.adoc

@@ -219,3 +219,39 @@ a| * `Authorization: token`
 | ROLE_MOD
 
 |===
+
+=== Client Interaction
+
+For the client, each command is executed via terminal and it is used multiple tools with specific functionalities:
+
+* Argparse footnote:[https://docs.python.org/3/library/argparse.html] → Check for errors in arguments given by the user.
+* Logging footnote:[https://docs.python.org/3/library/logging.html] → Logging system to send out messages such as errors.
+* OS footnote:[https://docs.python.org/3/library/os.html] → Add path to local folder `~/.sio` to save or load any files used by the current command.
+* Requests footnote:[https://requests.readthedocs.io/en/latest/] → Main library to allow communication from the client to the API.
+
+For every command the argument `-r` is present to set the API's address. It is needed to define if it wasn't previously, otherwise an error is cast with the corresponding message.
+
+To use the API, it is first needed to create a public key to create an organization with the key.
+The command `rep_subject_credentials` it is generated a keypair using RSA with a given password and both public and private keys are saved in different files.
+
+==== Creating an Organization
+
+The command `rep_create_org` creates an organization and for it the client must give the file containing his public key in order to create a session afterwards.
+
+==== Creating a session
+For the client to use the Authenticated API, the command `rep_create_session` allows the user to create a session and assume an identity. This command also protects information that shouldn't be visible to outsiders when it's being transfered between the client and the server.
+
+To protect the information, the client and the server initiate a Diffie-Hellman footnote:[https://cryptography.io/en/latest/hazmat/primitives/asymmetric/dh/] key exchange where both create a key pair with the same parameters and share each other their public key to derive with their own private key and obtain a common key which can be used to encrypt and decrypt information between both entities.
+
+[source, python]
+----
+generator = 2; key_size = 1024
+parameters = generate_parameters(generator, key_size)
+private_key, public_key = generate_key_pair(parameters)
+
+response = req.json()
+server_public_key = serialization.load_pem_public_key(bytes.fromhex(response['public_key']))
+derived_key = derive_keys(private_key, server_public_key)
+----
+
+If the exchange is succesful, the client will attempt to login using it's private key that should be given when executing this command.