Package com.chilkatsoft.chilkat2

Class Jwe

java.lang.Object
com.chilkatsoft.chilkat2.ChilkatObject
com.chilkatsoft.chilkat2.Jwe
All Implemented Interfaces:
AutoCloseable
public class Jwe extends ChilkatObject
<section class="jwe-summary">

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.

</section>

Instances hold a native Chilkat object: close them with ChilkatObject.close() (try-with-resources) when done; an unclosed instance is freed when it becomes unreachable.

See Also:
Online reference

  • Constructor Details

    • Jwe

      public Jwe()
      Creates a new Jwe object.

  • Method Details

    • getNumRecipients

      public int 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.

      Returns:
      the value of the NumRecipients property (read-only)

    • getPreferCompact

      public boolean getPreferCompact()
      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.

      Returns:
      the value of the PreferCompact property

    • setPreferCompact

      public void setPreferCompact​(boolean value)
      Sets the PreferCompact property; see getPreferCompact().
      Parameters:
      value - the new value

    • getPreferFlattened

      public boolean getPreferFlattened()
      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.

      Returns:
      the value of the PreferFlattened property

    • setPreferFlattened

      public void setPreferFlattened​(boolean value)
      Sets the PreferFlattened property; see getPreferFlattened().
      Parameters:
      value - the new value

    • getUncommonOptions

      public String getUncommonOptions()
      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.

      Returns:
      the value of the UncommonOptions property

    • setUncommonOptions

      public void setUncommonOptions​(String value)
      Sets the UncommonOptions property; see getUncommonOptions().
      Parameters:
      value - the new value (not null)

    • decrypt

      public String decrypt​(int index, String charset)
      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.

      Parameters:
      index - the index argument
      charset - the charset argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • decryptBd

      public void decryptBd​(int index, BinData bd)
      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.

      Parameters:
      index - the index argument
      bd - the bd argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • decryptSb

      public void decryptSb​(int index, String charset, StringBuilder contentSb)
      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.

      Parameters:
      index - the index argument
      charset - the charset argument (not null)
      contentSb - the contentSb argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • encrypt

      public String encrypt​(String content, String charset)
      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.

      Parameters:
      content - the content argument (not null)
      charset - the charset argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • encryptBd

      public void encryptBd​(BinData contentBd, StringBuilder jweSb)
      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.

      Parameters:
      contentBd - the contentBd argument (not null)
      jweSb - the jweSb argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • encryptSb

      public void encryptSb​(StringBuilder contentSb, String charset, StringBuilder jweSb)
      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.

      Parameters:
      contentSb - the contentSb argument (not null)
      charset - the charset argument (not null)
      jweSb - the jweSb argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • findRecipient

      public int findRecipient​(String paramName, String paramValue, boolean caseSensitive)
      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.

      Parameters:
      paramName - the paramName argument (not null)
      paramValue - the paramValue argument (not null)
      caseSensitive - the caseSensitive argument
      Returns:
      the result (see ChilkatObject.getLastMethodSuccess() where the description mentions failure)

    • getHeader

      public void getHeader​(JsonObject json)
      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.

      Parameters:
      json - the json argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getProtectedHeader

      public void getProtectedHeader​(JsonObject json)
      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.

      Parameters:
      json - the json argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • loadJwe

      public void loadJwe​(String jwe)
      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.

      Parameters:
      jwe - the jwe argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • loadJweSb

      public void loadJweSb​(StringBuilder sb)
      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.

      Parameters:
      sb - the sb argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setAad

      public void setAad​(String aad, String charset)
      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.

      Parameters:
      aad - the aad argument (not null)
      charset - the charset argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setAadBd

      public void setAadBd​(BinData aad)
      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.

      Parameters:
      aad - the aad argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setPassword

      public void setPassword​(int index, String password)
      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.

      Parameters:
      index - the index argument
      password - the password argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setPrivateKey

      public void setPrivateKey​(int index, PrivateKey privKey)
      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.

      Parameters:
      index - the index argument
      privKey - the privKey argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setProtectedHeader

      public void setProtectedHeader​(JsonObject json)
      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.

      Parameters:
      json - the json argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setPublicKey

      public void setPublicKey​(int index, PublicKey pubKey)
      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.

      Parameters:
      index - the index argument
      pubKey - the pubKey argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setRecipientHeader

      public void setRecipientHeader​(int index, JsonObject json)
      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.

      Parameters:
      index - the index argument
      json - the json argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setUnprotectedHeader

      public void setUnprotectedHeader​(JsonObject json)
      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.

      Parameters:
      json - the json argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setWrappingKey

      public void setWrappingKey​(int index, String encodedKey, String encoding)
      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.

      Parameters:
      index - the index argument
      encodedKey - the encodedKey argument (not null)
      encoding - the encoding argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why