Skip to main content

%Net.JSON.JWE

class %Net.JSON.JWE extends %Library.RegisteredObject

This class provides methods to encrypt and decrypt JSON Web Encryption objects, as defined in RFC 7516.

Method Inventory

Methods

classmethod Decrypt(JWE As %String, JWKS As %String, Output plaintext As %String, Output decryptions As %DynamicArray) as %Status
This method decrypts a JWE.

Input parameters:
  • JWE - The JSON Web Encryption to be decrypted.
  • JWKS - The JSON Web Key Set that contains the key that will be used to create the content encryption key needed to validate this JWS.

Output parameters:
  • plaintext - The decrypted plaintext.
  • decryptions - A dynamic array containing information about whether or not each encrypted key in the JWE successfully decrypted the ciphertext. The decryptions array contains one DynamicObject for each encrypted key in the JWE, each containing the following fields:
    • "encryptedKey": The encrypted key this DynamicObject contains information about.
    • "decrypted": A boolean indicating whether or not the encrypted key successfully decrypted the ciphertext.
    • "error": A string containing any error message that was generating during the decryption of the ciphertext.

Return value:
  • A status indicating whether or not the JWE's ciphertext was successfully decrypted. (If there are multiple encrypted keys in the JWE, this method will return a success as long as at least one of the keys successfully decrypts the ciphertext.) If the ciphertext was not successfully decrypted this method will return an error describing why.

Notes:
  • This method will not accept an empty JWE. If provided one, it will return false and the decryptions array will be null.
  • This method supports decryption for the JWE Compact Serialization and both the flattened and general syntax of the JWE JSON Serialization.
  • For ease of development, this method returns detailed error messages. However, applications that use this method should take care when passing these errors on to end users, as doing so could allow their application to be used as an oracle for decrypting messages. Note, in particular, that applications should report formatting errors to the CEK, AAD, and ciphertext of the provided JWE as a single error, as per RFC 7516 section 11.4.
  • If the provided JWE contains multiple encrypted keys, this method will succeed and output the plaintext as long as at least one of the keys successfully decrypted the ciphertext.
  • Some applications may only want to consider a JWE with multiple encrypted keys valid if all of the encrypted keys successfully decrypt the ciphertext. Since this method only needs one encrypted key to decrypt the plaintext in order to return the plaintext, applications that require all encrypted keys to successfully decrypt the ciphertext should use the error field of each encrypted key in the validations array to meet their needs. Specifically, they should check to see if any encrypted key's error field is not null. Any encrypted key whose error field is not null failed to decrypt the ciphertext (which is why it has an error message), so the presence of any non-null error fields means that at least one encrypted key failed to decrypt the ciphertext.
classmethod Encrypt(protectedHeader As %DynamicObject, sharedUnprotectedHeader As %DynamicObject, perRecipientUnprotectedHeader As %DynamicObject, plaintext As %String, AAD As %String = "", serialization As %String = "compact", JWKS As %String, Output JWE As %String) as %Status
This method encrypts a message and makes a JWE.

Input parameters:
  • protectedHeader - The JOSE Protected Header to use.
  • sharedUnprotectedHeader - The JOSE Shared Unprotected Header to use.
  • perRecipientUnprotectedHeader - The JOSE Per-Recipient Unprotected Header to use.
  • plaintext - The message being encrypted.
  • AAD - any Additional Authenticated Data to input to the content encryption algorithm. This defaults to null.
  • serialization - The JWE Serialization format to use. Accepted serialization formats are "compact" and "json". The format type determines the structure of the JWE that is created. This defaults to "compact"
  • JWKS - The JSON Web Key Set that contains the key that will be used to create the content encryption key for this JWE.

Output parameters:
  • JWE - The JSON Web Encryption that is created. If json serialization is used, this will be a valid JSON string. If compact serialization is used it will be a non-JSON string.

Return value:
  • A status indicating whether or not a JWE was created from the inputs. If this method is unable to create a JWE from the inputs it will return an error indicating why this is.

Notes:
  • At least one of the headers must be present and non-null.
  • If none of the provided headers contains a kid but in the process of creating the JWE a JWK with a kid is used, that kid will be added to the protected header before the JWE is created.
  • This method will fail if provided an empty plaintext.
  • If the "compact" serialization format is used, the protected header MUST be present and both unprotected headers MUST be absent. If the "json" format is used, at least one of the protected header and unprotected headers MUST be present and they all CAN be present.
  • Only the JWE Compact Serialization and the flattened syntax of the JWE JSON Serialization are supported for encryption (not the general format of the JWE JSON Serialization).

Inherited Members

Inherited Methods

FeedbackOpens in a new tab