From 68c568670ce2608153e0d5709b0a08b2418431b4 Mon Sep 17 00:00:00 2001 From: Yigit Sever Date: Thu, 15 Apr 2021 05:30:53 +0300 Subject: Start frontend --- site/config.toml | 1 + site/content/JWT.md | 38 ++++++++- site/content/_index.md | 61 ++++++++++++++- site/public/block-docs/index.html | 2 +- site/public/index.html | 134 +++++++++++++++++++++++++++----- site/public/jwt/index.html | 62 +++++++++++++-- site/public/register-docs/index.html | 2 +- site/public/search_index.en.js | 2 +- site/public/transaction-docs/index.html | 2 +- site/templates/index.html | 33 ++++---- 10 files changed, 288 insertions(+), 49 deletions(-) (limited to 'site') diff --git a/site/config.toml b/site/config.toml index 93e9468..8754d85 100644 --- a/site/config.toml +++ b/site/config.toml @@ -13,6 +13,7 @@ build_search_index = true # Whether to do syntax highlighting # Theme can be customised by setting the `highlight_theme` variable to a theme supported by Zola highlight_code = true +highlight_theme = "subway-moscow" [extra] # Put all your custom variables here diff --git a/site/content/JWT.md b/site/content/JWT.md index 91a7a73..f55ab17 100644 --- a/site/content/JWT.md +++ b/site/content/JWT.md @@ -4,8 +4,38 @@ description = "JSON Web Token Documentation" weight = 5 +++ -Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod -tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At -vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd -ubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. +> JSON Web Tokens are representations of claims, or authorization proofs that fit into the `Header` of HTTP requests. + +# How? + +JWTs are used as the [MAC](https://en.wikipedia.org/wiki/Message_authentication_code) of operations that require authorization: +- block proposal +- transaction proposal. + +They are send alongside the JSON request body in the `Header`; + +```html +Authorization: Bearer aaaaaa.bbbbbb.ccccc +``` + +Gradecoin uses 3 fields for the JWTs; + +```json +{ +"tha": "Hash of the payload, check invididual references", +"iat": "Issued At, Unix Time", +"exp": "Expiration Time, epoch" +} +``` + +- `tha` is explained in [blocks](@/block_docs.md) and [transactions](@/transaction_docs.md) documentations. +- `iat` when the JWT was created in [Unix Time](https://en.wikipedia.org/wiki/Unix_time) format +- `exp` when the JWT will expire & be rejected in [Unix Time](https://en.wikipedia.org/wiki/Unix_time) + +# Algorithm +We are using [RS256](https://www.rfc-editor.org/rfc/rfc7518.html#section-3.1), `RSASSA-PKCS1-v1_5 using SHA-256`. The JWTs you encode with your private RSA key will be decoded using the public key you have authenticated with. You can see how the process works [here](https://jwt.io/). + +# References +- [RFC, the ultimate reference](https://tools.ietf.org/html/rfc7519) +- [JWT Debugger](https://jwt.io/) diff --git a/site/content/_index.md b/site/content/_index.md index 7dd7a7c..bf33eef 100644 --- a/site/content/_index.md +++ b/site/content/_index.md @@ -3,8 +3,35 @@ title = "Gradecoin" sort_by = "weight" +++ -- Don't know where to start? Gradecoin uses RESTful API, simple `curl` commands or even your browser will work! [This website can help as well](https://curl.trillworks.com/). -- [JWT Debugger](https://jwt.io) and the corresponding [RFC](https://tools.ietf.org/html/rfc7519) +# Welcome to Gradecoin! + +Blockchains are incredibly simple yet can appear very complicated, we will see how they work and practice programming _production_ cryptography code. + +This server is the sandbox for the PA1, it's currently running the Gradecoin application. Gradecoin is the faux currency we will use to simulate a blockchain network. At the end of the simulation, the amount of Gradecoin you hold will be your PA1 grade. + +**A quick summary**: authenticate yourself to the system using public key encryption. +Craft [Transaction](@/transaction_docs.md) proposals and tag them using [JWTs](@/JWT.md). +When there are enough transactions then you can propose [Blocks](@/block_docs.md) in the same way. +Blocks need to be _mined_ beforehand using Proof-of-work, or brute force. + +Gradecoin offers 3 endpoints at [/register](/register), [/block](/block) and [/transaction](/transaction). You can only send GET requests to /block and /transaction without authorization. +The server is programmed in [RESTful](https://www.service-architecture.com/articles/web-services/representational_state_transfer_rest.html) architecture, there are no `DELETE`, `PUT` or `UPDATE` operations, though. + +Gradecoin uses a Proof-of-work block accepting mechanism. It uses single round [Blake2s](https://www.blake2.net/) hashing which produces 256-bit (64 hexadecimal characters) output. The [target](https://wiki.bitcoinsv.io/index.php/Target) hash is _24 bits_ or _6 hexadecimal characters_ of 0. During testing, I could mine a block on average around 2-7 minutes. + +> We're expecting you to use existing tools and implementations. Standards are hard. [Don't roll your own crypto](https://www.reddit.com/r/crypto/comments/2coqsy/dont_roll_your_own/). Feel free to ask questions. Collaborate. + +You might ask, + +> But if nobody has any Gradecoin then how do we have transactions? + +There is a bank! Their public key is `31415926535897932384626433832795028841971693993751058209749445923` and they have some amount of Gradecoin preloaded. It's also the only account that you can send transactions requests _to_ yourself. + +# Coinbase +The first transactions of a block is called the `coinbase`. They are the **author** of the block proposal and if the block is accepted then they get compensated for their efforts with some Gradecoin. + +# Public Key Signatures +Gradecoin uses 2048 bit RSA keyspairs. # Services ## /register @@ -26,3 +53,33 @@ sort_by = "weight" - fetch the last accepted [`schema::Block`] - GET request `Authorization`: The request header should have Bearer JWT.Token signed with Student Public Key + +# Questions +## This all sound complicated! +- I've drawn inspiration from [actual Bitcoin transactions](https://explorer.bitcoin.com/btc) and [warp](https://github.com/seanmonstar/warp/blob/master/examples/todos.rs). The simplicity of the system is how little interfaces it has. +- Don't know where to start? Gradecoin uses RESTful API; simple `curl` commands or even your browser will work! [This website can help as well](https://curl.trillworks.com/). +- [JWT Debugger](https://jwt.io) and the corresponding [RFC](https://tools.ietf.org/html/rfc7519) +- Remember that you are absolutely encouraged to grab off-the-shelf implementations for every cryptography primitive you will use. You can start by finding a code snippet to generate a RSA keypair? + +## I found a bug! +Thank you! Please [let me know](mailto:yigit@ceng.metu.edu.tr) so we can solve it. + +## I hacked the server! +That wasn't supposed to happen :( I did not place any intentional vulnerabilities to the system so if you cracked something, it was not intended. Please don't abuse it and let me know so I can patch it. + +## Submission? +At the end of the _simulation_, your Gradecoin balance will be your grade. I will also expect a unique client programmed in either; +- c +- c++ +- perl +- rust +- python +- random assortment of bash scripts + +If your favourite programming language is missing please let me know 🤷? + +## Can my friends play? +Sadly, no. Student's who are enrolled to the class will receive one-time-passwords for authentication. + +## How and or Why? +- [Built](https://xkcd.com/2314/), with [Rust](https://xkcd.com/2418/) diff --git a/site/public/block-docs/index.html b/site/public/block-docs/index.html index 8331952..3da4e8b 100644 --- a/site/public/block-docs/index.html +++ b/site/public/block-docs/index.html @@ -84,7 +84,7 @@ ubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet.