Chilkat.Jwe Class Overview

Chilkat.Jwe creates, loads, encrypts, and decrypts JSON Web Encryption objects. It supports string and binary payloads, compact and JSON serializations, single-recipient and multi-recipient JWEs, protected and unprotected headers, Additional Authenticated Data, RSA key wrapping, AES key wrapping, direct symmetric encryption, AES-GCM key wrapping, and PBES2 password based encryption.

What the Class Is Used For

Use Chilkat.Jwe when an application needs to encrypt content into a JWE or decrypt content from a received JWE. The class works with string content, StringBuilder content, and binary BinData content. It also provides methods for setting headers and recipient keys, choosing compact or JSON serialization preferences, loading existing JWEs, selecting the correct recipient, and retrieving JWE header information.

Encrypt Text or Binary Data Create JWEs from strings, StringBuilder, or BinData.
Decrypt to Text or Bytes Decrypt to a string, append decrypted text to a StringBuilder, or append decrypted bytes to BinData.
Support Multiple Key Types Use RSA public/private keys, AES wrapping keys, direct symmetric keys, or PBES2 passwords depending on the JWE alg header.
Work with Headers and Recipients Set protected, shared unprotected, and per-recipient headers; find recipient indexes using header parameters such as kid.

Typical Encryption Workflow

  1. Create a Jwe object.
  2. Create a JsonObject containing the JWE protected header, including values such as alg and enc.
  3. Call SetProtectedHeader.
  4. Set the encryption or wrapping key for the recipient: SetPublicKey, SetWrappingKey, or SetPassword, depending on the algorithm.
  5. Optionally set shared unprotected headers, recipient headers, or Additional Authenticated Data.
  6. Call Encrypt, EncryptSb, or EncryptBd.
  7. Control serialization preference with PreferCompact and PreferFlattened when applicable.

Typical Decryption Workflow

  1. Load the JWE using LoadJwe or LoadJweSb.
  2. Inspect headers with GetHeader or GetProtectedHeader when needed.
  3. For multi-recipient JWEs, call FindRecipient to locate the correct recipient index, often by the kid header parameter.
  4. Set the decryption key for that recipient index: SetPrivateKey, SetWrappingKey, or SetPassword.
  5. Decrypt with Decrypt, DecryptSb, or DecryptBd.
  6. Check LastErrorText after failures or unexpected results.

Core Concepts

Concept Meaning Important Members
Content Encryption The plaintext content is encrypted using a content encryption algorithm such as AES-CBC-HMAC or AES-GCM. Encrypt, EncryptSb, EncryptBd
Key Management Algorithm The JWE alg header determines how the content encryption key is wrapped, encrypted, or directly supplied. SetPublicKey, SetPrivateKey, SetWrappingKey, SetPassword
Recipient Index Key material is assigned by recipient index. Most JWEs have one recipient, so the index is usually 0. NumRecipients, FindRecipient, SetRecipientHeader
Protected Header The shared protected JSON header contains integrity-protected JWE header parameters. SetProtectedHeader, GetProtectedHeader
Unprotected Headers JWE JSON Serialization can include shared unprotected headers and per-recipient unprotected headers. SetUnprotectedHeader, SetRecipientHeader, GetHeader
Additional Authenticated Data Optional authenticated data that is integrity-protected but not encrypted. It is used only for non-compact serializations. SetAad, SetAadBd

Core Properties

Property Purpose Guidance
NumRecipients Returns the number of recipients for the loaded or configured JWE. Use when processing multi-recipient JWEs or validating that the expected recipient entries exist.
PreferCompact Controls whether JWE Compact Serialization is preferred when creating JWEs. Default is true. Compact serialization is used when possible. If there are multiple recipients or any unprotected headers, JWE JSON Serialization is used regardless of this setting.
PreferFlattened Controls whether flattened JSON serialization is preferred when JWE JSON Serialization is used. Default is true. If multiple recipients exist, general JSON Serialization is used regardless of this setting.
UncommonOptions Catch-all property for uncommon needs. Defaults to the empty string and should typically remain empty.
LastErrorText Diagnostic text for the last method or property access. Check after failures or unexpected behavior. Diagnostic information may be available regardless of success or failure.

Serialization Selection

Serialization When Used Related Property
Compact Serialization Preferred by default when possible. PreferCompact = true
JSON Serialization Used when multiple recipients exist, or when any unprotected headers exist. Used regardless of PreferCompact in these cases.
Flattened JSON Serialization Preferred when JSON Serialization is used and it is possible to flatten. PreferFlattened = true
General JSON Serialization Used when multiple recipients exist. Used regardless of PreferFlattened.
Important rule: Compact serialization is only possible in simpler cases. Multiple recipients or unprotected headers force JWE JSON Serialization.

Encryption Methods

Input Type Method Output
String Encrypt Returns the generated JWE as a string. The supplied charset determines the byte representation of the input string.
StringBuilder EncryptSb Encrypts StringBuilder content and appends the resulting JWE to another StringBuilder.
BinData EncryptBd Encrypts binary content and appends the resulting JWE to a StringBuilder.
Charset rule: For string encryption, the charset such as utf-8 determines how the string is converted to bytes before encryption.

Decryption Methods

Output Type Method Behavior
String Decrypt Decrypts the JWE and returns the original content as a string. The charset tells Chilkat how to interpret the decrypted bytes as characters.
StringBuilder DecryptSb Decrypts and appends the decrypted text to a supplied StringBuilder.
BinData DecryptBd Decrypts and appends the decrypted bytes to a supplied BinData.
Recipient index: Decryption methods take an index identifying which recipient key is used. Most JWEs have a single recipient, so the index is typically 0.

Loading and Inspecting JWEs

Task Method Behavior
Load JWE string LoadJwe Loads the contents of a JWE from a string.
Load JWE from StringBuilder LoadJweSb Loads the contents of a JWE from a StringBuilder.
Get full JSON header GetHeader Loads the JWE JSON header into a supplied JsonObject.
Get protected header GetProtectedHeader Loads the shared protected JSON header into a supplied JsonObject.
Find recipient by header FindRecipient Finds a recipient index where a header parameter has a specified value. Returns -1 if no matching recipient is found.

Header Methods

Header Type Method Use
Protected header SetProtectedHeader Sets the JWE Protected Header, typically including parameters such as alg and enc.
Shared unprotected header SetUnprotectedHeader Sets the JWE Shared Unprotected Header. Its presence causes JSON Serialization rather than Compact Serialization.
Per-recipient unprotected header SetRecipientHeader Sets a recipient-specific unprotected header. This is typically used for multi-recipient JWEs.
Read full header GetHeader Returns the JSON header from the loaded JWE.
Read protected header GetProtectedHeader Returns the shared protected JSON header from the loaded JWE.

Setting Keys by Algorithm Family

JWE alg Family Use This Method Examples
RSA key wrapping / unwrapping SetPublicKey for encryption; SetPrivateKey for decryption. RSA1_5, RSA-OAEP, RSA-OAEP-256, RSA-OAEP-384, RSA-OAEP-512
AES Key Wrap or AES-GCM Key Wrap SetWrappingKey A128KW, A192KW, A256KW, A128GCMKW, A192GCMKW, A256GCMKW
Direct symmetric encryption SetWrappingKey dir. In this case the key is the direct content encryption key, not a key-encryption key.
PBES2 password-based key wrapping SetPassword PBES2-HS256+A128KW, PBES2-HS384+A192KW, PBES2-HS512+A256KW
Indexing rule: Key-setting methods take a recipient index. The first recipient is index 0.

Supported Content Encryption Algorithms

Family Supported enc Values
AES-CBC with HMAC authentication A128CBC-HS256, A192CBC-HS384, A256CBC-HS512
AES-GCM A128GCM, A192GCM, A256GCM

Supported Key Management Combinations

Key Management Supported With
RSA-OAEP-256, RSA-OAEP, RSA1_5 A128CBC-HS256, A192CBC-HS384, A256CBC-HS512, A128GCM, A192GCM, A256GCM
Direct symmetric key encryption with a pre-shared key A128CBC-HS256, A192CBC-HS384, A256CBC-HS512, A128GCM, A192GCM, A256GCM
A128KW, A192KW, A256KW A128CBC-HS256, A192CBC-HS384, A256CBC-HS512, A128GCM, A192GCM, A256GCM
A128GCMKW, A192GCMKW, A256GCMKW A128CBC-HS256, A192CBC-HS384, A256CBC-HS512, A128GCM, A192GCM, A256GCM
PBES2-HS256+A128KW, PBES2-HS384+A192KW, PBES2-HS512+A256KW A128CBC-HS256, A192CBC-HS384, A256CBC-HS512, A128GCM, A192GCM, A256GCM

Additional Authenticated Data

Input Type Method Behavior
String AAD SetAad Sets optional Additional Authenticated Data from text. The charset controls the byte representation.
Binary AAD SetAadBd Sets optional Additional Authenticated Data from BinData.
Serialization rule: Additional Authenticated Data is only used for non-compact serializations.

