---
product: Chilkat
product_version: 11.7.0
language: c
language_label: C
class: Jws
license: bundle
deprecated: false
reference_html: https://www.chilkatsoft.com/refdoc/c_CkJwsRef.html
---
# Chilkat Jws — C — v11.7.0

> Chilkat 11.7.0 · language=c · class=Jws
> Other versions: replace `11.7.0` in this URL. Other languages: `https://www.chilkatsoft.com/ai-docs/v/11.7.0/<lang>/classes/Jws.md`.
> Language-wide rules (install, unlock, error model, strings/bytes): `https://www.chilkatsoft.com/ai-docs/v/11.7.0/c/guide.md`.

## Purpose

**Create, serialize, load, inspect, and validate JSON Web Signatures.**

`Chilkat.Jws` is the Chilkat class for creating and validating JSON Web Signatures. It supports compact serialization, flattened JSON serialization, general JSON serialization, single or multiple signatures, protected and unprotected headers, text and binary payloads, detached or embedded payload workflows, and signature algorithms such as HMAC, RSA, ECDSA, and RSA-PSS.

**Create JWS signatures**

Sign text or binary payloads using the key type and algorithm required by the target protocol or application.

**Validate signed data**

Load a JWS and verify its signature using the matching shared secret, public key, certificate, or other verification key.

**Compact and JSON forms**

Use compact serialization for common single-signature workflows, or JSON serialization when headers, multiple signatures, or richer structure is needed.

**Multiple signatures**

Use general JSON serialization when the same payload must be signed by more than one key or party.

**Header control**

Set protected and unprotected header fields such as `alg`, `kid`, `typ`, `cty`, or other protocol-specific values.

**Algorithm flexibility**

Work with HMAC, RSA, ECDSA, and RSA-PSS signatures depending on the trust model, key material, and interoperability requirements.

**Common pattern:** Choose the JWS serialization format, set the protected header values such as `alg`, provide the payload, add one or more signing keys, and create the JWS. To verify, load the JWS, provide the matching verification key for the signature, validate it, and then retrieve or inspect the payload and headers.

For an extended overview, see [Jws Class Overview](https://www.chilkatsoft.com/jws_class_overview.asp).

## Object creation, unlocking and error handling

**Create/Dispose**

```c
HCkJws instance = CkJws_Create();
// ...
CkJws_Dispose(instance);
```

`HCkJws CkJws_Create(void);`

Creates an instance of the HCkJws object and returns a handle ("void \*" pointer). The handle is passed in the 1st argument for the functions listed on this page.

`void CkJws_Dispose(HCkJws handle);`

Objects created by calling CkJws_Create must be freed by calling this method. A memory leak occurs if a handle is not disposed by calling this function. Also, any handle returned by a Chilkat "C" function must also be freed by the application by calling the appropriate Dispose method, such as CkJws_Dispose.

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

## 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` | `void CkJws_getDebugLogFilePath(HCkJws cHandle, HCkString retval); void CkJws_putDebugLogFilePath(HCkJws cHandle, const char *newVal); const char *CkJws_debugLogFilePath(HCkJws cHandle);` | 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` | `void CkJws_getLastErrorHtml(HCkJws cHandle, HCkString retval); const char *CkJws_lastErrorHtml(HCkJws cHandle);` | read-only | Provides HTML-formatted information about the last called method or property. |
| `LastErrorText` | `void CkJws_getLastErrorText(HCkJws cHandle, HCkString retval); const char *CkJws_lastErrorText(HCkJws cHandle);` | read-only | Provides plain text information about the last called method or property. |
| `LastErrorXml` | `void CkJws_getLastErrorXml(HCkJws cHandle, HCkString retval); const char *CkJws_lastErrorXml(HCkJws cHandle);` | read-only | Provides XML-formatted information about the last called method or property. |
| `LastMethodSuccess` | `BOOL CkJws_getLastMethodSuccess(HCkJws cHandle); void CkJws_putLastMethodSuccess(HCkJws cHandle, BOOL newVal);` | read/write | Indicates the success or failure of the most recent method call: `TRUE` means success, `FALSE` means failure. |
| `Utf8` | `BOOL CkJws_getUtf8(HCkJws cHandle); void CkJws_putUtf8(HCkJws cHandle, BOOL newVal);` | read/write | When set to `TRUE`, all `const char *` arguments and return values are interpreted as UTF-8 strings. |
| `VerboseLogging` | `BOOL CkJws_getVerboseLogging(HCkJws cHandle); void CkJws_putVerboseLogging(HCkJws cHandle, BOOL newVal);` | read/write | If set to `TRUE`, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. |
| `Version` | `void CkJws_getVersion(HCkJws cHandle, HCkString retval); const char *CkJws_version(HCkJws cHandle);` | read-only | Version of the component/library, such as "10.1.0" |

## Member index

| Member | Kind | Signature |
|---|---|---|
| `NumSignatures` | property, read-only | `int CkJws_getNumSignatures(HCkJws cHandle);` |
| `PreferCompact` | property, read/write | `BOOL CkJws_getPreferCompact(HCkJws cHandle); void CkJws_putPreferCompact(HCkJws cHandle, BOOL newVal);` |
| `PreferFlattened` | property, read/write | `BOOL CkJws_getPreferFlattened(HCkJws cHandle); void CkJws_putPreferFlattened(HCkJws cHandle, BOOL newVal);` |
| `UncommonOptions` | property, read/write | `void CkJws_getUncommonOptions(HCkJws cHandle, HCkString retval); void CkJws_putUncommonOptions(HCkJws cHandle, const char *newVal); const char *CkJws_uncommonOptions(HCkJws cHandle);` |
| `CreateJws` | method | `BOOL CkJws_CreateJws(HCkJws cHandle, HCkString outStr); const char *CkJws_createJws(HCkJws cHandle);` |
| `CreateJwsSb` | method | `BOOL CkJws_CreateJwsSb(HCkJws cHandle, HCkStringBuilder sbJws);` |
| `GetPayload` | method | `BOOL CkJws_GetPayload(HCkJws cHandle, const char *charset, HCkString outStr); const char *CkJws_getPayload(HCkJws cHandle, const char *charset);` |
| `GetPayloadBd` | method | `BOOL CkJws_GetPayloadBd(HCkJws cHandle, HCkBinData binData);` |
| `GetPayloadSb` | method | `BOOL CkJws_GetPayloadSb(HCkJws cHandle, const char *charset, HCkStringBuilder sbPayload);` |
| `GetProtectedH` | method | `BOOL CkJws_GetProtectedH(HCkJws cHandle, int index, HCkJsonObject json);` |
| `GetUnprotectedH` | method | `BOOL CkJws_GetUnprotectedH(HCkJws cHandle, int index, HCkJsonObject json);` |
| `LoadJws` | method | `BOOL CkJws_LoadJws(HCkJws cHandle, const char *jwsStr);` |
| `LoadJwsSb` | method | `BOOL CkJws_LoadJwsSb(HCkJws cHandle, HCkStringBuilder sbJws);` |
| `SetMacKey` | method | `BOOL CkJws_SetMacKey(HCkJws cHandle, int index, const char *key, const char *encoding);` |
| `SetMacKeyBd` | method | `BOOL CkJws_SetMacKeyBd(HCkJws cHandle, int index, HCkBinData key);` |
| `SetPayload` | method | `BOOL CkJws_SetPayload(HCkJws cHandle, const char *payload, const char *charset, BOOL includeBom);` |
| `SetPayloadBd` | method | `BOOL CkJws_SetPayloadBd(HCkJws cHandle, HCkBinData binData);` |
| `SetPayloadSb` | method | `BOOL CkJws_SetPayloadSb(HCkJws cHandle, HCkStringBuilder sbPayload, const char *charset, BOOL includeBom);` |
| `SetPrivateKey` | method | `BOOL CkJws_SetPrivateKey(HCkJws cHandle, int index, HCkPrivateKey privKey);` |
| `SetProtectedHeader` | method | `BOOL CkJws_SetProtectedHeader(HCkJws cHandle, int index, HCkJsonObject json);` |
| `SetPublicKey` | method | `BOOL CkJws_SetPublicKey(HCkJws cHandle, int index, HCkPublicKey pubKey);` |
| `SetSigningCert` | method | `BOOL CkJws_SetSigningCert(HCkJws cHandle, int index, HCkCert cert);` |
| `SetUnprotectedHeader` | method | `BOOL CkJws_SetUnprotectedHeader(HCkJws cHandle, int index, HCkJsonObject json);` |
| `Validate` | method | `int CkJws_Validate(HCkJws cHandle, int index);` |

Deprecated members are listed at the end of this file with their replacements; do not use them in new code.

## Properties

### Jws.NumSignatures

`Chilkat 11.7.0 · c · Jws · NumSignatures · property · read-only · since 9.5.0.66`

```c
int CkJws_getNumSignatures(HCkJws cHandle);
```

Returns the number of signature slots represented by this object.

After a successful `LoadJws` or `LoadJwsSb`, this is the number of signatures in the loaded serialization: `1` for compact or flattened form, or the number of elements in the general JSON `signatures` array.

During creation, only `SetProtectedHeader` and `SetUnprotectedHeader` establish signature slots. The value is one greater than the highest index having either type of header. Key setters attach key material but do not change this property.

**Contiguous indexes are required:** Indexes are valid from `0` through `1000`. If a header is set at index `2`, this property becomes `3`; `CreateJws` then requires configured headers at indexes `0`, `1`, and `2`. A gap causes creation to fail.

### Jws.PreferCompact

`Chilkat 11.7.0 · c · Jws · PreferCompact · property · read/write · since 9.5.0.66`

```c
BOOL CkJws_getPreferCompact(HCkJws cHandle);
void CkJws_putPreferCompact(HCkJws cHandle, BOOL newVal);
```

Controls whether Chilkat uses JWS Compact Serialization for a single signature. The default is `TRUE`.

| Configured state | Output |
| :--- | :--- |
| No signature headers | Creation fails. |
| One signature and `PreferCompact = TRUE` | Compact Serialization. A protected header must exist. Any unprotected header is not represented. |
| One signature, `PreferCompact = FALSE`, `PreferFlattened = TRUE` | Flattened JWS JSON Serialization. |
| One signature, both preference properties `FALSE` | General JWS JSON Serialization with one element in `signatures`. |
| More than one signature | General JWS JSON Serialization, regardless of the preference properties. |

Compact output has the form `protected.payload.signature`. It requires a protected header and cannot represent an unprotected header. If both header types are configured and compact output is selected, the unprotected header is omitted from the result.

**Attached payload only:** Chilkat always emits the base64url-encoded payload. The class has no built-in detached-payload mode and does not support RFC 7797 `b64=false` payloads.

### Jws.PreferFlattened

`Chilkat 11.7.0 · c · Jws · PreferFlattened · property · read/write · since 9.5.0.66`

```c
BOOL CkJws_getPreferFlattened(HCkJws cHandle);
void CkJws_putPreferFlattened(HCkJws cHandle, BOOL newVal);
```

Controls which JSON form is used when creating a JWS with exactly one signature and `PreferCompact` is `FALSE`. The default is `TRUE`.

| Setting | One-signature JSON output |
| :--- | :--- |
| `TRUE` | Flattened JSON, with `protected`, `header`, and `signature` directly in the top-level object. |
| `FALSE` | General JSON, with one signature object in the top-level `signatures` array. |

When more than one signature is configured, General JSON Serialization is always used and this property is ignored. Signature objects are emitted in ascending index order.

### Jws.UncommonOptions

`Chilkat 11.7.0 · c · Jws · UncommonOptions · property · read/write · since 10.1.0`

```c
void CkJws_getUncommonOptions(HCkJws cHandle, HCkString retval);
void CkJws_putUncommonOptions(HCkJws cHandle, const char *newVal);
const char *CkJws_uncommonOptions(HCkJws cHandle);
```

Provides a catch-all string for specialized compatibility options. The default is an empty string.

**No public JWS options are currently documented:** Leave this property empty unless an exact keyword and value are supplied by a Chilkat release note, example, or support response. Undocumented values should not be used as substitutes for JOSE headers or application policy.

## Methods

### Jws.CreateJws

`Chilkat 11.7.0 · c · Jws · CreateJws · method · since 9.5.0.66`

```c
BOOL CkJws_CreateJws(HCkJws cHandle, HCkString outStr);
const char *CkJws_createJws(HCkJws cHandle);
```

Creates and returns a JWS from the current payload, headers, and signing keys.

| Configured state | Output |
| :--- | :--- |
| No signature headers | Creation fails. |
| One signature and `PreferCompact = TRUE` | Compact Serialization. A protected header must exist. Any unprotected header is not represented. |
| One signature, `PreferCompact = FALSE`, `PreferFlattened = TRUE` | Flattened JWS JSON Serialization. |
| One signature, both preference properties `FALSE` | General JWS JSON Serialization with one element in `signatures`. |
| More than one signature | General JWS JSON Serialization, regardless of the preference properties. |

Signature slots must form a contiguous range from `0` through `NumSignatures - 1`. Each slot must have at least one header, an `alg` value, and compatible signing material. Chilkat looks for `alg` in the protected header first and then the unprotected header; matching is case-insensitive after trimming.

The payload is always attached and base64url encoded. If no payload setter was called, Chilkat signs a valid zero-length payload. Detached payloads and RFC 7797 unencoded payloads are not supported.

**Calling after `LoadJws`:** The loaded payload and headers are reused, but the existing serialized signatures are discarded and recomputed using the currently configured keys. Key material survives loads. For unrelated operations, a fresh `Jws` object avoids carrying keys forward.

**Signing algorithms:** `CreateJws` and `CreateJwsSb` support `HS256`, `HS384`, `HS512`; `RS256`, `RS384`, `RS512`; `PS256`, `PS384`, `PS512`; `ES256`, `ES384`, `ES512`; and `none`. The `none` algorithm produces an empty signature. Other identifiers, including `EdDSA`, `Ed25519`, `Ed448`, `ES256K`, Brainpool `bp*` identifiers, legacy SHA-1 algorithms, and private-use names, are not supported for signing.

Returns TRUE for success, FALSE for failure.

### Jws.CreateJwsSb

`Chilkat 11.7.0 · c · Jws · CreateJwsSb · method · since 9.5.0.66`

```c
BOOL CkJws_CreateJwsSb(HCkJws cHandle, HCkStringBuilder sbJws);
```

Creates a JWS using the same rules as `CreateJws` and writes it to `sbJws`.

The destination `StringBuilder` is cleared at the start. On success it contains the complete serialized JWS; on failure it remains empty and no partial JWS is returned.

**Creation requirements:** Signature indexes must be contiguous, each slot must have a header and `alg`, and the required MAC key, private key, or signing certificate must be configured at that same index.

Returns TRUE for success, FALSE for failure.

### Jws.GetPayload

`Chilkat 11.7.0 · c · Jws · GetPayload · method · since 9.5.0.66`

```c
BOOL CkJws_GetPayload(HCkJws cHandle, const char *charset, HCkString outStr);
const char *CkJws_getPayload(HCkJws cHandle, const char *charset);
```

Returns the loaded payload as text after decoding its bytes using charset `charset`.

If the charset is unsupported or the payload bytes are invalid for that charset, the method fails and returns no decoded text. Use `GetPayloadBd` to retrieve exact bytes.

**Extraction is not validation:** This method does not verify a signature. Treat the returned value as untrusted until the signatures required by the application have returned `1` from `Validate`.

Returns TRUE for success, FALSE for failure.

### Jws.GetPayloadBd

`Chilkat 11.7.0 · c · Jws · GetPayloadBd · method · since 9.5.0.66`

```c
BOOL CkJws_GetPayloadBd(HCkJws cHandle, HCkBinData binData);
```

Writes the exact loaded JWS payload bytes to `binData` without charset conversion.

The destination `BinData` is cleared first. On success it contains only the payload bytes; on failure it remains empty.

**Validate before use:** Loading and extracting a payload does not establish integrity or signer identity. Validate the required signature indexes before trusting these bytes.

Returns TRUE for success, FALSE for failure.

### Jws.GetPayloadSb

`Chilkat 11.7.0 · c · Jws · GetPayloadSb · method · since 9.5.0.66`

```c
BOOL CkJws_GetPayloadSb(HCkJws cHandle, const char *charset, HCkStringBuilder sbPayload);
```

Decodes the loaded payload bytes using charset `charset` and writes the resulting text to `sbPayload`.

The destination `StringBuilder` is cleared first. On success it contains the decoded payload; on failure, including a charset conversion error, it remains empty. Use `GetPayloadBd` when the payload is binary or its encoding is unknown.

**Extraction is not validation:** This method does not verify a signature. Treat the payload as untrusted until `Validate` returns `1` for every signer required by the application.

Returns TRUE for success, FALSE for failure.

### Jws.GetProtectedH

`Chilkat 11.7.0 · c · Jws · GetProtectedH · method · since 11.0.0`

```c
BOOL CkJws_GetProtectedH(HCkJws cHandle, int index, HCkJsonObject json);
```

Copies the decoded protected header of signature `index` into `json`. The valid zero-based index range is `0` through `1000`.

On success, the destination `JsonObject` is replaced with a clone of the header. On failure—an invalid index or no protected header—the destination is left unchanged. The method does not merge members.

**Exact signed representation:** The returned JSON is decoded content, not the original base64url text. During creation, Chilkat preserves JSON member insertion order and emits compact JSON; byte-for-byte test vectors require the same member order and formatting.

**Critical parameters:** Chilkat preserves but does not process `crit`. Inspect and enforce critical-extension and expected-algorithm policy before trusting a valid signature.

Returns TRUE for success, FALSE for failure.

### Jws.GetUnprotectedH

`Chilkat 11.7.0 · c · Jws · GetUnprotectedH · method · since 11.0.0`

```c
BOOL CkJws_GetUnprotectedH(HCkJws cHandle, int index, HCkJsonObject json);
```

Copies the optional unprotected header of signature `index` into `json`. The valid zero-based index range is `0` through `1000`.

On success, the destination `JsonObject` is replaced with a clone of the header. If no unprotected header exists, this method returns `FALSE` as a normal absence result and leaves the destination unchanged. An invalid index also returns `FALSE` and records an error.

**Not signed:** These members are not part of the JWS Signing Input. Chilkat does not reject a member name that also appears in the protected header; protected values take precedence when Chilkat looks up parameters such as `alg`.

Returns TRUE for success, FALSE for failure.

### Jws.LoadJws

`Chilkat 11.7.0 · c · Jws · LoadJws · method · since 9.5.0.66`

```c
BOOL CkJws_LoadJws(HCkJws cHandle, const char *jwsStr);
```

Loads a JWS from `jwsStr`.

Loads and parses a compact, flattened JSON, or general JSON JWS. Leading and trailing whitespace around the complete input is accepted. Input whose first non-whitespace character is `{` is parsed as JSON; all other input is treated as compact serialization.

| Form | Load requirements |
| :--- | :--- |
| Compact | Exactly three dot-separated parts. The protected header must base64url-decode to a JSON object. An empty payload segment is allowed. |
| Flattened JSON | A top-level `payload` and `signature` are required. |
| General JSON | A top-level `payload` and `signatures` array are required. Each array element must contain `signature`. An empty array is accepted and produces `NumSignatures = 0`. |

If a `signatures` array is present, general form takes precedence and top-level flattened signature fields are ignored. Unknown top-level JSON members are ignored. Structural and payload/protected-header decoding errors are detected while loading; algorithm, key compatibility, and cryptographic signature checks are deferred until `Validate`.

**State replacement:** Loading clears the previous payload and all protected and unprotected headers before parsing, but retains MAC keys, public keys, private keys, and signing certificates. A failed load does not restore the prior JWS; the object is left cleared or partially populated while key material remains.

**No detached input:** The payload must be present. JSON without a `payload` member fails, and there is no method to supply external detached content for validation.

Returns TRUE for success, FALSE for failure.

### Jws.LoadJwsSb

`Chilkat 11.7.0 · c · Jws · LoadJwsSb · method · since 9.5.0.66`

```c
BOOL CkJws_LoadJwsSb(HCkJws cHandle, HCkStringBuilder sbJws);
```

Loads a JWS from the current contents of `sbJws`.

Loads and parses a compact, flattened JSON, or general JSON JWS. Leading and trailing whitespace around the complete input is accepted. Input whose first non-whitespace character is `{` is parsed as JSON; all other input is treated as compact serialization.

| Form | Load requirements |
| :--- | :--- |
| Compact | Exactly three dot-separated parts. The protected header must base64url-decode to a JSON object. An empty payload segment is allowed. |
| Flattened JSON | A top-level `payload` and `signature` are required. |
| General JSON | A top-level `payload` and `signatures` array are required. Each array element must contain `signature`. An empty array is accepted and produces `NumSignatures = 0`. |

If a `signatures` array is present, general form takes precedence and top-level flattened signature fields are ignored. Unknown top-level JSON members are ignored. Structural and payload/protected-header decoding errors are detected while loading; algorithm, key compatibility, and cryptographic signature checks are deferred until `Validate`.

**State replacement:** Loading clears the previous payload and all protected and unprotected headers before parsing, but retains MAC keys, public keys, private keys, and signing certificates. A failed load does not restore the prior JWS; the object is left cleared or partially populated while key material remains.

**No detached input:** The payload must be present. JSON without a `payload` member fails, and there is no method to supply external detached content for validation.

Returns TRUE for success, FALSE for failure.

### Jws.SetMacKey

`Chilkat 11.7.0 · c · Jws · SetMacKey · method · since 9.5.0.66`

```c
BOOL CkJws_SetMacKey(HCkJws cHandle, int index, const char *key, const char *encoding);
```

Sets the symmetric MAC key for signature `index`. The valid zero-based index range is `0` through `1000`. `key` is decoded using binary encoding `encoding`, and the resulting bytes are copied.

This setter attaches key material but does not establish a signature slot or change `NumSignatures`. Calling it again at the same index replaces the previous MAC key. A successful return means the key text decoded and was stored; algorithm and key-length compatibility are checked when creating or validating.

| `alg` | Application-recommended minimum key length |
| :--- | :--- |
| `HS256` | 32 bytes |
| `HS384` | 48 bytes |
| `HS512` | 64 bytes |

**Key length is not enforced:** Chilkat accepts shorter HMAC keys silently for both creation and validation. The application is responsible for meeting its security policy and the JOSE recommendation that the key be at least as long as the hash output.

Returns TRUE for success, FALSE for failure.

### Jws.SetMacKeyBd

`Chilkat 11.7.0 · c · Jws · SetMacKeyBd · method · since 9.5.0.66`

```c
BOOL CkJws_SetMacKeyBd(HCkJws cHandle, int index, HCkBinData key);
```

Sets the symmetric MAC key for signature `index` from a copy of the raw bytes in `key`. The valid zero-based index range is `0` through `1000`.

This setter does not create a signature slot. Calling it again replaces only the MAC key at this index. Key length is not checked until use—and Chilkat does not enforce the recommended minimum even during creation or validation.

| `alg` | Application-recommended minimum key length |
| :--- | :--- |
| `HS256` | 32 bytes |
| `HS384` | 48 bytes |
| `HS512` | 64 bytes |

**Key selection:** The MAC key is used only when `alg` is `HS256`, `HS384`, or `HS512`. Other key objects configured at the same index are ignored for an HMAC algorithm.

Returns TRUE for success, FALSE for failure.

### Jws.SetPayload

`Chilkat 11.7.0 · c · Jws · SetPayload · method · since 9.5.0.66`

```c
BOOL CkJws_SetPayload(HCkJws cHandle, const char *payload, const char *charset, BOOL includeBom);
```

Replaces the current payload with `payload` converted to bytes using charset `charset`.

If `includeBom` is `TRUE`, a byte-order mark is included when the charset defines one. Unsupported charsets or unrepresentable text cause this method to return `FALSE`. The payload bytes are copied.

An empty string establishes a valid zero-length payload, which is equivalent to having never set a payload. Chilkat always includes the base64url-encoded payload in generated output.

**JWS signs bytes:** Charset and BOM choices change the exact signing input. UTF-8 without a BOM is normally preferred. Built-in detached payloads and RFC 7797 `b64=false` are not supported.

Returns TRUE for success, FALSE for failure.

### Jws.SetPayloadBd

`Chilkat 11.7.0 · c · Jws · SetPayloadBd · method · since 9.5.0.66`

```c
BOOL CkJws_SetPayloadBd(HCkJws cHandle, HCkBinData binData);
```

Replaces the current JWS payload with a copy of all bytes in `binData`. Use this method for binary data or whenever the exact byte sequence must be preserved without charset conversion.

An empty `BinData` establishes a valid zero-length payload. The class does not distinguish this from never having called a payload setter.

**Attached, encoded payload:** Chilkat always base64url encodes these bytes and includes the resulting payload segment or JSON member. Built-in detached payloads and `b64=false` unencoded payloads are not supported.

Returns TRUE for success, FALSE for failure.

### Jws.SetPayloadSb

`Chilkat 11.7.0 · c · Jws · SetPayloadSb · method · since 9.5.0.66`

```c
BOOL CkJws_SetPayloadSb(HCkJws cHandle, HCkStringBuilder sbPayload, const char *charset, BOOL includeBom);
```

Replaces the current payload with the text in `sbPayload`, converted to bytes using charset `charset`. The bytes are copied; the source `StringBuilder` does not need to remain alive.

If `includeBom` is `TRUE`, a byte-order mark is included when the chosen charset defines one. Charset conversion failure, including unsupported charset or unrepresentable text, causes this method to return `FALSE`.

An empty input establishes a valid zero-length payload. Chilkat always base64url encodes and includes the payload in the generated JWS.

**Exact bytes are signed:** The charset and BOM determine the octets covered by the signature. UTF-8 without a BOM is the usual interoperable choice for textual or JSON payloads. Use `SetPayloadBd` for exact binary bytes.

Returns TRUE for success, FALSE for failure.

### Jws.SetPrivateKey

`Chilkat 11.7.0 · c · Jws · SetPrivateKey · method · since 9.5.0.66`

```c
BOOL CkJws_SetPrivateKey(HCkJws cHandle, int index, HCkPrivateKey privKey);
```

Sets a private key for creating signature `index`. The valid zero-based index range is `0` through `1000`. The key is cloned, so the source object does not need to remain alive.

This setter does not establish a signature slot. A successful return means the key was accepted and copied; key type, RSA size, EC curve, and compatibility with the header's `alg` are validated during `CreateJws`.

| `alg` family | Key used |
| :--- | :--- |
| `RS256`, `RS384`, `RS512` | RSA key; RSASSA-PKCS1-v1_5 with the corresponding SHA-2 hash. |
| `PS256`, `PS384`, `PS512` | RSA key; RSASSA-PSS using the same hash for MGF1 and a salt whose length equals the hash output length. |
| `ES256` | EC key on P-256; JWS signature is the 64-byte fixed-width `R \|\| S` value. |
| `ES384` | EC key on P-384; JWS signature is the 96-byte fixed-width `R \|\| S` value. |
| `ES512` | EC key on P-521; JWS signature is the 132-byte fixed-width `R \|\| S` value. |

**Precedence:** For RSA or ECDSA signing, an explicitly set private key takes precedence over a signing certificate at the same index. A public key may coexist and is used only by `Validate`. Setting one key kind does not clear the others.

**ECDSA details:** Chilkat produces JOSE fixed-width `R || S` signatures. It does not force low-S normalization. The curve must exactly match ES256/P-256, ES384/P-384, or ES512/P-521.

Returns TRUE for success, FALSE for failure.

### Jws.SetProtectedHeader

`Chilkat 11.7.0 · c · Jws · SetProtectedHeader · method · since 9.5.0.66`

```c
BOOL CkJws_SetProtectedHeader(HCkJws cHandle, int index, HCkJsonObject json);
```

Sets the protected JOSE header for signature `index`. The valid zero-based index range is `0` through `1000`. Setting either a protected or unprotected header establishes the signature slot and can increase `NumSignatures`.

`json` is cloned; later modification or disposal of the source `JsonObject` does not change the stored header. Calling this method again at the same index replaces only that protected header. An empty object is stored as `{}` and still counts as a configured slot.

During signing, Chilkat serializes the object compactly, preserving member insertion order, UTF-8 encodes it, and base64url encodes the result. These exact encoded bytes are included in the JWS Signing Input.

**Where `alg` is found:** Chilkat checks the protected header first and then the unprotected header. Put `alg` in the protected header so the algorithm choice is integrity protected. If the same name appears in both headers, Chilkat does not reject the overlap; the protected value takes precedence.

**Unsupported extensions:** The `crit` parameter is preserved but not processed, and RFC 7797 `b64=false` is not supported. Applications that use critical extensions must inspect and enforce them independently.

Returns TRUE for success, FALSE for failure.

### Jws.SetPublicKey

`Chilkat 11.7.0 · c · Jws · SetPublicKey · method · since 9.5.0.66`

```c
BOOL CkJws_SetPublicKey(HCkJws cHandle, int index, HCkPublicKey pubKey);
```

Sets the public key used to validate signature `index`. The valid zero-based index range is `0` through `1000`. The key is cloned, so the source object does not need to remain alive.

This setter does not create a signature slot. Key type, RSA size, applicable EC-curve requirements, and compatibility with `alg` are checked during `Validate`, not by this method.

| `alg` family | Key used |
| :--- | :--- |
| `RS256`, `RS384`, `RS512` | RSA key; RSASSA-PKCS1-v1_5 with the corresponding SHA-2 hash. |
| `PS256`, `PS384`, `PS512` | RSA key; RSASSA-PSS using the same hash for MGF1 and a salt whose length equals the hash output length. |
| `ES256` | EC key on P-256; JWS signature is the 64-byte fixed-width `R \|\| S` value. |
| `ES384` | EC key on P-384; JWS signature is the 96-byte fixed-width `R \|\| S` value. |
| `ES512` | EC key on P-521; JWS signature is the 132-byte fixed-width `R \|\| S` value. |
| Other `es*` identifiers, such as `ES256K` | Verification only. Chilkat performs generic ECDSA verification using SHA-256 without enforcing a particular EC curve. |
| Brainpool `bp*` identifiers | Verification only. These are non-standard JOSE identifiers; Chilkat uses an EC key and SHA-256 without enforcing a particular curve. |

**No automatic key resolution:** Chilkat never resolves `jku` or `x5u`, imports an embedded `jwk`, extracts a key from `x5c`, or searches a certificate store by `kid`. The application must resolve and set the verification key at the same signature index.

**ECDSA verification:** For the standard identifiers, Chilkat accepts the JOSE raw fixed-width format: 64 bytes for `ES256`, 96 bytes for `ES384`, and 132 bytes for `ES512`, with the corresponding P-256, P-384, and P-521 curve requirements. High-S signatures are accepted. Other `es*` identifiers and Brainpool `bp*` identifiers are handled as verification-only generic ECDSA with SHA-256 and no curve check.

Returns TRUE for success, FALSE for failure.

### Jws.SetSigningCert

`Chilkat 11.7.0 · c · Jws · SetSigningCert · method · since 11.5.0`

```c
BOOL CkJws_SetSigningCert(HCkJws cHandle, int index, HCkCert cert);
```

Sets the certificate whose associated private key will be used to create signature `index`. The valid zero-based index range is `0` through `1000`. This setter attaches key material but does not establish a signature slot.

| `alg` family | Key used |
| :--- | :--- |
| `RS256`, `RS384`, `RS512` | RSA key; RSASSA-PKCS1-v1_5 with the corresponding SHA-2 hash. |
| `PS256`, `PS384`, `PS512` | RSA key; RSASSA-PSS using the same hash for MGF1 and a salt whose length equals the hash output length. |
| `ES256` | EC key on P-256; JWS signature is the 64-byte fixed-width `R \|\| S` value. |
| `ES384` | EC key on P-384; JWS signature is the 96-byte fixed-width `R \|\| S` value. |
| `ES512` | EC key on P-521; JWS signature is the 132-byte fixed-width `R \|\| S` value. |

If the certificate has an exportable private key, Chilkat copies the key and the source certificate need not remain alive. For a non-exportable smart-card or HSM-backed key, Chilkat retains the certificate and uses the platform key provider during `CreateJws`; keep the certificate and provider available until signing completes.

**Validation is deferred:** This method can return `TRUE` even when no usable private key is currently accessible; it logs a warning and the definitive failure occurs during `CreateJws`. PIN prompts and provider errors also occur while signing.

**Certificate status is not checked:** Chilkat does not require the certificate to be trusted, unexpired, or authorized for digital signatures, and it does not choose `alg` automatically. The application must set a compatible algorithm and apply any certificate policy it requires. An explicitly configured private key takes precedence over the certificate at the same index.

Returns TRUE for success, FALSE for failure.

### Jws.SetUnprotectedHeader

`Chilkat 11.7.0 · c · Jws · SetUnprotectedHeader · method · since 9.5.0.66`

```c
BOOL CkJws_SetUnprotectedHeader(HCkJws cHandle, int index, HCkJsonObject json);
```

Sets the optional unprotected JOSE header for signature `index`. The valid zero-based index range is `0` through `1000`. Setting either header type establishes the signature slot.

`json` is cloned. Calling this method again at the same index replaces only the unprotected header; it does not change the protected header or any key material. An empty object is stored and is emitted as `"header":{}` in JSON serialization.

An unprotected header is emitted only in flattened or general JWS JSON Serialization. It is not included in the JWS Signing Input. If compact output is selected for one signature, the unprotected header is omitted; if no protected header exists, compact creation fails.

**Not integrity protected:** Do not place trusted algorithm selection, authorization decisions, or key-selection data solely in this header. Chilkat does not reject names duplicated in the protected header; protected-header values take precedence.

Returns TRUE for success, FALSE for failure.

### Jws.Validate

`Chilkat 11.7.0 · c · Jws · Validate · method · since 9.5.0.66`

```c
int CkJws_Validate(HCkJws cHandle, int index);
```

Validates exactly one signature, identified by zero-based `index`, using the MAC key or public key configured at that same index.

| Return value | Meaning |
| :--- | :--- |
| `1` | The signature or MAC is cryptographically valid for this signature index. |
| `0` | A well-formed signature was checked but did not match. For HMAC, a wrong key or wrong-length signature normally produces this result. |
| `-1` | Validation could not be performed because of an error such as an invalid index, missing or unsupported `alg`, missing key, incompatible key type, a required curve mismatch for the standard `ES256`/`ES384`/`ES512` algorithms, a malformed signature, or an RSA/ECDSA verification error. |

Chilkat obtains `alg` from the protected header first and then the unprotected header. Matching is case-insensitive after trimming. If the same name is present in both headers, the protected value wins; the duplicate is not rejected.

**Verification algorithms:** `Validate` supports `HS256`, `HS384`, `HS512`; `RS256`, `RS384`, `RS512`; `PS256`, `PS384`, `PS512`; and `ES256`, `ES384`, `ES512`. Algorithm-family matching is prefix-based after trimming and case normalization. Other `es*` identifiers, such as `ES256K`, are treated as generic ECDSA using SHA-256 with no curve restriction. Brainpool `bp*` identifiers are also accepted for verification using an EC key and SHA-256 with no curve check; these are non-standard JOSE identifiers and are not supported for signing. `none` is rejected. `EdDSA`, `Ed25519`, `Ed448`, legacy SHA-1 algorithms, and names that do not begin with a recognized `hs`, `rs`, `ps`, `es`, or `bp` prefix are rejected with `-1`.

**Multiple signatures:** This method does not validate all signatures automatically. Loop from `0` through `NumSignatures - 1`, set the appropriate key at each index, and apply the application's required all/any/threshold signer policy.

**Header policy remains application-controlled:** The class does not process `crit` or enforce an expected-algorithm allowlist. A valid cryptographic result can still use an algorithm or header policy unacceptable to the application. Chilkat also never treats an RSA public key as an HMAC secret; HS algorithms require a separately configured MAC key.

## Deprecated members — do not use in new code

| Member | Kind | Deprecated in | Use instead |
|---|---|---|---|
| `GetProtectedHeader` | method | before 11.6.1 | `GetProtectedH` |
| `GetUnprotectedHeader` | method | before 11.6.1 | `GetUnprotectedH` |

## Related classes

[`BinData`](https://www.chilkatsoft.com/ai-docs/v/11.7.0/c/classes/BinData.md), [`Cert`](https://www.chilkatsoft.com/ai-docs/v/11.7.0/c/classes/Cert.md), [`JsonObject`](https://www.chilkatsoft.com/ai-docs/v/11.7.0/c/classes/JsonObject.md), [`PrivateKey`](https://www.chilkatsoft.com/ai-docs/v/11.7.0/c/classes/PrivateKey.md), [`PublicKey`](https://www.chilkatsoft.com/ai-docs/v/11.7.0/c/classes/PublicKey.md), [`StringBuilder`](https://www.chilkatsoft.com/ai-docs/v/11.7.0/c/classes/StringBuilder.md)