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