From 109ae1f771ec5e8a5a9510c3b09fad579dab5ed7 Mon Sep 17 00:00:00 2001
From: Yigit Sever
Date: Fri, 16 Apr 2021 13:56:45 +0300
Subject: Improve auth documentation

---
 site/content/register_docs.md | 26 +++++++++++++++-----------
 1 file changed, 15 insertions(+), 11 deletions(-)

(limited to 'site/content')

diff --git a/site/content/register_docs.md b/site/content/register_docs.md
index 83aef7f..a387838 100644
--- a/site/content/register_docs.md
+++ b/site/content/register_docs.md
@@ -4,36 +4,40 @@ description = "Register Documentation"
 weight = 3
 +++
 
-POST request to /register endpoint
+POST request to `/register` endpoint
 
 Lets a user to authenticate themselves to the system.
 Only people who are enrolled to the class can open Gradecoin accounts.
 This is enforced with your Student ID and a one time password you will receive.
 
 # Authentication Process
-- Gradecoin's Public Key (`gradecoin_public_key`) is listed on our Moodle page.
-- You pick a short temporary key (`k_temp`)
-- Create a JSON object (`auth_plaintext`) with your `metu_id` and `public key` in base64 (PEM) format (`S_PK`) [reference](https://tls.mbed.org/kb/cryptography/asn1-key-structures-in-der-and-pem)
+
+> The bytes you are sending over the network are all Base64 Encoded
+
+- Gradecoin's Public Key (`gradecoin_public_key`) is listed on our Moodle page. Download and load it it to your client.
+- Create a JSON object (`P_AR`) with your `metu_id` ("e"+`6 chars`) and `public key` in base64 (PEM) format (`S_PK`) [reference](https://tls.mbed.org/kb/cryptography/asn1-key-structures-in-der-and-pem)
 ```json
 {
-    "student_id": "e12345",
+    "student_id": "e123456",
     "passwd": "15 char secret",
     "public_key": "---BEGIN PUBLIC KEY..."
 }
 ```
 
-- Pick a random IV.
-- Encrypt the serialized string of `auth_plaintext` with 128 bit block AES in CBC mode with Pkcs7 padding using the temporary key (`k_temp`), the result is `auth_ciphertext`. Encode this with base64.
-- The temporary key you have picked `k_temp` is encrypted using RSA with OAEP padding scheme
-using SHA-256 with `gradecoin_public_key`, giving us `key_ciphertext`. Encode this with base 64.
+- Pick a short temporary key (`k_temp`)
+- Pick a random IV (`iv`).
+- Encrypt the serialized string of `P_AR` with 128 bit block AES in CBC mode with Pkcs7 padding using the temporary key (`k_temp`), the result is `C_AR`. Encode this with base64.
+- The temporary key you have picked `k_temp` is encrypted using RSA with OAEP padding scheme using SHA-256 with `gradecoin_public_key`, giving us `key_ciphertext`. Encode this with base64.
+- Base64 encode the IV (`iv`) as well.
 - The payload JSON object (`auth_request`) can be serialized now:
 
 ```json
 {
-    "c": "auth_ciphertext",
-    "iv": "hexadecimal",
+    "c": "C_AR",
+    "iv": "iv",
     "key": "key_ciphertext"
 }
 ```
 
 If your authentication process was valid, you will be given access and your public key fingerprint that is your address.
+You can now sign JWTs to send authorized transaction requests.
-- 
cgit v1.2.3-70-g09d2