From c30b51d53770f5e104585f8203a92cb99444fbfa Mon Sep 17 00:00:00 2001 From: Jakob Lorz Date: Tue, 7 Feb 2017 15:07:49 +0100 Subject: [PATCH 1/5] Started rewriting the readme --- README.md | 33 ++++++++++++++++++++++----------- 1 file changed, 22 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index aef4a8d..00aac34 100644 --- a/README.md +++ b/README.md @@ -1,27 +1,38 @@ -# node-jwt-simple +# Welcome +Secure your application in seconds using standardised **JWT-Tokens**. [RFC 7519](https://tools.ietf.org/html/rfc7519) -[JWT(JSON Web Token)](http://self-issued.info/docs/draft-jones-json-web-token.html) encode and decode module for node.js. +[![npm version](https://badge.fury.io/js/jwt-simple.svg)](https://badge.fury.io/js/jwt-simple) -## Install +## Sample Use-Case +You may use this as an authentication-method for your API: on one route you encode a token, storing the authenticated user (e.g. after checking password and email) in it. On all other routes you check if the token is valid - this indicates that the user once did authenticate himself successfully. +## Installation $ npm install jwt-simple ## Usage - +### Encoding Data and Creating a new Token ```javascript var jwt = require('jwt-simple'); -var payload = { foo: 'bar' }; -var secret = 'xxx'; // HS256 secrets are typically 128-bit random strings, for example hex-encoded: -// var secret = Buffer.from('fe1a1915a379f3be5394b64d14794932', 'hex) +var secret = Buffer.from('fe1a1915a379f3be5394b64d14794932', 'hex'); + +var payload = { 'foo': 'bar' }; -// encode +//create a new token by encoding the payload object into it var token = jwt.encode(payload, secret); +``` + + + +### Decoding the Token to the Encoded Object +```javascript +var jwt = require('jwt-simple'); +var secret = Buffer.from('fe1a1915a379f3be5394b64d14794932', 'hex'); + +var payload = jwt.decode(token, secret); +console.log(payload); //-> { 'foo': 'bar' } -// decode -var decoded = jwt.decode(token, secret); -console.log(decoded); //=> { foo: 'bar' } ``` ### decode params From f77848a363d2f9ee8e65d25165379bff4ac5038a Mon Sep 17 00:00:00 2001 From: Jakob Lorz Date: Tue, 7 Feb 2017 15:24:34 +0100 Subject: [PATCH 2/5] Added description for decode --- README.md | 52 ++++++++++++++++++++++++---------------------------- 1 file changed, 24 insertions(+), 28 deletions(-) diff --git a/README.md b/README.md index 00aac34..042376e 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,15 @@ You may use this as an authentication-method for your API: on one route you enco $ npm install jwt-simple ## Usage -### Encoding Data and Creating a new Token +### Encoding +Encode a Object into your token - the `jwt.encode` function takes a maximum of 3 parameters: + +| Name | Description | Optional? | +| --- | --- | --- | +| payload | the object you want to encode into the token | No | +| secret | you secret | No | +| algorithm | there are 4 different algorithms `HS256`, `HS384`, `HS512` and `RS256` - standard is `HS256` | Yes | + ```javascript var jwt = require('jwt-simple'); @@ -21,49 +29,37 @@ var payload = { 'foo': 'bar' }; //create a new token by encoding the payload object into it var token = jwt.encode(payload, secret); + +//encode using HS512 +var token = jwt.encode(payload, secret, 'HS512'); ``` +### Decoding +Decode a Token returning the encoded Object - the `jwt.decode` function takes a maximum of 4 parameters + +| Name | Description | Optional? | +| --- | --- | --- | +| token | the token previously generated | No | +| secret | key which previously encoded the token | No | +| noVerify | turn off verifying **ON YOUR OWN RISK** | Yes | +| algorithm | select another algorithm. see encode for algorithm options. | Yes, but noVerify must been set | -### Decoding the Token to the Encoded Object ```javascript var jwt = require('jwt-simple'); var secret = Buffer.from('fe1a1915a379f3be5394b64d14794932', 'hex'); -var payload = jwt.decode(token, secret); -console.log(payload); //-> { 'foo': 'bar' } - -``` - -### decode params - -```javascript -/* - * jwt.decode(token, key, noVerify, algorithm) - */ - // decode, by default the signature of the token is verified var decoded = jwt.decode(token, secret); -console.log(decoded); //=> { foo: 'bar' } +console.log(decoded); //-> { foo: 'bar' } // decode without verify the signature of the token, // be sure to KNOW WHAT ARE YOU DOING because not verify the signature // means you can't be sure that someone hasn't modified the token payload var decoded = jwt.decode(token, secret, true); -console.log(decoded); //=> { foo: 'bar' } +console.log(decoded); //-> { foo: 'bar' } // decode with a specific algorithm (not using the algorithm described in the token payload) var decoded = jwt.decode(token, secret, false, 'HS256'); -console.log(decoded); //=> { foo: 'bar' } -``` - -### Algorithms - -By default the algorithm to encode is `HS256`. - -The supported algorithms for encoding and decoding are `HS256`, `HS384`, `HS512` and `RS256`. - -```javascript -// encode using HS512 -jwt.encode(payload, secret, 'HS512') +console.log(decoded); //-> { foo: 'bar' } ``` From 83bfd251e6ba5a928de26c4f8ccd04492a627869 Mon Sep 17 00:00:00 2001 From: Jakob Lorz Date: Tue, 7 Feb 2017 15:25:08 +0100 Subject: [PATCH 3/5] Update README.md --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 042376e..75fe016 100644 --- a/README.md +++ b/README.md @@ -42,8 +42,8 @@ Decode a Token returning the encoded Object - the `jwt.decode` function takes a | --- | --- | --- | | token | the token previously generated | No | | secret | key which previously encoded the token | No | -| noVerify | turn off verifying **ON YOUR OWN RISK** | Yes | -| algorithm | select another algorithm. see encode for algorithm options. | Yes, but noVerify must been set | +| noVerify | turn off verification **ON YOUR OWN RISK** | Yes | +| algorithm | select another algorithm. see encode for algorithm options. | Yes, but noVerify must been set before | ```javascript var jwt = require('jwt-simple'); From ed9f5029570016ab2044d30108b70e51030da388 Mon Sep 17 00:00:00 2001 From: Jakob Lorz Date: Tue, 7 Feb 2017 15:31:10 +0100 Subject: [PATCH 4/5] added logo to readme --- README.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/README.md b/README.md index 75fe016..1104a87 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,7 @@ +
+

+
+ # Welcome Secure your application in seconds using standardised **JWT-Tokens**. [RFC 7519](https://tools.ietf.org/html/rfc7519) From 4b6aa48153d4f03eb386eb1e850775989802b3ed Mon Sep 17 00:00:00 2001 From: Jakob Lorz Date: Tue, 7 Feb 2017 15:32:09 +0100 Subject: [PATCH 5/5] Update README.md --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 1104a87..62b2a09 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@ -
-

+
+

# Welcome