Jws PHP Extension Reference Documentation
CkJws
Current Version: 11.5.0
Chilkat.Jws
Sign text or binary payloads using the key type and algorithm required by
the target protocol or application.
Load a JWS and verify its signature using the matching shared secret,
public key, certificate, or other verification key.
Use compact serialization for common single-signature workflows, or JSON
serialization when headers, multiple signatures, or richer structure is
needed.
Use general JSON serialization when the same payload must be signed by
more than one key or party.
Set protected and unprotected header fields such as
Work with HMAC, RSA, ECDSA, and RSA-PSS signatures depending on the
trust model, key material, and interoperability requirements.
For an extended overview, see
Jws Class Overview.
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
Validate signed data
Compact and JSON forms
Multiple signatures
Header control
alg,
kid, typ, cty, or other
protocol-specific values.
Algorithm flexibility
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.
Object Creation
$obj = new CkJws();
Properties
DebugLogFilePath
void put_DebugLogFilePath(string strVal);
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.
LastErrorHtml
string lastErrorHtml();
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.
topLastErrorText
string lastErrorText();
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.
LastErrorXml
string lastErrorXml();
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.
topLastMethodSuccess
void put_LastMethodSuccess(bool boolVal);
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.
NumSignatures
int get_NumSignatures()
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.
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.PreferCompact
void put_PreferCompact(bool boolVal);
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 = | Compact Serialization. A protected header must exist. Any unprotected header is not represented. |
One signature, PreferCompact = , PreferFlattened = | Flattened JWS JSON Serialization. |
One signature, both preference properties | 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.
b64=false payloads.PreferFlattened
void put_PreferFlattened(bool boolVal);
Controls which JSON form is used when creating a JWS with exactly one signature and PreferCompact is falsetrue
| Setting | One-signature JSON output |
|---|---|
| Flattened JSON, with protected, header, and signature directly in the top-level object. |
| 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.
topUncommonOptions
void put_UncommonOptions(string strVal);
Provides a catch-all string for specialized compatibility options. The default is an empty string.
Utf8
void put_Utf8(bool boolVal);
When set to true, all string arguments and return values are interpreted as UTF-8 strings. When set to false, they are interpreted as ANSI strings.
In Chilkat v11.0.0 and later, the default value is true. Before v11.0.0, it was false.
VerboseLogging
void put_VerboseLogging(bool boolVal);
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
string version();
Methods
CreateJws
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 = | Compact Serialization. A protected header must exist. Any unprotected header is not represented. |
One signature, PreferCompact = , PreferFlattened = | Flattened JWS JSON Serialization. |
One signature, both preference properties | 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.
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.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.
CreateJwsSb
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.
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.
GetPayload
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.
1 from Validate.Returns true for success, false for failure.
GetPayloadBd
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.
Returns true for success, false for failure.
GetPayloadSb
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.
Validate returns 1 for every signer required by the application.Returns true for success, false for failure.
GetProtectedH
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.
crit. Inspect and enforce critical-extension and expected-algorithm policy before trusting a valid signature.Returns true for success, false for failure.
GetUnprotectedH
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 falsefalse
alg.Returns true for success, false for failure.
LoadJws
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.
payload member fails, and there is no method to supply external detached content for validation.Returns true for success, false for failure.
LoadJwsSb
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.
payload member fails, and there is no method to supply external detached content for validation.Returns true for success, false for failure.
SetMacKey
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 |
Returns true for success, false for failure.
SetMacKeyBd
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 |
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.
SetPayload
Replaces the current payload with payload converted to bytes using charset charset.
If includeBom is truefalse
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.
b64=false are not supported.Returns true for success, false for failure.
SetPayloadBd
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.
b64=false unencoded payloads are not supported.Returns true for success, false for failure.
SetPayloadSb
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 truefalse
An empty input establishes a valid zero-length payload. Chilkat always base64url encodes and includes the payload in the generated JWS.
SetPayloadBd for exact binary bytes.Returns true for success, false for failure.
SetPrivateKey
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. |
Validate. Setting one key kind does not clear the others.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.
SetProtectedHeader
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.
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.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.
SetPublicKey
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. |
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.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.
SetSigningCert
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.
trueCreateJws. PIN prompts and provider errors also occur while signing.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.
SetUnprotectedHeader
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.
Returns true for success, false for failure.
Validate
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.
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.0 through NumSignatures - 1, set the appropriate key at each index, and apply the application's required all/any/threshold signer policy.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
GetProtectedHeader
Returns a newly allocated clone of the decoded protected header for signature index. The valid index range is 0 through 1000.
The returned object belongs to the caller. This method returns NULL if the index is invalid or no protected header exists at that index.
GetProtectedH to load an existing JsonObject. The protected header is signed data, but its meaning should not be trusted until the corresponding signature validates and application policy accepts its parameters.Returns null on failure
GetUnprotectedHeader
Returns a newly allocated clone of the optional unprotected header for signature index. The valid index range is 0 through 1000.
The returned object belongs to the caller. This method returns NULL if the index is invalid or no unprotected header exists at that index.
GetUnprotectedH. Members in this object are not covered by the signature and must not be treated as trusted security decisions unless independently authenticated.Returns null on failure