--- product: Chilkat product_version: 11.7.0 language: pascal language_label: Lazarus Pascal class: Jwe license: bundle deprecated: false reference_html: https://www.chilkatsoft.com/refdoc/pascal_JweRef.html --- # Chilkat Jwe — Lazarus Pascal — v11.7.0 > Chilkat 11.7.0 · language=pascal · class=Jwe > Other versions: replace `11.7.0` in this URL. Other languages: `https://www.chilkatsoft.com/ai-docs/v/11.7.0//classes/Jwe.md`. > Language-wide rules (install, unlock, error model, strings/bytes): `https://www.chilkatsoft.com/ai-docs/v/11.7.0/pascal/guide.md`. ## Purpose **Create and decrypt JSON Web Encryption payloads in compact or JSON form.** `Chilkat.Jwe` is the Chilkat class for creating and decrypting JSON Web Encryption objects. It supports text and binary payloads, compact serialization, flattened JSON serialization, general JSON serialization, protected and unprotected headers, Additional Authenticated Data, single or multiple recipients, and several key-management approaches including RSA, AES key wrapping, direct symmetric encryption, AES-GCM key wrapping, and PBES2 password-based key wrapping. **Encrypt text or binary data** Protect string or binary payloads using JWE content-encryption algorithms and the key-management method required by the recipient. **Decrypt JWE messages** Load a compact, flattened, or general JWE object and decrypt the payload using the appropriate private key, symmetric key, or password. **Compact and JSON formats** Produce or consume compact serialization for single-recipient workflows, or JSON serialization when richer header or multi-recipient structure is needed. **Single or multiple recipients** Create JWE data for one recipient or use general JSON serialization when the same encrypted payload must be decryptable by multiple recipients. **Headers and AAD** Configure protected headers, unprotected headers, recipient-specific headers, and Additional Authenticated Data for protocol-specific JWE requirements. **Flexible key management** Use RSA key management, AES key wrapping, direct symmetric keys, AES-GCM key wrapping, or PBES2 password-based key wrapping. **Common pattern:** Choose the JWE serialization format, set the protected header values such as `alg` and `enc`, add the recipient key information, provide the plaintext payload, and encrypt. To decrypt, load the JWE, provide the matching key or password, and retrieve the plaintext as text, bytes, or a Chilkat binary buffer. For an extended overview, see [Jwe Class Overview](https://www.chilkatsoft.com/jwe_class_overview.asp). ## Object creation, unlocking and error handling **Create / Free** ```pascal uses Chilkat.Jwe; var obj: TJwe; begin obj := TJwe.Create; try if not obj.IsValid then raise Exception.Create('Failed to create a TJwe instance.'); // ... use obj ... finally obj.Free; end; end; ``` `constructor Create;` Allocates the underlying CkJwe object and returns a new TJwe instance. Simply adding **Chilkat.Jwe** to the unit's `uses` clause is enough to locate and bind to the Chilkat shared library (DLL / .so / .dylib) at runtime — no separate load step is required. Check `obj.IsValid` after calling `Create`; it is `False` if the underlying library could not be found/loaded or the object could not be allocated (for example, when unlicensed). `destructor Destroy; override;` Every TJwe created by calling `Create` should eventually be released by calling `.Free` (inherited from `TObject`). The destructor automatically disposes the underlying CkJwe handle. A native (unmanaged) memory leak occurs if the object is never freed. Call `Global.UnlockBundle` once at the start of the program, before using this or any other Chilkat class. Any string unlocks a fully functional 30-day trial; a purchased unlock code is used in production. See `guide.md` for the exact code in Lazarus Pascal. ## Members common to every Chilkat class Documented once per language in `common-members.md`; listed here so this page is self-contained. | Property | Signature | Access | Meaning | |---|---|---|---| | `DebugLogFilePath` | `property DebugLogFilePath: string read GetDebugLogFilePath write SetDebugLogFilePath;` | read/write | If set to a file path, this property logs the LastErrorText of each Chilkat method or property call to the specified file. | | `LastErrorHtml` | `property LastErrorHtml: string read GetLastErrorHtml;` | read-only | Provides HTML-formatted information about the last called method or property. | | `LastErrorText` | `property LastErrorText: string read GetLastErrorText;` | read-only | Provides plain text information about the last called method or property. | | `LastErrorXml` | `property LastErrorXml: string read GetLastErrorXml;` | read-only | Provides XML-formatted information about the last called method or property. | | `LastMethodSuccess` | `property LastMethodSuccess: Boolean read GetLastMethodSuccess write SetLastMethodSuccess;` | read/write | Indicates the success or failure of the most recent method call: `True` means success, `False` means failure. | | `VerboseLogging` | `property VerboseLogging: Boolean read GetVerboseLogging write SetVerboseLogging;` | read/write | If set to `True`, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. | | `Version` | `property Version: string read GetVersion;` | read-only | Version of the component/library, such as "10.1.0" | ## Member index | Member | Kind | Signature | |---|---|---| | `NumRecipients` | property, read-only | `property NumRecipients: Integer read GetNumRecipients;` | | `PreferCompact` | property, read/write | `property PreferCompact: Boolean read GetPreferCompact write SetPreferCompact;` | | `PreferFlattened` | property, read/write | `property PreferFlattened: Boolean read GetPreferFlattened write SetPreferFlattened;` | | `UncommonOptions` | property, read/write | `property UncommonOptions: string read GetUncommonOptions write SetUncommonOptions;` | | `Decrypt` | method | `function Decrypt(index: Integer;     const charset: string): string;` | | `DecryptBd` | method | `// bd is a TBinData object. function DecryptBd(index: Integer;     bd: TChilkatBase): Boolean;` | | `DecryptSb` | method | `// contentSb is a TStringBuilder object. function DecryptSb(index: Integer;     const charset: string;     contentSb: TChilkatBase): Boolean;` | | `Encrypt` | method | `function Encrypt(const content: string;     const charset: string): string;` | | `EncryptBd` | method | `// contentBd is a TBinData object. // jweSb is a TStringBuilder object. function EncryptBd(contentBd: TChilkatBase;     jweSb: TChilkatBase): Boolean;` | | `EncryptSb` | method | `// contentSb is a TStringBuilder object. // jweSb is a TStringBuilder object. function EncryptSb(contentSb: TChilkatBase;     const charset: string;     jweSb: TChilkatBase): Boolean;` | | `FindRecipient` | method | `function FindRecipient(const paramName: string;     const paramValue: string;     caseSensitive: Boolean): Integer;` | | `GetHeader` | method | `// json is a TJsonObject object. function GetHeader(json: TChilkatBase): Boolean;` | | `GetProtectedHeader` | method | `// json is a TJsonObject object. function GetProtectedHeader(json: TChilkatBase): Boolean;` | | `LoadJwe` | method | `function LoadJwe(const jwe: string): Boolean;` | | `LoadJweSb` | method | `// sb is a TStringBuilder object. function LoadJweSb(sb: TChilkatBase): Boolean;` | | `SetAad` | method | `function SetAad(const aad: string;     const charset: string): Boolean;` | | `SetAadBd` | method | `// aad is a TBinData object. function SetAadBd(aad: TChilkatBase): Boolean;` | | `SetPassword` | method | `function SetPassword(index: Integer;     const password: string): Boolean;` | | `SetPrivateKey` | method | `// privKey is a TPrivateKey object. function SetPrivateKey(index: Integer;     privKey: TChilkatBase): Boolean;` | | `SetProtectedHeader` | method | `// json is a TJsonObject object. function SetProtectedHeader(json: TChilkatBase): Boolean;` | | `SetPublicKey` | method | `// pubKey is a TPublicKey object. function SetPublicKey(index: Integer;     pubKey: TChilkatBase): Boolean;` | | `SetRecipientHeader` | method | `// json is a TJsonObject object. function SetRecipientHeader(index: Integer;     json: TChilkatBase): Boolean;` | | `SetUnprotectedHeader` | method | `// json is a TJsonObject object. function SetUnprotectedHeader(json: TChilkatBase): Boolean;` | | `SetWrappingKey` | method | `function SetWrappingKey(index: Integer;     const encodedKey: string;     const encoding: string): Boolean;` | ## Properties ### Jwe.NumRecipients `Chilkat 11.7.0 · pascal · Jwe · NumRecipients · property · read-only · since 9.5.0.66` ```pascal property NumRecipients: Integer read GetNumRecipients; ``` Returns the number of recipients in the loaded JWE or in the JWE currently being configured. Recipient indexes are zero-based and must be in the range `0` through `1000`. | Object state | How the count is determined | | :--- | :--- | | After `LoadJwe` or `LoadJweSb` | Returns `1` for compact or flattened serialization, or the number of elements in the general JSON `recipients` array. | | Before encryption | Returns one more than the highest index having a public key, wrapping key, or password, with a minimum value of `1`. Private keys and recipient headers do not increase the create-mode count. | Indexes may be configured in any order, but encryption processes every recipient from index `0` through `NumRecipients - 1`. For example, setting only a public key at index `2` implies three recipients; encryption then fails for indexes `0` and `1` because they are not fully configured. In practice, configure a contiguous range beginning at `0`. **No recipient removal method:** Re-setting an indexed key, password, or header replaces only that value. There is no method to remove an individual configured recipient, so use a fresh `Jwe` object for an unrelated recipient set. ### Jwe.PreferCompact `Chilkat 11.7.0 · pascal · Jwe · PreferCompact · property · read/write · since 9.5.0.66` ```pascal property PreferCompact: Boolean read GetPreferCompact write SetPreferCompact; ``` Controls whether encryption prefers JWE Compact Serialization. The default is `True`. | Configuration | Serialization selected | | :--- | :--- | | More than one recipient | General JWE JSON Serialization, regardless of this property. | | One recipient, `PreferCompact` = `True`, and no shared unprotected header | Compact Serialization. | | One recipient and `PreferCompact` = `False` | A JSON serialization; `PreferFlattened` chooses flattened or general form. | | One recipient with a shared unprotected header, even an empty one | A JSON serialization because compact form cannot carry the `unprotected` member. | A per-recipient header by itself does not prevent compact output. If compact form is selected, that header is not included. Set this property to `False` when a single-recipient per-recipient header must be emitted. **AAD and compact form:** Setting AAD does not itself force JSON output. If compact serialization is selected, the configured AAD is ignored and Chilkat logs a warning. Set `PreferCompact` to `False` when AAD must be carried and authenticated. ### Jwe.PreferFlattened `Chilkat 11.7.0 · pascal · Jwe · PreferFlattened · property · read/write · since 9.5.0.66` ```pascal property PreferFlattened: Boolean read GetPreferFlattened write SetPreferFlattened; ``` Controls which JWE JSON Serialization is produced for a single recipient. The default is `True`. It has no effect when compact form is selected or when multiple recipients require general JSON. | Condition | Result | | :--- | :--- | | One recipient, JSON required, and this property is `True` | Flattened JWE JSON Serialization. | | One recipient, JSON required, and this property is `False` | General JWE JSON Serialization containing a one-element `recipients` array. | | More than one recipient | General JWE JSON Serialization. | To force general JSON for a single recipient, set both `PreferCompact` and `PreferFlattened` to `False`. **Empty header objects:** A shared protected header is emitted only when it contains members. A shared unprotected header is emitted whenever it has been set, even when empty. A configured per-recipient header is also emitted in JSON form even when empty. ### Jwe.UncommonOptions `Chilkat 11.7.0 · pascal · Jwe · UncommonOptions · property · read/write · since 10.1.0` ```pascal property UncommonOptions: string read GetUncommonOptions write SetUncommonOptions; ``` Provides a comma-separated list of specialized compatibility options that are not exposed as ordinary properties. The default is the empty string, which is appropriate for normal JWE creation and decryption. | Option | Effect | | :--- | :--- | | `jwe-no-inflate-limit` | Starting in v11.7.0. Removes the limit on the decompressed size of a JWE that uses `zip`:`DEF`. By default, decryption fails if the plaintext would decompress to more than 64 MB, which protects against decompression bombs. | **Use only for trusted senders:** A small compressed JWE can expand to an enormous plaintext. Set `jwe-no-inflate-limit` only when every JWE you decrypt comes from a trusted source and legitimately decompresses to more than 64 MB. ## Methods ### Jwe.Decrypt `Chilkat 11.7.0 · pascal · Jwe · Decrypt · method · since 9.5.0.66` ```pascal function Decrypt(index: Integer;     const charset: string): string; ``` Decrypts recipient `index` from the currently loaded JWE and returns the plaintext decoded using charset `charset`. The valid recipient index range is `0` through `NumRecipients - 1`. 1. Call `LoadJwe` or `LoadJweSb`. 2. Inspect headers and select an acceptable recipient and algorithm under application policy. 3. Set the required private key, wrapping key, or password at the same index. 4. Call this method. Loaded AAD is used automatically. Authentication is completed before plaintext is returned. For `zip`:`DEF`, decompression occurs only after successful authentication, and no partial decompressed output is returned. Starting in v11.7.0, decryption fails if the plaintext would decompress to more than 64 MB, unless `UncommonOptions` contains `jwe-no-inflate-limit`. **Charset errors:** Charset conversion errors cause `Decrypt` to fail. Returns True for success, False for failure. ### Jwe.DecryptBd `Chilkat 11.7.0 · pascal · Jwe · DecryptBd · method · since 9.5.0.66` ```pascal // bd is a TBinData object. function DecryptBd(index: Integer;     bd: TChilkatBase): Boolean; ``` Decrypts recipient `index` and appends the authenticated plaintext bytes to `bd`. No character-set conversion is performed. Loaded AAD is used automatically, and `zip`:`DEF` is decompressed only after authentication succeeds. **Atomic destination behavior:** On success, plaintext bytes are appended and existing bytes are preserved. On failure, `bd` is left unchanged; no partial or unauthenticated plaintext is delivered. Returns True for success, False for failure. ### Jwe.DecryptSb `Chilkat 11.7.0 · pascal · Jwe · DecryptSb · method · since 9.5.0.66` ```pascal // contentSb is a TStringBuilder object. function DecryptSb(index: Integer;     const charset: string;     contentSb: TChilkatBase): Boolean; ``` Decrypts recipient `index`, authenticates the JWE, decodes the plaintext bytes using charset `charset`, and appends the resulting text to `contentSb`. Loaded AAD is used automatically, and `zip`:`DEF` is decompressed only after authentication succeeds. **Atomic destination behavior:** On success, plaintext is appended and existing text is preserved. On failure, `contentSb` is left unchanged; no unauthenticated or partially decoded plaintext is delivered. **Charset handling:** Invalid byte sequences for `charset` cause failure. Use `DecryptBd` for raw binary plaintext. Returns True for success, False for failure. ### Jwe.Encrypt `Chilkat 11.7.0 · pascal · Jwe · Encrypt · method · since 9.5.0.66` ```pascal function Encrypt(const content: string;     const charset: string): string; ``` Encrypts `content` and returns the resulting compact, flattened JSON, or general JSON JWE. `content` is converted to bytes using charset `charset`. If the text cannot be represented in that charset, the method fails. Before calling this method, configure the protected header and each recipient's required public key, wrapping key, or password. The selected `alg` and `enc` values determine the required key type and length; final compatibility checks occur during this call. Chilkat generates the content-encryption IV automatically: 12 bytes for AES-GCM content encryption and 16 bytes for AES-CBC-HMAC content encryption. Serialization is selected by `NumRecipients`, `PreferCompact`, `PreferFlattened`, and whether a shared unprotected header is present. A single per-recipient header is omitted if compact serialization is selected. Configured AAD is also ignored in compact form and causes a warning. **Generated state persists:** Encryption replaces any previously loaded JWE and can add `epk`, AES-GCM wrapping `iv`/`tag`, and other generated parameters to the stored headers. Use a fresh object or reset headers for independent operations, especially to prevent AES-GCM wrapping-IV reuse. **Compression and extensions:** `zip`:`DEF` compresses before encryption. Unknown `zip` values are ignored. The class does not enforce `crit`; applications must apply any critical-extension policy themselves. Returns True for success, False for failure. ### Jwe.EncryptBd `Chilkat 11.7.0 · pascal · Jwe · EncryptBd · method · since 9.5.0.66` ```pascal // contentBd is a TBinData object. // jweSb is a TStringBuilder object. function EncryptBd(contentBd: TChilkatBase;     jweSb: TChilkatBase): Boolean; ``` Encrypts the exact bytes in `contentBd` and appends the resulting JWE text to `jweSb`. No character-set conversion is performed, making this the appropriate method for arbitrary binary content. The same recipient configuration, serialization-selection, AAD, compression, and generated-header rules described for `Encrypt` apply. **Failure behavior:** Check the `True`/`False` return before using `jweSb`. A failure does not append a partial JWE. Returns True for success, False for failure. ### Jwe.EncryptSb `Chilkat 11.7.0 · pascal · Jwe · EncryptSb · method · since 9.5.0.66` ```pascal // contentSb is a TStringBuilder object. // jweSb is a TStringBuilder object. function EncryptSb(contentSb: TChilkatBase;     const charset: string;     jweSb: TChilkatBase): Boolean; ``` Encodes the text in `contentSb` using charset `charset`, encrypts it, and appends the resulting JWE text to `jweSb`. Existing text in `jweSb` is preserved. If the input contains characters that cannot be represented in `charset`, the call fails. The same recipient configuration, serialization-selection, AAD, compression, and generated-header rules described for `Encrypt` apply. **Failure behavior:** Check the `True`/`False` return before using `jweSb`. A failure does not append a partial JWE. Returns True for success, False for failure. ### Jwe.FindRecipient `Chilkat 11.7.0 · pascal · Jwe · FindRecipient · method · since 9.5.0.66` ```pascal function FindRecipient(const paramName: string;     const paramValue: string;     caseSensitive: Boolean): Integer; ``` Searches only the per-recipient unprotected headers for a member named `paramName` whose string value equals `paramValue`. `caseSensitive` controls whether both the member-name and value comparisons are case-sensitive. Returns the zero-based index of the first matching recipient, or `-1` when no match is found. A value of `-1` is also returned when the object cannot be searched; treat it simply as “no matching recipient found.” The protected and shared unprotected headers are not searched. A common use is to load a JWE, find a recipient by `kid`, set the corresponding key or password at the returned index, and decrypt using that same index. **Routing only:** Per-recipient headers are unprotected and attacker-controlled. Validate acceptable key identifiers and algorithms under application policy, and trust the result only after authenticated decryption succeeds. ### Jwe.GetHeader `Chilkat 11.7.0 · pascal · Jwe · GetHeader · method · since 9.5.0.89` ```pascal // json is a TJsonObject object. function GetHeader(json: TChilkatBase): Boolean; ``` Copies the entire currently loaded JWE structure into `json` as a JSON object. This is the full JWE representation, not a decoded or merged JOSE header. The object can contain `protected` in its original base64url-encoded form, `unprotected`, `header`, `recipients`, `encrypted_key`, `iv`, `ciphertext`, `tag`, `aad`, and any retained unknown top-level members. A JWE originally loaded from compact form is also exposed in this JSON-object representation. On success, `json` is overwritten. The method requires a loaded JWE; on failure, `json` is left unchanged. Use `GetProtectedHeader` to obtain the decoded protected-header JSON. **No effective-header merge:** This method does not decode `protected` and does not combine protected, shared unprotected, and per-recipient members. Applications must inspect the relevant objects explicitly. Returns True for success, False for failure. ### Jwe.GetProtectedHeader `Chilkat 11.7.0 · pascal · Jwe · GetProtectedHeader · method · since 9.5.0.89` ```pascal // json is a TJsonObject object. function GetProtectedHeader(json: TChilkatBase): Boolean; ``` Copies the decoded shared JWE Protected Header into `json`. Only the protected header is returned; it is not merged with the shared unprotected header or any per-recipient header. The method succeeds after a protected header was configured with `SetProtectedHeader`, or after a JWE containing a protected header was loaded. On success `json` is overwritten; on failure it is left unchanged. Use this method to inspect `alg`, `enc`, `zip`, `crit`, and other protected parameters before choosing a key or applying application policy. **Authentication timing:** The header can be decoded before a key is supplied, but its integrity is established only when authenticated decryption succeeds. The `Jwe` class does not enforce `crit`; applications requiring critical-extension processing must do so themselves. Returns True for success, False for failure. ### Jwe.LoadJwe `Chilkat 11.7.0 · pascal · Jwe · LoadJwe · method · since 9.5.0.66` ```pascal function LoadJwe(const jwe: string): Boolean; ``` Loads `jwe` as JWE Compact Serialization, Flattened JWE JSON Serialization, or General JWE JSON Serialization. Loading parses structure and headers but does not decrypt, authenticate, or apply application algorithm policy. | Input rule | Behavior | | :--- | :--- | | Leading or trailing whitespace | Trimmed before format detection. | | First non-whitespace character is `{{` | Parsed as flattened or general JSON. | | Other input | Treated as compact serialization and required to contain exactly five dot-separated segments. | | Empty compact `encrypted_key` segment | Accepted, as required by `dir` and direct `ECDH-ES`. | | Protected header | Base64url-decoded and parsed as UTF-8 JSON during loading. Invalid protected-header encoding or JSON causes failure. | | General JSON with top-level flattened recipient members | The `recipients` array takes precedence; top-level `header` and `encrypted_key` are ignored. | | Unknown top-level members | Retained and visible through `GetHeader`, but otherwise ignored. | Most semantic checks are deferred until decryption, including presence and support of `alg`/`enc`, key compatibility, PBES2 parameter validity, and decoding or length checks for `iv`, `tag`, `ciphertext`, and `encrypted_key`. **State replacement:** Every load attempt discards the previous loaded JWE and clears configured protected, shared unprotected, recipient-header, and AAD state. A failed load does not restore the prior message. Public keys, private keys, wrapping keys, and passwords are not cleared. The normal decrypt sequence is therefore: load first, then set the selected recipient key, then decrypt. **Parsing details:** Padding, alternate Base64 alphabets, line breaks, and duplicate JSON member names follow Chilkat's underlying JSON and base64url decoders when each value is used. Malformed values generally fail during decryption if they were not needed during initial loading. **No authentication yet:** Headers and `kid` values are attacker-controlled until authenticated decryption succeeds. Apply an algorithm and key-selection allowlist before decrypting untrusted input. Returns True for success, False for failure. ### Jwe.LoadJweSb `Chilkat 11.7.0 · pascal · Jwe · LoadJweSb · method · since 9.5.0.66` ```pascal // sb is a TStringBuilder object. function LoadJweSb(sb: TChilkatBase): Boolean; ``` Loads the complete JWE text in `sb`. It accepts compact, flattened JSON, or general JSON serialization and otherwise follows all parsing, state-replacement, deferred-validation, and security behavior documented for `LoadJwe`. The source `StringBuilder` is read during the call and does not need to remain alive afterward. Returns True for success, False for failure. ### Jwe.SetAad `Chilkat 11.7.0 · pascal · Jwe · SetAad · method · since 9.5.0.66` ```pascal function SetAad(const aad: string;     const charset: string): Boolean; ``` Sets external Additional Authenticated Data (AAD) for a JWE being encrypted. `aad` is encoded using charset `charset`, and the resulting bytes replace any previously configured AAD. Chilkat copies the bytes. Passing an empty string clears AAD. If encoding or another validation step fails, the previous AAD remains unchanged. In JSON serialization, AAD is base64url-encoded into the top-level `aad` member and included in the authentication calculation. It is visible but cannot be modified without causing authentication failure. **Compact serialization:** AAD does not force JSON serialization. If compact form is selected, Chilkat ignores the configured AAD and logs a warning. Set `PreferCompact` to `False` when AAD must be emitted. **Decryption:** After loading a JSON JWE, Chilkat automatically uses its serialized `aad` value. Do not call this method merely to repeat AAD before decryption. **Exact bytes:** Character encoding is part of the AAD definition. Use `SetAadBd` when the protocol defines exact binary AAD. Returns True for success, False for failure. ### Jwe.SetAadBd `Chilkat 11.7.0 · pascal · Jwe · SetAadBd · method · since 9.5.0.66` ```pascal // aad is a TBinData object. function SetAadBd(aad: TChilkatBase): Boolean; ``` Sets external Additional Authenticated Data (AAD) to the exact bytes in `aad`. Chilkat copies the bytes, replacing previous AAD. Passing empty `BinData` clears AAD and causes no `aad` member to be emitted. If the setter fails, the previous AAD remains unchanged. In JSON serialization, the bytes are base64url-encoded into the top-level `aad` member and authenticated without being encrypted. **Compact serialization:** AAD does not force JSON output. If compact form is selected, the configured AAD is ignored and a warning is logged. Set `PreferCompact` to `False` when AAD is required. **Decryption:** A loaded JSON JWE supplies its own AAD automatically; do not set it again before decrypting. Returns True for success, False for failure. ### Jwe.SetPassword `Chilkat 11.7.0 · pascal · Jwe · SetPassword · method · since 9.5.0.66` ```pascal function SetPassword(index: Integer;     const password: string): Boolean; ``` Sets the PBES2 password for recipient `index`. The valid index range is `0` through `1000`. Chilkat converts `password` to UTF-8, copies it, and replaces only the password at that index. Use this method with `PBES2-HS256+A128KW`, `PBES2-HS384+A192KW`, or `PBES2-HS512+A256KW`. The applicable header must also contain: | Header member | Requirement | | :--- | :--- | | `p2s` | Base64url-encoded salt. Chilkat does not generate it, impose a minimum length, or detect reuse. Generate a fresh random salt of at least 8 bytes for each encryption. | | `p2c` | A JSON integer or quoted numeric string from `1` through `999000`. Chilkat does not generate it. | The parameters may be in the protected header or the recipient header. A recipient-header value takes precedence over a shared value. Missing or invalid values are detected during encryption or decryption, not by this setter or by `LoadJwe`. If this setter fails, the previously stored password remains unchanged. **Cost policy:** The built-in maximum is 999,000 iterations. Applications accepting untrusted JWEs should still apply their own acceptable `p2c` range before decryption. **Recipient indexing:** Passwords contribute to create-mode `NumRecipients`. Configure a contiguous recipient range beginning at index `0`. Returns True for success, False for failure. ### Jwe.SetPrivateKey `Chilkat 11.7.0 · pascal · Jwe · SetPrivateKey · method · since 9.5.0.66` ```pascal // privKey is a TPrivateKey object. function SetPrivateKey(index: Integer;     privKey: TChilkatBase): Boolean; ``` Sets the private key used to decrypt recipient `index`. The valid index range is `0` through `1000`. Chilkat copies `privKey` and releases any previously stored private key at that index; the source object may be discarded after this call. | Key type | Applicable `alg` values | | :--- | :--- | | RSA private key | `RSA1_5`, `RSA-OAEP`, `RSA-OAEP-256`, `RSA-OAEP-384`, and `RSA-OAEP-512`. | | EC private key | `ECDH-ES` and the `ECDH-ES+A128KW`, `+A192KW`, and `+A256KW` variants. | Call `LoadJwe` first, then set the private key for the selected recipient index, and finally call a decryption method with the same index. Loading does not clear previously stored keys, so explicitly overwrite keys when reusing the object for unrelated messages. **Validation timing:** A `True` return means the key was copied and stored. RSA-versus-EC type, curve, key size, and compatibility with the loaded `alg` are validated during decryption, not by this setter. If the setter fails, the previously stored key remains unchanged. **RSA-OAEP-256 compatibility:** During decryption, Chilkat includes a fallback for tokens produced by older Chilkat versions that labeled the algorithm `RSA-OAEP-256` while using SHA-1 for the mask-generation function. **Recipient count:** Private keys are decryption state and do not increase create-mode `NumRecipients`. Returns True for success, False for failure. ### Jwe.SetProtectedHeader `Chilkat 11.7.0 · pascal · Jwe · SetProtectedHeader · method · since 9.5.0.66` ```pascal // json is a TJsonObject object. function SetProtectedHeader(json: TChilkatBase): Boolean; ``` Sets the shared JWE Protected Header from `json`. Chilkat copies the source `JsonObject`, replacing the previously configured protected header only if the call succeeds. The caller does not need to keep `json` alive or call this method again after modifying the original object. The protected header is serialized as UTF-8 and base64url-encoded. It is visible, but its encoded form is included in the authenticated data, so any modification causes authenticated decryption to fail. | JWE pattern | Recommended placement | | :--- | :--- | | Single-recipient compact JWE | Place `alg` and `enc` here. | | Single-recipient JSON JWE | Normally place `alg` and `enc` here. | | Multiple recipients using different key-management algorithms | Place the shared `enc` here and each recipient-specific `alg` in its per-recipient header. | | Multiple recipients using one common `alg` | The common `alg` may be placed here. | - For PBES2, `p2s` and `p2c` may be placed here or in the applicable recipient header. - For ECDH-ES encryption, a protected header must be configured. Chilkat generates a fresh ephemeral EC key and writes its public JWK to `epk`. Optional `apu` and `apv` values must be supplied here as base64url strings. - For single-recipient compact AES-GCM key wrapping, Chilkat writes the wrapping `iv` and `tag` here. In JSON serialization they are written to the recipient header instead. - `zip`:`DEF` enables DEFLATE compression. Other `zip` values are ignored. **Object reuse:** Encryption can add generated members such as ECDH `epk` or AES-GCM key-wrap `iv`/`tag` to the stored headers. These values remain for later calls. Reusing an existing AES-GCM wrapping IV with the same key is unsafe; use a fresh `Jwe` object or reset the headers for each independent encryption. **Critical extensions:** The `Jwe` class does not enforce `crit`. Applications that accept critical JOSE extensions must inspect this header and reject unsupported entries before trusting the decrypted content. Returns True for success, False for failure. ### Jwe.SetPublicKey `Chilkat 11.7.0 · pascal · Jwe · SetPublicKey · method · since 9.5.0.66` ```pascal // pubKey is a TPublicKey object. function SetPublicKey(index: Integer;     pubKey: TChilkatBase): Boolean; ``` Sets the public key used to encrypt for recipient `index`. The valid index range is `0` through `1000`. Chilkat copies `pubKey` and replaces only the public key at that index; the source object need not remain alive. | Key type | Applicable `alg` values | | :--- | :--- | | RSA public key | `RSA1_5`, `RSA-OAEP`, `RSA-OAEP-256`, `RSA-OAEP-384`, and `RSA-OAEP-512`. | | EC public key | `ECDH-ES` and the `ECDH-ES+A128KW`, `+A192KW`, and `+A256KW` variants. | For ECDH-ES, Chilkat generates a fresh ephemeral key pair for each encryption on the same curve as the recipient key and writes the generated public key to protected-header `epk`. If an `epk` object was preconfigured, only its `crv` value is used as a curve-name hint; Chilkat replaces its `kty`, `x`, and `y` values. NIST P-256, P-384, P-521, and supported Brainpool EC keys can be used. X25519 is not supported by this JWE ECDH-ES implementation. ECDH-ES, including its `+A*KW` variants, should be used with a single recipient. **Validation timing:** A `True` result means the key was copied. Key type, size, curve, and `alg` compatibility are checked when `Encrypt`, `EncryptSb`, or `EncryptBd` runs. If the setter fails, the previously stored key remains unchanged. **Algorithm names:** `RSA-OAEP-384` and `RSA-OAEP-512` are Chilkat extensions beyond the base JOSE algorithm set; confirm peer interoperability before selecting them. **Recipient indexing:** Public keys contribute to create-mode `NumRecipients`. Configure a contiguous range beginning at index `0`; skipped lower indexes cause encryption to attempt incomplete recipients and fail. Returns True for success, False for failure. ### Jwe.SetRecipientHeader `Chilkat 11.7.0 · pascal · Jwe · SetRecipientHeader · method · since 9.5.0.66` ```pascal // json is a TJsonObject object. function SetRecipientHeader(index: Integer;     json: TChilkatBase): Boolean; ``` Sets the per-recipient unprotected header for zero-based recipient index `index`. The valid index range is `0` through `1000`. Chilkat copies `json`, and calling this method again at the same index replaces only that recipient header. In flattened JSON this becomes the top-level `header` member. In general JSON it becomes the `header` member of the corresponding element in the `recipients` array. An empty object is retained and emitted as `"header":{}`; it does not remove the recipient, and no recipient-removal method exists. Typical members include `kid`, recipient-specific `alg`, PBES2 `p2s`/`p2c`, or AES-GCM key-wrap `iv`/`tag`. Use the same index with the appropriate key or password setter. **Compact serialization:** A per-recipient header alone does not force JSON output. If compact serialization is selected for a single recipient, this header is omitted. Set `PreferCompact` to `False` when it must be serialized. **Recipient counting:** Before encryption, `NumRecipients` is determined by configured public keys, wrapping keys, and passwords. A recipient header by itself does not increase that count. **Not authenticated:** Per-recipient headers are unprotected. Treat values such as `kid` as routing hints and accept them only under application policy and after authenticated decryption succeeds. Returns True for success, False for failure. ### Jwe.SetUnprotectedHeader `Chilkat 11.7.0 · pascal · Jwe · SetUnprotectedHeader · method · since 9.5.0.66` ```pascal // json is a TJsonObject object. function SetUnprotectedHeader(json: TChilkatBase): Boolean; ``` Sets the shared JWE Unprotected Header from `json`. Chilkat copies the source `JsonObject`; a successful call replaces the previous shared unprotected header, while a failed call preserves it. The header applies to every recipient and can be represented only by JWE JSON Serialization. Setting it forces JSON output even when `json` is empty, in which case the output contains `"unprotected":{}`. **Not authenticated:** This header is neither encrypted nor integrity-protected. Do not place algorithm-policy, identity, authorization, or trusted key-location decisions here unless the application independently validates them. **Loading a JWE:** `LoadJwe` and `LoadJweSb` discard this configured header and replace all header state with the loaded message. Returns True for success, False for failure. ### Jwe.SetWrappingKey `Chilkat 11.7.0 · pascal · Jwe · SetWrappingKey · method · since 9.5.0.66` ```pascal function SetWrappingKey(index: Integer;     const encodedKey: string;     const encoding: string): Boolean; ``` Sets the symmetric key for recipient `index`. `encodedKey` contains the key bytes encoded according to `encoding`, such as `hex` or `base64`. The valid index range is `0` through `1000`. Chilkat decodes and copies the key. A decoding failure returns `False` and leaves the previous key at that index unchanged. Algorithm-specific key length is validated during encryption or decryption. | Algorithm family | Required key length | | :--- | :--- | | `A128KW` or `A128GCMKW` | 16 bytes | | `A192KW` or `A192GCMKW` | 24 bytes | | `A256KW` or `A256GCMKW` | 32 bytes | | `dir` with `A128GCM` | 16 bytes | | `dir` with `A192GCM` | 24 bytes | | `dir` with `A256GCM` | 32 bytes | | `dir` with `A128CBC-HS256` | 32 bytes | | `dir` with `A192CBC-HS384` | 48 bytes | | `dir` with `A256CBC-HS512` | 64 bytes | For `dir`, set the direct content-encryption key at index `0`. Direct encryption uses one shared key and is intended for a single recipient. **AES-GCM key wrapping:** For `A128GCMKW`, `A192GCMKW`, and `A256GCMKW`, Chilkat normally generates the required 12-byte wrapping IV and computes the 16-byte tag. A pre-set `iv` is used as-is and must decode to exactly 12 bytes. A pre-set `tag` is replaced by the computed tag. Compact output stores these values in the protected header; JSON output stores them in the recipient header. During decryption, the IV may be read from the recipient or a shared header; the tag is read from the recipient header, with the shared protected header also consulted for recipient index `0`. Both values are required. **Never reuse a wrapping IV:** Generated AES-GCM wrapping parameters remain in the stored headers after encryption. Reusing the object can therefore reuse an existing IV. Use a fresh object or reset the headers before each independent AES-GCM key-wrap encryption. **Recipient indexing:** Wrapping keys contribute to create-mode `NumRecipients`. Configure every index from `0` through the highest index used. Returns True for success, False for failure. ## Related classes [`BinData`](https://www.chilkatsoft.com/ai-docs/v/11.7.0/pascal/classes/BinData.md), [`JsonObject`](https://www.chilkatsoft.com/ai-docs/v/11.7.0/pascal/classes/JsonObject.md), [`PrivateKey`](https://www.chilkatsoft.com/ai-docs/v/11.7.0/pascal/classes/PrivateKey.md), [`PublicKey`](https://www.chilkatsoft.com/ai-docs/v/11.7.0/pascal/classes/PublicKey.md), [`StringBuilder`](https://www.chilkatsoft.com/ai-docs/v/11.7.0/pascal/classes/StringBuilder.md)