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