From 0f67c6c79325078ad71f666915c065d15d417814 Mon Sep 17 00:00:00 2001
From: Yigit Sever
Date: Fri, 16 Apr 2021 15:30:59 +0300
Subject: Improve register documentation
---
site/public/register-docs/index.html | 36 ++++++++++++++++++++++++++++++------
1 file changed, 30 insertions(+), 6 deletions(-)
(limited to 'site/public/register-docs')
diff --git a/site/public/register-docs/index.html b/site/public/register-docs/index.html
index 810f4ec..9d9c91d 100644
--- a/site/public/register-docs/index.html
+++ b/site/public/register-docs/index.html
@@ -27,6 +27,7 @@
<link rel="stylesheet" href="https://gradecoin.xyz/juice.css">
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/animate.css/4.1.1/animate.min.css" />
+<link rel="stylesheet" href="/site.css" />
</head>
@@ -76,6 +77,16 @@
</div>
+ <div class="toc-item-child">
+ <a class="subtext" href="https://gradecoin.xyz/register-docs/#cipher-initialization"><small>- Cipher Initialization</small></a>
+ </div>
+
+ <div class="toc-item-child">
+ <a class="subtext" href="https://gradecoin.xyz/register-docs/#encryption"><small>- Encryption</small></a>
+ </div>
+
+
+
</div>
</div>
@@ -87,7 +98,7 @@
<p>POST request to <code>/register</code> endpoint</p>
<p>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.</p>
+This is enforced with your Student ID (e123456) and a one time password you will receive.</p>
<h1 id="authentication-process">Authentication Process</h1>
<blockquote>
<p>The bytes you are sending over the network are all Base64 Encoded</p>
@@ -102,13 +113,26 @@ This is enforced with your Student ID and a one time password you will receive.<
"</span><span style="color:#009854;">passwd</span><span style="color:#545052;">": "</span><span style="color:#009854;">15 char secret</span><span style="color:#545052;">",
"</span><span style="color:#009854;">public_key</span><span style="color:#545052;">": "</span><span style="color:#009854;">---BEGIN PUBLIC KEY...</span><span style="color:#545052;">"
}
-</span></code></pre>
+</span></code></pre><h2 id="cipher-initialization">Cipher Initialization</h2>
+<blockquote>
+<p>Since we are working with AES-128, both key and IV should be 128 bits (or 16 hexadecimal characters)</p>
+</blockquote>
<ul>
<li>Pick a short temporary key (<code>k_temp</code>)</li>
-<li>Pick a random IV (<code>iv</code>).</li>
-<li>Encrypt the serialized string of <code>P_AR</code> with 128 bit block AES in CBC mode with Pkcs7 padding using the temporary key (<code>k_temp</code>), the result is <code>C_AR</code>. Encode this with base64.</li>
-<li>The temporary key you have picked <code>k_temp</code> is encrypted using RSA with OAEP padding scheme using SHA-256 with <code>gradecoin_public_key</code>, giving us <code>key_ciphertext</code>. Encode this with base64.</li>
+<li>Pick a random IV <a href="https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation#Initialization_vector_(IV)">1</a> <a href="https://en.wikipedia.org/wiki/Initialization_vector">2</a> (<code>iv</code>).</li>
+</ul>
+<h2 id="encryption">Encryption</h2>
+<ul>
+<li>Encrypt the serialized string of <code>P_AR</code> with 128 bit block <a href="https://en.wikipedia.org/wiki/Initialization_vector">AES</a> in <a href="https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation#CBC">CBC</a> mode with <a href="https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation#Padding">Pkcs7 padding</a> using the temporary key (<code>k_temp</code>), the result is <code>C_AR</code>. Encode this with base64.</li>
+<li>The temporary key you have picked <code>k_temp</code> is encrypted using RSA with <a href="https://en.wikipedia.org/wiki/Optimal_asymmetric_encryption_padding">OAEP</a> padding scheme using SHA-256 with <code>gradecoin_public_key</code>, giving us <code>key_ciphertext</code>. Encode this with base64.</li>
<li>Base64 encode the IV (<code>iv</code>) as well.</li>
+</ul>
+<blockquote class="tidbit">
+ <p>
+ The available tools and libraries might warn you about how using the primitives given above are "hazardous". They are, crypto is hard.
+ </p>
+</blockquote>
+<ul>
<li>The payload JSON object (<code>auth_request</code>) can be serialized now:</li>
</ul>
<pre style="background-color:#ffffff;">
@@ -119,7 +143,7 @@ This is enforced with your Student ID and a one time password you will receive.<
}
</span></code></pre>
<p>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.</p>
+You can now sign <a href="https://gradecoin.xyz/jwt/">JWTs</a> to send authorized transaction requests.</p>
</div>
--
cgit v1.2.3-70-g09d2