Initial commit

README.md

@@ -0,0 +1,94 @@
+# SimpleJwt
+
+This is a simple library for generating (signing) and verifying JWT tokens. It
+is by no means an advanced library. If you just need to sign and refresh tokens
+for users of your site or intranet, this will work great. If you need all the
+glorious features of the JWT spec you should look elsewhere. 
+
+* Only handles HMAC-SHA256.
+* Only handles expiry ('exp') natively
+* Doesn't use any X.509 stuff.
+
+
+## Use Cases
+
+Use this to avoid having to rewrite the wheel when implementing authorization
+internally within a system where OAuth may be overkill.
+
+* Make good use of the expiry. JWTs aren't armored in any way, so make sure
+  they can't be used longer than they have to. (An hour is a good idea)
+* Make sure you understand the security aspects of JWTs.
+
+## Installation
+
+Install using composer:
+
+    $ composer require noccylabs/simple-jwt:@dev
+
+## Usage
+
+You need a key for both generating and parsing tokens. Create a `JwtDerivedKey`
+or a `JwtPlaintextKey` and pass it to the `JwtToken` constructor:
+
+    use NoccyLabs\SimpleJwt\Key\{JwtDerivedKey,JwtPlaintextKey}
+
+    // Derive a key using secret and salt...
+    $key = new JwtDerivedKey("secret", "salt");
+    // ...or use a prepared plaintext key
+    $key = new JwtPlaintextKey("This Should Be Binary Data..");
+
+### Generating tokens
+
+
+
+    use NoccyLabs\SimpleJwt\JwtToken;
+
+    $tok = new JwtToken($key);
+    $tok->setExpiry("1h");
+    $tok->claims->add("some/claim/MaxItems", 8);
+
+    $str = $tok->getSignedToken();
+
+
+### Parsing tokens
+
+Parsing is done by passing the raw token as the 2nd parameter
+
+    use NoccyLabs\SimpleJwt\JwtToken;
+
+    $str = "...received token...";
+
+    $tok = new JwtToken($key, $str);
+
+    if (!$tok->isValid()) {
+        // This check works, but using the validator might be better
+    }
+
+    // Using ->has() follwed by ->get() is one way
+    if ($tok->claims->has("some/claim/MaxItems")) {
+        // The claim exists, we can get the value (if any)
+        $val = $tok->claims->get("some/claim/MaxItems");
+    }
+
+    // You can also use valueOf() to return a default value if needed
+    $val = $tok->claims->valueOf("some/claim/MaxItems", 64);
+
+### Validating tokens
+
+    use NoccyLabs\SimpleJwt\Validator\JwtValidator;
+
+    $validator = new JwtValidator();
+    // Require that the claim exists
+    $validator->addRequiredClaim("some/required/Claim");
+    // Require that the claim exists and has a value of true
+    $validator->addRequiredClaimWithValue("some/required/OtherClaim", true);
+
+    try {
+        // Pass a JwtToken to validateToken()...
+        $valid = $validator->validateToken($tok);
+        // ...or pass a JwtKeyInterface and the raw string to validate()
+        $valid = $validator->validate($key, $tokenstr);
+    }
+    catch (JwtValidatorException $e) {
+        // validation failed
+    }