Jwe Delphi DLL Reference Documentation
Jwe
Current Version: 11.5.0
Chilkat.Jwe
Protect string or binary payloads using JWE content-encryption algorithms
and the key-management method required by the recipient.
Load a compact, flattened, or general JWE object and decrypt the payload
using the appropriate private key, symmetric key, or password.
Produce or consume compact serialization for single-recipient workflows,
or JSON serialization when richer header or multi-recipient structure is
needed.
Create JWE data for one recipient or use general JSON serialization when
the same encrypted payload must be decryptable by multiple recipients.
Configure protected headers, unprotected headers, recipient-specific
headers, and Additional Authenticated Data for protocol-specific JWE
requirements.
Use RSA key management, AES key wrapping, direct symmetric keys,
AES-GCM key wrapping, or PBES2 password-based key wrapping.
For an extended overview, see
Jwe Class Overview.
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
Decrypt JWE messages
Compact and JSON formats
Single or multiple recipients
Headers and AAD
Flexible key management
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.
Create/Dispose
var myObject: HCkJwe; begin myObject := CkJwe_Create(); // ... CkJwe_Dispose(myObject); end;
Creates an instance of the HCkJwe object and returns a handle (i.e. a Pointer). The handle is passed in the 1st argument for the functions listed on this page.
Objects created by calling CkJwe_Create must be freed by calling this method. A memory leak occurs if a handle is not disposed by calling this function.
Properties
DebugLogFilePath
procedure CkJwe_putDebugLogFilePath(objHandle: HCkJwe; newPropVal: PWideChar); stdcall;
function CkJwe__debugLogFilePath(objHandle: HCkJwe): PWideChar; stdcall;
If set to a file path, this property logs the LastErrorText of each Chilkat method or property call to the specified file. This logging helps identify the context and history of Chilkat calls leading up to any crash or hang, aiding in debugging.
Enabling the VerboseLogging property provides more detailed information. This property is mainly used for debugging rare instances where a Chilkat method call causes a hang or crash, which should generally not happen.
Possible causes of hangs include:
- A timeout property set to 0, indicating an infinite timeout.
- A hang occurring within an event callback in the application code.
- An internal bug in the Chilkat code causing the hang.
See the notes about PWideChar memory ownership and validity.
LastErrorHtml
function CkJwe__lastErrorHtml(objHandle: HCkJwe): PWideChar; stdcall;
Provides HTML-formatted information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.
See the notes about PWideChar memory ownership and validity.
topLastErrorText
function CkJwe__lastErrorText(objHandle: HCkJwe): PWideChar; stdcall;
Provides plain text information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.
See the notes about PWideChar memory ownership and validity.
LastErrorXml
function CkJwe__lastErrorXml(objHandle: HCkJwe): PWideChar; stdcall;
Provides XML-formatted information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.
See the notes about PWideChar memory ownership and validity.
topLastMethodSuccess
procedure CkJwe_putLastMethodSuccess(objHandle: HCkJwe; newPropVal: wordbool); stdcall;
Indicates the success or failure of the most recent method call: True means success, False means failure. This property remains unchanged by property setters or getters. This method is present to address challenges in checking for null or Nothing returns in certain programming languages. Note: This property does not apply to methods that return integer values or to boolean-returning methods where the boolean does not indicate success or failure.
NumRecipients
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.
Jwe object for an unrelated recipient set.PreferCompact
procedure CkJwe_putPreferCompact(objHandle: HCkJwe; newPropVal: wordbool); stdcall;
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.
PreferCompact to False when AAD must be carried and authenticated.PreferFlattened
procedure CkJwe_putPreferFlattened(objHandle: HCkJwe; newPropVal: wordbool); stdcall;
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.
UncommonOptions
procedure CkJwe_putUncommonOptions(objHandle: HCkJwe; newPropVal: PWideChar); stdcall;
function CkJwe__uncommonOptions(objHandle: HCkJwe): PWideChar; stdcall;
Provides a catch-all string for 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.
Jwe.UncommonOptions keywords. Leave the property empty unless a Chilkat release note, example, or support response provides the exact option name, syntax, and intended use.See the notes about PWideChar memory ownership and validity.
topVerboseLogging
procedure CkJwe_putVerboseLogging(objHandle: HCkJwe; newPropVal: wordbool); stdcall;
If set to True, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. The default value is False. Verbose logging should only be used for debugging. The potentially large quantity of logged information may adversely affect peformance.
Version
function CkJwe__version(objHandle: HCkJwe): PWideChar; stdcall;
Version of the component/library, such as "10.1.0"
See the notes about PWideChar memory ownership and validity.
Methods
Decrypt
index: Integer;
charset: PWideChar;
outStr: HCkString): wordbool; stdcall;
function CkJwe__decrypt(objHandle: HCkJwe;
index: Integer;
charset: PWideChar): PWideChar; stdcall;
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.
- Call
LoadJweorLoadJweSb. - Inspect headers and select an acceptable recipient and algorithm under application policy.
- Set the required private key, wrapping key, or password at the same index.
- 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.
Decrypt to fail.Returns True for success, False for failure.
See the notes about PWideChar memory ownership and validity.
DecryptBd
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.
bd is left unchanged; no partial or unauthenticated plaintext is delivered.Returns True for success, False for failure.
DecryptSb
index: Integer;
charset: PWideChar;
contentSb: HCkStringBuilder): wordbool; stdcall;
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.
contentSb is left unchanged; no unauthenticated or partially decoded plaintext is delivered.charset cause failure. Use DecryptBd for raw binary plaintext.Returns True for success, False for failure.
Encrypt
content: PWideChar;
charset: PWideChar;
outStr: HCkString): wordbool; stdcall;
function CkJwe__encrypt(objHandle: HCkJwe;
content: PWideChar;
charset: PWideChar): PWideChar; stdcall;
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.
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.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.
See the notes about PWideChar memory ownership and validity.
EncryptBd
contentBd: HCkBinData;
jweSb: HCkStringBuilder): wordbool; stdcall;
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.
True/False return before using jweSb. A failure does not append a partial JWE.Returns True for success, False for failure.
EncryptSb
contentSb: HCkStringBuilder;
charset: PWideChar;
jweSb: HCkStringBuilder): wordbool; stdcall;
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.
True/False return before using jweSb. A failure does not append a partial JWE.Returns True for success, False for failure.
FindRecipient
paramName: PWideChar;
paramValue: PWideChar;
caseSensitive: wordbool): Integer; stdcall;
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.
GetHeader
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.
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.
GetProtectedHeader
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.
Jwe class does not enforce crit; applications requiring critical-extension processing must do so themselves.Returns True for success, False for failure.
LoadJwe
jwe: PWideChar): wordbool; stdcall;
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.
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.
LoadJweSb
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.
SetAad
aad: PWideChar;
charset: PWideChar): wordbool; stdcall;
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.
PreferCompact to False when AAD must be emitted.aad value. Do not call this method merely to repeat AAD before decryption.SetAadBd when the protocol defines exact binary AAD.Returns True for success, False for failure.
SetAadBd
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.
PreferCompact to False when AAD is required.Returns True for success, False for failure.
SetPassword
index: Integer;
password: PWideChar): wordbool; stdcall;
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.
p2c range before decryption.NumRecipients. Configure a contiguous recipient range beginning at index 0.Returns True for success, False for failure.
SetPrivateKey
index: Integer;
privKey: HCkPrivateKey): wordbool; stdcall;
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.
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 while using SHA-1 for the mask-generation function.NumRecipients.Returns True for success, False for failure.
SetProtectedHeader
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,
p2sandp2cmay 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. Optionalapuandapvvalues must be supplied here as base64url strings. - For single-recipient compact AES-GCM key wrapping, Chilkat writes the wrapping
ivandtaghere. In JSON serialization they are written to the recipient header instead. zip:DEFenables DEFLATE compression. Otherzipvalues are ignored.
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.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.
SetPublicKey
index: Integer;
pubKey: HCkPublicKey): wordbool; stdcall;
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.
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.RSA-OAEP-384 and RSA-OAEP-512 are Chilkat extensions beyond the base JOSE algorithm set; confirm peer interoperability before selecting them.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.
SetRecipientHeader
index: Integer;
json: HCkJsonObject): wordbool; stdcall;
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.
PreferCompact to False when it must be serialized.NumRecipients is determined by configured public keys, wrapping keys, and passwords. A recipient header by itself does not increase that count.kid as routing hints and accept them only under application policy and after authenticated decryption succeeds.Returns True for success, False for failure.
SetUnprotectedHeader
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":{}.
LoadJwe and LoadJweSb discard this configured header and replace all header state with the loaded message.Returns True for success, False for failure.
SetWrappingKey
index: Integer;
encodedKey: PWideChar;
encoding: PWideChar): wordbool; stdcall;
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.
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.NumRecipients. Configure every index from 0 through the highest index used.Returns True for success, False for failure.