# JWT Message

The sample usecases in Authentication Basics and Multiple Resource Identities showcased how Resource Instances communicate with each other by using the the Source Identifier inside a Login Token.

An alternative way for Resources to communicate with each other is to use encrypted JSON Web Tokens (JWT). In order to create a encrypted JWT you will need to use HexaEight JWT Library

The main advantages of using JWT for exchanging secure messages are

Eliminate the need to exchange Login Token for Source Identification
Signed JWT cannot be tampered, as such the name of the source can be exposed in the JWT header
Ability to use a Random Password to sign the JWT and inturn use HexaEight Encryption to store the password inside the JWT.
Ability to secure the actual message body using HexaEight encryption.

A sample encrypted JWT can be inspected here for better clarity

The JWT consists of the following headers

alg: HS256

This is the actual algoritm that was used to sign the JWT. HS256 (HMAC with SHA-256) is a symmetric keyed hashing algorithm that uses one secret key. Symmetric means two parties share the secret key. The key is used for both generating the signature and validating it.

kid

The kid (key ID) Header Parameter is a hint indicating which key was used to secure the JWT. However in the case of HexaEight JWT, the kid contains the actual secret key that was used to sign the JWT, but protected using HexaEight Encryption.

issuer

The issuer tells us the source which created this JWT message thus eliminating the need to transmit the Login Token Source Identifier as part of the message.

type

The type field indicates that the JWT follows Javascript Object Signing and Encryption (JOSE) and JSON Web Token (JWT) standards for Signing and encryption.

channelSecurityContext

The channelSecurityContext field is used to highlight that the JWT was recived over a secure channel protected using HexaEight Encryption

iat

The Issued AT header contains the unix timestamp when the JWT was created

exp

The Expiry header contains the unix timestamp when the JWT can no longer be consumed

payload

The payload contains the encrypted data that is intended for the destination.

JWT Creation Example

The following process outlines the method to create an encrypted JWT when Resource A wants to send an encrypted JWT message to Resource B

%%{init: { 'theme': 'forest' } }%%
erDiagram
    HexaEightPlatform ||--|| ResourceA : Fetch-Machine-Token-of-ResourceB
    ResourceA ||--|| ResourceB : Sends-Encrypted-JWT
    ResourceA {
        Generate Random-Password-(SecretKey)
	Generates-KID By-Encrypting-SecretKey-Using-Machine-Token-of-Resource-B
	Encrypts-PAYLOAD By-Using-Machine-Token-of-Resource-B
	Populates JWT-Headers-like-ALG-KID-ISSUER-IAT-EXP
	Creates-JWT By-Adding-the-JWT-headers-And-Encrypted-Payload
	Signs-JWT By-Using-Generated-Random-Password
    }

Similarly Resource B uses the below procedure to decrypt the message received from Resource-A

%%{init: { 'theme': 'forest' } }%%
erDiagram

    ResourceB ||--|| JWT-Message-Inspection : Inspects-JWT-Header
    JWT-Message-Inspection {
        Check-EXP-Header Ensures-JWT-message-has-not-expired-and-still-valid
	Fetch-ISSUER-Header To-Fetch-Machine-Token
    }
    HexaEightPlatform ||--|| ResourceB : Fetch-Machine-Token-of-ResourceA
    ResourceB ||--|| JWT-Message-Decryption : Decrypts-JWT
    JWT-Message-Decryption {
	Decrypts-KID Using-Resource-A-Machine-Token-And-Obtains-Secret-Key
	Validates-JWT By-Computing-Signature-using-HS256-Algorithm-using-Secret-Key
	Decrypts-PAYLOAD By-Using-Machine-Token-of-Resource-B
    }

HexaEight JWT Library provides the below two important functions to create HexaEight JWT

CreateEncryptedJWTTokenDirect : Fetches Machine Token of Destination and Creates Encrypted JWT

CreateEncryptedJWTTokenUsingSharedKey : Pass a Machine Token(Asymmetric Shared Key) to Create Encrypted JWT

as well as these two functions to decrypt the JWT

ValidateTokenDirect : Fetches Machine Token of Source using the JWT ISSUER header and decrypts the JWT payload

ValidateTokenUsingSharedKey : Pass a Machine Token(Asymmetric Shared Key) to decrypt the JWT payload.

Summary

HexaEight JWT Library can be used to securely transmit message between resources.

Source Resource uses the KID header to encrypt a random secret key that is used to sign the message
Destination Resource uses the KID header to decrypt the secret key by fetching a machine token of the source resource which is indicated in the ISSUER header
HexaEight JWT Library provides easy methods that can be used to create JWT messages