JWE Class Reference

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

Inheritance diagram for JWE:

Collaboration diagram for JWE:

Static Public Member Functions
_.Library.Status	Decrypt (_.Library.String JWE, _.Library.String JWKS, _.Library.String plaintext, _.Library.DynamicArray decryptions)
	This method decrypts a JWE. More...
_.Library.Status	Encrypt (_.Library.DynamicObject protectedHeader, _.Library.DynamicObject sharedUnprotectedHeader, _.Library.DynamicObject perRecipientUnprotectedHeader, _.Library.String plaintext, _.Library.String AAD, _.Library.String serialization, _.Library.String JWKS, _.Library.String JWE)
	This method encrypts a message and makes a JWE. More...

Static Private Member Functions
_.Library.Status	__CreateCEK (_.Library.DynamicObject algInfo, _.Library.DynamicObject encInfo, _.Library.DynamicObject JWK, _.Library.String CEK)
	This class provides methods to encrypt and decrypt JSON Web Encryption objects, as defined in RFC 7516. More...
_.Library.Status	__CreateCiphertext (_.Library.DynamicObject encInfo, _.Library.String plaintext, _.Library.String CEK, _.Library.String IV, _.Library.String AAD, _.Library.String ciphertext, _.Library.String authTag)
	This private helper method is what actually encrypts the plaintext using the provided encryption algorithm information and inputs. More...
_.Library.Status	__DecryptCEK (_.Library.DynamicObject algInfo, _.Library.DynamicObject JWK, _.Library.String encryptedCEK, _.Library.String CEK)
	This private helper method decrypts the Content Encryption Key based on the given algorithm information and JWK.
_.Library.Status	__DecryptCiphertext (_.Library.DynamicObject encInfo, _.Library.String ciphertext, _.Library.String authTag, _.Library.String CEK, _.Library.String IV, _.Library.String AAD, _.Library.String plaintext)
	This private helper method is what actually decrypts the ciphertext using the provided encryption algorithm information and inputs. More...
_.Library.Status	__DecryptCompact (_.Library.String JWE, _.Library.String JWKS, _.Library.String plaintext, _.Library.DynamicArray decryptions)
	This private method decrypts a compact serialized JWE and returns an object containing information on the decryption status of the. More...
_.Library.Status	__DecryptJSON (_.Library.String JWE, _.Library.String JWKS, _.Library.String plaintext, _.Library.DynamicArray decryptions)
	This private method decrypts a JSON serialized JWE and returns an object containing information on the decryption status of each. More...
_.Library.Status	__EncryptCEK (_.Library.DynamicObject algInfo, _.Library.DynamicObject JWK, _.Library.String CEK, _.Library.String encryptedCEK)
	This private helper method encrypts the Content Encryption Key based on the given algorithm information and JWK.
_.Library.Status	__EncryptCompact (_.Library.DynamicObject header, _.Library.String plaintext, _.Library.String JWKS, _.Library.String JWE)
	This private method encrypts and creates a compact serialized JWE. More...
_.Library.Status	__EncryptJSON (_.Library.DynamicObject protectedHeader, _.Library.DynamicObject sharedUnprotectedHeader, _.Library.DynamicObject perRecipientUnprotectedHeader, _.Library.String plaintext, _.Library.String JWEAAD, _.Library.String JWKS, _.Library.String JWE)
	This private method encrypts and creates a JSON serialized JWE with flattened syntax. More...
_.Library.Integer	__ExtractAllRecipients (_.Library.DynamicObject JWEObj, recipientsArray)
	This private helper method retrieves all of the encrypted keys and per-recipient unprotected headers. More...
_.Library.Integer	__ExtractFlattenedFormat (_.Library.DynamicObject JWEObj, recipientsArray)
	This private helper method retrieves the encrypted key and per-recipient unprotected header from a. More...
_.Library.Integer	__ExtractGeneralFormat (_.Library.DynamicObject JWEObj, recipientsArray)
	This private helper method retrieves all of the encrypted keys and per-recipient unprotected headers from a. More...

Additional Inherited Members
Public Member Functions inherited from RegisteredObject
_.Library.Status	OnAddToSaveSet (_.Library.Integer depth, _.Library.Integer insert, _.Library.Integer callcount)
	This callback method is invoked when the current object is added to the SaveSet,. More...
_.Library.Status	OnClose ()
	This callback method is invoked by the <METHOD>Close</METHOD> method to. More...
_.Library.Status	OnConstructClone (_.Library.RegisteredObject object, _.Library.Boolean deep, _.Library.String cloned)
	This callback method is invoked by the <METHOD>ConstructClone</METHOD> method to. More...
_.Library.Status	OnNew ()
	This callback method is invoked by the <METHOD>New</METHOD> method to. More...
_.Library.Status	OnValidateObject ()
	This callback method is invoked by the <METHOD>ValidateObject</METHOD> method to. More...
Static Public Attributes inherited from RegisteredObject
	CAPTION = None
	Optional name used by the Form Wizard for a class when generating forms. More...
	JAVATYPE = None
	The Java type to be used when exported.
	PROPERTYVALIDATION = None
	This parameter controls the default validation behavior for the object. More...