Method Summary by Category

Category Methods Purpose
Encrypt Encrypt, EncryptSb, EncryptBd Create a JWE from string, StringBuilder, or binary BinData content.
Decrypt Decrypt, DecryptSb, DecryptBd Decrypt a loaded JWE to a string, StringBuilder, or BinData.
Load and inspect LoadJwe, LoadJweSb, GetHeader, GetProtectedHeader, FindRecipient Load JWE content, inspect headers, and find the recipient index for decryption.
Set headers SetProtectedHeader, SetUnprotectedHeader, SetRecipientHeader Configure shared protected, shared unprotected, and per-recipient headers.
Set keys SetPublicKey, SetPrivateKey, SetWrappingKey, SetPassword Provide recipient key material for RSA, AES wrapping/direct symmetric, or PBES2 password-based algorithms.
Additional authenticated data SetAad, SetAadBd Set optional AAD for non-compact JWE serialization.

Diagnostics and Troubleshooting

Problem Area Member What to Check
Encryption fails SetProtectedHeader, SetPublicKey, SetWrappingKey, SetPassword, LastErrorText Confirm the protected header contains the intended alg and enc, and that the correct key-setting method was used for the algorithm.
Decryption fails LoadJwe, SetPrivateKey, SetWrappingKey, SetPassword Confirm the JWE was loaded, the correct recipient index was used, and the correct decryption key or password was supplied.
Wrong recipient selected FindRecipient Use a header parameter such as kid to locate the matching recipient, then set the key at that returned index.
Unexpected JSON Serialization output PreferCompact, SetUnprotectedHeader, SetRecipientHeader Multiple recipients or any unprotected headers force JWE JSON Serialization.
Expected flattened JSON but got general JSON PreferFlattened Multiple recipients force general JSON Serialization.
Decrypted text appears garbled Decrypt, DecryptSb Use the same charset that correctly represents the decrypted plaintext bytes, typically utf-8.
AAD does not appear to affect compact output SetAad, SetAadBd Additional Authenticated Data is only used for non-compact serializations.

Common Pitfalls

Pitfall Better Approach
Using a public key when decrypting an RSA-based JWE. Use SetPublicKey for encryption and SetPrivateKey for decryption.
Using SetWrappingKey for PBES2 algorithms. Use SetPassword for PBES2-HS256+A128KW, PBES2-HS384+A192KW, and PBES2-HS512+A256KW.
Forgetting that dir uses the supplied key directly. With dir, the key passed to SetWrappingKey is the direct content encryption key, not a key-encryption key.
Expecting compact serialization with multiple recipients. Multiple recipients force JWE JSON Serialization.
Expecting compact serialization when unprotected headers are present. Any unprotected headers force JWE JSON Serialization.
Decrypting multi-recipient JWEs without locating the correct recipient. Use FindRecipient, often with kid, then set the key at that recipient index.
Using text methods for binary plaintext. Use EncryptBd and DecryptBd for binary content.

Best Practices

Recommendation Reason
Set the protected header before encryption. The protected header defines the key management and content encryption algorithms used to create the JWE.
Choose the key-setting method based on the alg header. RSA, AES wrapping/direct, and PBES2 algorithms each require different key setup methods.
Use BinData methods for binary content. They avoid unnecessary charset interpretation when plaintext is not text.
Use explicit charsets for text content. The charset determines how strings are converted to bytes for encryption and how decrypted bytes are interpreted as characters.
Use recipient headers such as kid for multi-recipient JWEs. They make it possible to locate the correct recipient index with FindRecipient.
Expect JSON Serialization when using multi-recipient or unprotected-header features. Compact serialization is not used in those cases, regardless of PreferCompact.
Check LastErrorText after failures. It provides the most useful diagnostic detail for loading, header setup, key setup, encryption, decryption, and serialization issues.

Summary

Chilkat.Jwe is the Chilkat class for creating and decrypting JSON Web Encryption objects. It supports text and binary payloads, compact and JSON serialization, flattened and general JSON output, single and multiple recipients, protected and unprotected headers, Additional Authenticated Data, RSA key management, AES key wrapping, direct symmetric encryption, AES-GCM key wrapping, and PBES2 password-based key wrapping.

The most important practical guidance is to set the protected header correctly, use the key-setting method that matches the JWE alg, use recipient indexes carefully for multi-recipient JWEs, and use EncryptBd / DecryptBd when the plaintext is binary rather than text.