Adding YIP-0005 details (#117)

* Adding YIP details

* Adding YIP-0005 Adding the channel Authorization flow

docs/YIP/YIP-0005-subkey-management.md

@@ -1,8 +1,8 @@
-# 0005 - Subkey Management
+# 0005 - Sub-key Management
 
 ## Status
 
-In Work
+Work in progress
 
 ## Context
 
@@ -12,9 +12,81 @@ End User MUST be able to set expiration time of the subkey, revoke issued subkey
 
 ## Decision
 
+A lightweight certification protocol should utilize JSON Web Tokens (JWT), which are compact, URL-safe means of representing claims to be transferred between two parties. JWTs can include metadata and are digitally signed using a key pair. Below a simplified example of how Alice can use JWTs to certify the `clearport` subkey.
 
+### Certification Protocol Overview
+
+1. **Key Generation:** Both Alice and `clearport` generate their key pairs. Alice's keypair is her wallet keypair, and `clearport` generates a subkey using KMS.
+2. **Certificate Creation:** Alice creates a JWT to serve as the certificate for the `clearport` subkey. The JWT contains claims about the `clearport` subkey, such as the public key, ENS, expiration, and other metadata.
+3. **Signing Certificate:** Alice signs the JWT using her private key.
+4. **Verification:** Any party can verify the JWT using Alice's public key.
+5. **Revocation:** To revoke the certificate, Alice can maintain a revocation list or use a smart contract to flag the revoked subkeys.
+
+### Example Code
+
+Here's a simple example using Ruby with the `ruby-jwt` gem for JWT handling. This is just to illustrate the process; you'll need to adapt it to your exact requirements and ensure security best practices.
+
+```ruby
+require 'jwt'
+require 'openssl'
+
+# Alice's wallet keypair
+alice_private_key = OpenSSL::PKey::RSA.generate(2048)
+alice_public_key = alice_private_key.public_key
+
+# Clearport's subkey from KMS
+clearport_subkey = OpenSSL::PKey::RSA.generate(2048)
+clearport_subkey_public = clearport_subkey.public_key.to_pem
+
+# Current time and expiration time for the JWT
+current_time = Time.now.to_i
+expiration_time = current_time + 365 * 24 * 60 * 60 # 1 year from now
+
+# Certificate (JWT) payload with standard claims
+claims = {
+  iss: "0xAliceWalletAddress",          # Issuer: Alice wallet
+  ens: "alice.eth"			  			# Name: Alice
+  sub: "cert:0xClearport_subkey",       # Subject: Purpose of the JWT
+  aud: "canarynet",                     # Audience: Intended recipients
+  exp: expiration_time,                 # Expiration Time
+  nbf: current_time,                    # Not Before
+  iat: current_time,                    # Issued At
+  jti: SecureRandom.uuid                # JWT ID: Unique identifier for the JWT
+}
+
+# Alice signs the JWT using her private key
+cert_token = JWT.encode(claims, alice_private_key, 'RS256')
+
+# Verification (any party would use Alice's public key)
+begin
+  decoded_token = JWT.decode(cert_token, alice_public_key, true, { algorithm: 'RS256' })
+  puts "Certificate is valid: #{decoded_token}"
+rescue JWT::DecodeError => e
+  puts "Invalid certificate: #{e.message}"
+end
+
+# Revocation method
+def revoke_subkey(subkey_id)
+  # Logic to revoke the key, e.g., update a list or a smart contract
+  puts "Subkey #{subkey_id} revoked."
+end
+
+```
+
+### Opening State Channels
+
+1. Pre-Authorization `turnNum=0` would contain in the `appData` the information to verify
+2. Both parties fetch from the `Adjudicator.LookUp(0xParticipantAddress) => ipfs://certificate_location.json`
+3. If certificate value post parties signs Post-Authorization step.
+4. Parties can move on funding steps.
 
 ## Consequences
 
--
+- Use JWTs for creating a certificate for the `clearport` subkey.
+- Include metadata like the public key, ENS, wallet address, and expiration in the JWT claims.
+- Alice signs the JWT with her private key to issue the certificate.
+- Verification is done using Alice's public key.
+- Revocation can be handled with a list or smart contract.
+
+Remember to handle key management securely, use appropriate cryptographic algorithms, and implement proper error handling in your actual code.