Detailed Description

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

Member Function Documentation

__CreateCEK()

_.Library.Status __CreateCEK ( _.Library.DynamicObject  algInfo, _.Library.DynamicObject  encInfo, _.Library.DynamicObject  JWK, _.Library.String  CEK  )

staticprivate

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

This private helper method creates a Content Encryption Key based on the given algorithm information and JWK.

__CreateCiphertext()

_.Library.Status __CreateCiphertext ( _.Library.DynamicObject  encInfo, _.Library.String  plaintext, _.Library.String  CEK, _.Library.String  IV, _.Library.String  AAD, _.Library.String  ciphertext, _.Library.String  authTag  )

staticprivate

This private helper method is what actually encrypts the plaintext using the provided encryption algorithm information and inputs.

It outputs both the ciphertext and an authentication tag.

Decrypt()

_.Library.Status Decrypt ( _.Library.String  JWE, _.Library.String  JWKS, _.Library.String  plaintext, _.Library.DynamicArray  decryptions  )

static

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.

__DecryptCiphertext()

_.Library.Status __DecryptCiphertext ( _.Library.DynamicObject  encInfo, _.Library.String  ciphertext, _.Library.String  authTag, _.Library.String  CEK, _.Library.String  IV, _.Library.String  AAD, _.Library.String  plaintext  )

staticprivate

This private helper method is what actually decrypts the ciphertext using the provided encryption algorithm information and inputs.

Before decrypting the ciphertext, it first verifies the authentication tag.

__DecryptCompact()

_.Library.Status __DecryptCompact ( _.Library.String  JWE, _.Library.String  JWKS, _.Library.String  plaintext, _.Library.DynamicArray  decryptions  )

staticprivate

This private method decrypts a compact serialized JWE and returns an object containing information on the decryption status of the.

encrypted key in the JWE. It is a helper method for Decrypt() above and should never be called on its own. See Decrypt() for information on the inputs and outputs.

__DecryptJSON()

_.Library.Status __DecryptJSON ( _.Library.String  JWE, _.Library.String  JWKS, _.Library.String  plaintext, _.Library.DynamicArray  decryptions  )

staticprivate

This private method decrypts a JSON serialized JWE and returns an object containing information on the decryption status of each.

encrypted key in the JWE. It is a helper method for Decrypt() above and should never be called on its own. See Decrypt() for information on the inputs and outputs.

Encrypt()

_.Library.Status Encrypt ( _.Library.DynamicObject  protectedHeader, _.Library.DynamicObject  sharedUnprotectedHeader, _.Library.DynamicObject  perRecipientUnprotectedHeader, _.Library.String  plaintext, _.Library.String  AAD, _.Library.String  serialization, _.Library.String  JWKS, _.Library.String  JWE  )

static

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).

__EncryptCompact()

_.Library.Status __EncryptCompact ( _.Library.DynamicObject  header, _.Library.String  plaintext, _.Library.String  JWKS, _.Library.String  JWE  )

staticprivate

This private method encrypts and creates a compact serialized JWE.

It is a helper method for Encrypt() above and

should never be called on its own. See Encrypt() for information on the inputs and outputs.

__EncryptJSON()

_.Library.Status __EncryptJSON ( _.Library.DynamicObject  protectedHeader, _.Library.DynamicObject  sharedUnprotectedHeader, _.Library.DynamicObject  perRecipientUnprotectedHeader, _.Library.String  plaintext, _.Library.String  JWEAAD, _.Library.String  JWKS, _.Library.String  JWE  )

staticprivate

This private method encrypts and creates a JSON serialized JWE with flattened syntax.

It is a helper method for

Encrypt() above and should never be called on its own. See Encrypt() for information on the inputs and outputs.

__ExtractAllRecipients()

_.Library.Integer __ExtractAllRecipients ( _.Library.DynamicObject  JWEObj,   recipientsArray  )

staticprivate

This private helper method retrieves all of the encrypted keys and per-recipient unprotected headers.

from a JSON serialized JWE. It returns the number of recipients found and outputs an array of all of the encrypted keys and per-recipient unprotected headers found.

__ExtractFlattenedFormat()

_.Library.Integer __ExtractFlattenedFormat ( _.Library.DynamicObject  JWEObj,   recipientsArray  )

staticprivate

This private helper method retrieves the encrypted key and per-recipient unprotected header from a.

JSON serialized JWE that uses flattened syntax. In order to ensure compatibility with the general syntax of JSON serialized JWEs, this method populates a two-dimensional array to store the encrypted key alongside the per-recipient unprotected header. It then returns the number of recipients found (which will always either be 0 or 1).

__ExtractGeneralFormat()

_.Library.Integer __ExtractGeneralFormat ( _.Library.DynamicObject  JWEObj,   recipientsArray  )

staticprivate

This private helper method retrieves all of the encrypted keys and per-recipient unprotected headers from a.

JSON serialized JWE that uses general syntax. It populates a two-dimensional array to store each encrypted key alongside the corresponding per-recipient unprotected header and then returns the number of recipients found.