kong.jwe

The JWE utility module provides utility functions around JSON Web Encryption.

kong.enterprise_edition.jwe.decrypt(key, token)

Decrypt JWE encrypted JWT token and returns its payload as plaintext

Supported keys (key argument):

  • Supported key formats:
    • JWK (given as a string or table)
    • PEM (given as a string)
    • DER (given as a string)
  • Supported key types:
    • RSA
    • EC, supported curves:
      • P-256
      • P-384
      • P-521

Parameters

  • key (string|table): Private key
  • token (string): JWE encrypted JWT token

Returns

  1. string: JWT token payload in plaintext, or nil

  2. string: Error message, or nil

Usage

  1. local jwe = require "kong.enterprise_edition.jwe"
  2. local jwk = {
  3.   kty = "EC",
  4.   crv = "P-256",
  5.   use = "enc",
  6.   x   = "MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4",
  7.   y   = "4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM",
  8.   d   = "870MB6gfuTJ4HtUnUvYMyJpr5eUZNP4Bk43bVdj3eAE",
  9. }
  10. local plaintext, err = jwe.decrypt(jwk,
  11.   "eyJhbGciOiJFQ0RILUVTIiwiZW5jIjoiQTI1NkdDTSIsImFwdSI6Ik1lUFhUS2oyWFR1NUktYldUSFI2bXci" ..
  12.   "LCJhcHYiOiJmUHFoa2hfNkdjVFd1SG5YWFZBclVnIiwiZXBrIjp7Imt0eSI6IkVDIiwiY3J2IjoiUC0yNTYi" ..
  13.   "LCJ4IjoiWWd3eF9NVXRLTW9NYUpNZXFhSjZjUFV1Z29oYkVVc0I1NndrRlpYRjVMNCIsInkiOiIxaEYzYzlR" ..
  14.   "VEhELVozam1vYUp2THZwTGJqcVNaSW9KNmd4X2YtUzAtZ21RIn19..4ZrIopIhLi3LeXyE.-Ke4ofA.MI5lT" ..
  15.   "kML5NIa-Twm-92F6Q")
  16. if plaintext then
  17.   print(plaintext) -- outputs "hello"
  18. end

kong.enterprise_edition.jwe.decode(token)

Decode JWE encrypted JWT token and return a table containing its parts This function will return a table that looks like this:

  1.  {
  2.    [1] = protected header (as it appears in token)
  3.    [2] = encrypted key (as it appears in token)
  4.    [3] = initialization vector (as it appears in token)
  5.    [4] = ciphertext (as it appears in token)
  6.    [5] = authentication tag (as it appears in token)
  7.    protected = protected key (base64url decoded and json decoded)
  8.    encrypted_key = encrypted key (base64url decoded)
  9.    iv = initialization vector (base64url decoded)
  10.    ciphertext = ciphertext (base64url decoded)
  11.    tag = authentication tag (base64url decoded)
  12.    aad = protected header (as it appears in token)
  13.  }

The original input can be reconstructed with:

  1.  local token = table.concat(<decoded-table>, ".")

If there is not exactly 5 parts in JWT token, or any decoding fails, the error is returned.

Parameters

  • token (string): JWE encrypted JWT token

Returns

  1. string: A table containing JWT token parts decoded, or nil

  2. string: Error message, or nil

Usage

  1. local jwe = require "kong.enterprise_edition.jwe"
  2. local jwt, err = jwe.decode(
  3.   "eyJhbGciOiJFQ0RILUVTIiwiZW5jIjoiQTI1NkdDTSIsImFwdSI6Ik1lUFhUS2oyWFR1NUktYldUSFI2bXci" ..
  4.   "LCJhcHYiOiJmUHFoa2hfNkdjVFd1SG5YWFZBclVnIiwiZXBrIjp7Imt0eSI6IkVDIiwiY3J2IjoiUC0yNTYi" ..
  5.   "LCJ4IjoiWWd3eF9NVXRLTW9NYUpNZXFhSjZjUFV1Z29oYkVVc0I1NndrRlpYRjVMNCIsInkiOiIxaEYzYzlR" ..
  6.   "VEhELVozam1vYUp2THZwTGJqcVNaSW9KNmd4X2YtUzAtZ21RIn19..4ZrIopIhLi3LeXyE.-Ke4ofA.MI5lT" ..
  7.   "kML5NIa-Twm-92F6Q")
  8. if jwt then
  9.   print(jwt.protected.alg) -- outputs "ECDH-ES"
  10. end

kong.enterprise_edition.jwe.encrypt(alg, enc, key, plaintext, options)

Encrypt plaintext using JWE encryption and returns a JWT token Supported algorithms (alg argument):

  • "RSA-OAEP"
  • "ECDH-ES"

Supported encryption algorithms (enc argument):

  • "A256GCM"

Supported keys (key argument):

  • Supported key formats:
    • JWK (given as a string or table)
    • PEM (given as a string)
    • DER (given as a string)
  • Supported key types:
    • RSA
    • EC, supported curves:
      • P-256
      • P-384
      • P-521

Supported options (options argument):

  • { zip = "DEF" }: whether to deflate the plaintext before encrypting
  • { apu = <string|boolean> }: Agreement PartyUInfo header parameter
  • { apv = <string|boolean> }: Agreement PartyVInfo header parameter

The apu and apv can also be set to false to prevent them from being auto-generated (sixteen random bytes) and added to ephemeral public key.

Parameters

  • alg (string): Algorithm used for key management
  • enc (string): Encryption algorithm used for content encryption
  • key (string|table): Public key

  • plaintext (string): Plaintext

  • options (table, optional): Options (optional), default: nil

Returns

  1. string: JWE encrypted JWT token, or nil

  2. string: Error message, or nil

Usage

  1. local jwe = require "kong.enterprise_edition.jwe"
  2. local jwk = {
  3.   kty = "EC",
  4.   crv = "P-256",
  5.   use = "enc",
  6.   x   = "MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4",
  7.   y   = "4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM",
  8. }
  9. local token, err = jwe.encrypt("ECDH-ES", "A256GCM", jwk, "hello", {
  10.   zip = "DEF,
  11. })
  12. if token then
  13.   print(token)
  14. end