uport-jwt

The uPort-JWT library allows you to sign and verify JSON Web Tokens (JWT). Public keys are resolved using the Decentralized ID (DID) of the iss claim of the JWT.

JWT Details

Algorithms supported

• ES256k the secp256k1 ECDSA curve

Claims

Name | Description | Required ---- | ----------- | -------- iss | The DID of the signing identity| yes sub | The DID of the subject of the JWT| no aud | The DID or URL of the audience of the JWT. Our libraries or app will not accept any JWT that has someone else as the audience| no iat | The time of issuance | yes exp | Expiration time of JWT | no

Installation

npm install uport-jwt

or if you use yarn

yarn add uport-jwt

API

Creating a JWT

Use the createJWT() function

import { createJWT, SimpleSigner } from 'uport-jwt'

const signer = SimpleSigner('PRIVATEKEY')

createJWT(
    {aud: 'did:uport:did:uport:2nQtiQG6Cgm1GYTBaaKAgr76uY7iSexUkqY', exp: 1485321133, name: 'Bob Smith'},
    {issuer: 'did:uport:2nQtiQG6Cgm1GYTBaaKAgr76uY7iSexUkqX', signer}).then(jwt => {
    console.log(jwt)
})

Parameters

createJWT(payload, settings)

Name | Description | Required ---- | ----------- | -------- payload | an object containing any claims you want to encode in the JWT including optional standard claims such as sub, aud and exp | yes settings.issuer | The DID of the audience of the JWT | yes settings.signer | A signing function (see SimpleSigner) | yes settings.expiresIn | How many seconds after signing should the JWT be valid (sets the exp claim) | no

Promise Return Value

The createJWT() function returns a Promise.

A successfull call returns an object containing the following attributes:

Name | Description ---- | ----------- jwt | String containing a JSON Web Tokens (JWT)

If there are any errors found during the signing process the promise is rejected with a clear error message.

Verifying a JWT

Use the verifyJWT() function

import { verifyJWT } from 'uport-jwt'

verifyJWT('eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NksifQ.eyJpc3MiOiJkaWQ6dXBvcn....', {audience: 'Your DID'}).then({payload, doc, did, signer, jwt} => {
    console.log(payload)
})

Parameters

verifyJWT(jwt, options)

Name | Description | Required ---- | ----------- | -------- jwt | String containing a JSON Web Tokens (JWT) | yes options.audience | The DID of the audience of the JWT | no options.callbackUrl | The the URL receiving the JWT | no

Promise Return Value

The verifyJWT() function returns a Promise.

A successfull call returns an object containing the following attributes:

Name | Description ---- | ----------- payload | An object containing the JSON parsed contents of the payload section of the JWT issuer | The DID of the issuer of the JWT signer | An object containing information about which key signed the JWT. This is useful if a DID document has multiple keys listed doc | The DID Document of the issuer of the JWT jwt | The original JWT passed in to the function

If there are any errors found during the verification process the promise is rejected with a clear error message.

Signer Functions

We provide a simple signing abstraction that makes it easy to add support for your own Key Management infrastructure.

SimpleSigner

For most people you can use our SimpleSigner() function to creaate a signer function using a hex encoded private key.

import { SimpleSigner } from 'uport-jwt'
const signer = SimpleSigner('278a5de700e29faae8e40e366ec5012b5ec63d36ec77e8a2417154cc1d25383f')

Parameters

SimpleSigner(privateKey)

Name | Description | Required ---- | ----------- | -------- privateKey | hex encoded secp256k1 privatekey | yes

Note this is NOT a constructor, but a higher order function that returns a signing function.

Creating Custom Signers for integrating with HSM

You can easily create custom signers that integrates into your existing signing infrastructure. A signer function takes the raw data to be signed and returns a Promise containing the signature parameters.

function mySigner (hash) {
    return new Promise((resolve, reject) => {
        const signature = /// sign it
        resolve(signature)
    })
}

Parameters

Name | Description | Required ---- | ----------- | -------- hash | Buffer containing hash of data to be signed | yes

Promise Return Value

Your function must returns a Promise.

A successfull call returns an object containing the following attributes:

Name | Description ---- | ----------- r | Hex encoded r value of secp256k1 signature | yes s | Hex encoded s value of secp256k1 signature | yes recoveryParam | Recovery parameter of signature (can be used to calculate signing public key) | no