5 files changed, 221 insertions, 0 deletions

diff --git a/site/content/JWT.md b/site/content/JWT.md
new file mode 100644
index 0000000..46da1a2
--- /dev/null
+++ b/site/content/JWT.md
@@ -0,0 +1,41 @@
++++
+title = "JWT"
+description = "JSON Web Token Documentation"
+weight = 4
++++
+
+> 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
new file mode 100644
index 0000000..4ad0544
--- /dev/null
+++ b/site/content/_index.md
@@ -0,0 +1,85 @@
++++
+title = "Gradecoin"
+sort_by = "weight"
++++
+
+# 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
+- Student creates their own 2048 bit RSA `keypair`
+- Downloads `Gradecoin`'s Public Key from [Moodle](https://odtuclass.metu.edu.tr/my/)
+- Encrypts their JSON wrapped `Public Key`, `Student ID` and one time `passwd` using Gradecoin's Public Key
+- Their public key is now in our database and can be used to sign their JWT's during requests
+
+## /transaction
+- You can offer a [Transaction](/transaction) - POST request
+    - The request should have `Authorization`
+    - The request header should be signed by the Public Key of the `by` field in the transaction
+- fetch the list of `Transaction`s - GET request
+
+## /block
+- offer a [`schema::Block`] - POST request
+    - The request should have `Authorization`
+    - The [`schema::Block::transaction_list`] of the block should be a subset of [`schema::Db::pending_transactions`]
+- 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](https://lofi.cafe/) [Rust](https://xkcd.com/2418/)
diff --git a/site/content/block_docs.md b/site/content/block_docs.md
new file mode 100644
index 0000000..c1d61e9
--- /dev/null
+++ b/site/content/block_docs.md
@@ -0,0 +1,30 @@
++++
+title = "Blocks"
+description = "Block Documentation"
+weight = 10
++++
+
+A block that was proposed to commit Transactions in `transaction_list` to the
+ledger with a nonce that made `hash` valid; 6 zeroes at the left hand side of the
+hash (24 bytes).
+
+We are _mining_ using [blake2s](https://www.blake2.net/) algorithm, which produces 256 bit hashes. Hash/second is roughly 20x10^3 on my machine, a new block can be mined in around 4-6 minutes.
+
+# Requests
+
+## GET
+A HTTP `GET` request to [/block](/block) endpoint will return the latest mined block.
+
+## POST
+
+A HTTP `POST` request with Authorization using JWT will allow you to propose your own blocks.
+
+# Fields
+```
+transaction_list: [array of Fingerprints]
+nonce: unsigned 32-bit integer
+timestamp: ISO 8601 <date>T<time>
+hash: String
+```
+
+[ISO 8601 Reference](https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations)
diff --git a/site/content/register_docs.md b/site/content/register_docs.md
new file mode 100644
index 0000000..83aef7f
--- /dev/null
+++ b/site/content/register_docs.md
@@ -0,0 +1,39 @@
++++
+title = "Register"
+description = "Register Documentation"
+weight = 3
++++
+
+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)
+```json
+{
+    "student_id": "e12345",
+    "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.
+- The payload JSON object (`auth_request`) can be serialized now:
+
+```json
+{
+    "c": "auth_ciphertext",
+    "iv": "hexadecimal",
+    "key": "key_ciphertext"
+}
+```
+
+If your authentication process was valid, you will be given access and your public key fingerprint that is your address.
diff --git a/site/content/transaction_docs.md b/site/content/transaction_docs.md
new file mode 100644
index 0000000..820c35f
--- /dev/null
+++ b/site/content/transaction_docs.md
@@ -0,0 +1,26 @@
++++
+title = "Transactions"
+description = "Transaction documentation"
+weight = 6
++++
+
+A transaction request between `source` and `target` to move `amount` Gradecoin.
+
+# Requests
+
+## GET
+A HTTP `GET` request to [/transaction](/transaction) endpoint will return the current list of pending transactions.
+
+## POST
+
+A HTTP `POST` request with Authorization using JWT to [/transaction](/transactions) will allow you to propose your own transactions.
+
+
+# Fields
+```
+by: Fingerprint
+source: Fingerprint
+target: Fingerprint
+amount: unsigned 16 bit integer
+timestamp: ISO 8601 <date>T<time>
+```