Chilkat.Jws Class Overview

Chilkat.Jws creates, loads, signs, and validates JSON Web Signature objects. It supports compact and JSON serializations, single-signature and multi-signature JWSs, protected and unprotected headers, string and binary payloads, HMAC signatures, RSA signatures, RSA-PSS signatures, ECDSA signatures, and payload access through strings, StringBuilder, or BinData.

What the Class Is Used For

Use Chilkat.Jws when an application needs to produce or verify a JSON Web Signature. A JWS protects a payload with one or more digital signatures or MACs. The payload can be text or binary data, and each signature has its own protected header, optional unprotected header, and key material.

Create Signed Payloads Set a payload, configure one or more signature headers, provide signing keys, and call CreateJws or CreateJwsSb.
Validate Received JWSs Load a JWS, provide the correct public key or MAC key, and call Validate.
Support Multiple Algorithms Supports HMAC, RSA PKCS#1 v1.5, ECDSA, and RSA-PSS algorithm families.
Handle Text and Binary Payloads Use charset-aware methods for text and BinData methods for binary payloads.

Typical Signing Workflow

  1. Create a Jws object.
  2. Set the payload with SetPayload, SetPayloadSb, or SetPayloadBd.
  3. Create a protected header in a JsonObject, typically including the alg parameter.
  4. Call SetProtectedHeader for the signature index, usually index 0.
  5. Optionally call SetUnprotectedHeader when an unprotected header is needed.
  6. Set the signing key using SetPrivateKey, SetSigningCert, SetMacKey, or SetMacKeyBd.
  7. Call CreateJws or CreateJwsSb.
  8. Control output serialization preference with PreferCompact and PreferFlattened.

Typical Validation Workflow

  1. Load the JWS with LoadJws or LoadJwsSb.
  2. Inspect NumSignatures to determine how many signatures are present.
  3. Retrieve headers with GetProtectedH and GetUnprotectedH when needed.
  4. Provide the validation key for the signature index: SetPublicKey for RSA/ECC signatures, or SetMacKey / SetMacKeyBd for HMAC signatures.
  5. Call Validate for the signature index.
  6. Retrieve the payload with GetPayload, GetPayloadSb, or GetPayloadBd.
  7. Check LastErrorText after failures or unexpected results.

Core Concepts

Concept Meaning Important Members
Payload The data being signed. It may be text with a charset or raw binary bytes. SetPayload, SetPayloadSb, SetPayloadBd, GetPayload
Signature Index Each signature is addressed by a zero-based index. Most JWSs contain a single signature at index 0. NumSignatures, SetProtectedHeader, Validate
Protected Header A signature header that is integrity-protected by the signature. It normally contains the alg value. SetProtectedHeader, GetProtectedH
Unprotected Header Optional signature header data that is not protected by the signature. Its presence forces JWS JSON Serialization. SetUnprotectedHeader, GetUnprotectedH
MAC Signature HMAC-based JWS algorithms use a shared MAC key for both creating and validating signatures. SetMacKey, SetMacKeyBd
Public-Key Signature RSA, RSA-PSS, and ECDSA signatures are created with a private key and validated with the corresponding public key. SetPrivateKey, SetSigningCert, SetPublicKey

Core Properties

Property Purpose Guidance
NumSignatures Returns the number of signatures contained in the JWS. Use when validating multi-signature JWS JSON Serialization objects.
PreferCompact Controls whether compact serialization is preferred when creating a JWS. Default is true. Compact serialization is used when possible. Multiple signatures or any unprotected headers force JWS JSON Serialization.
PreferFlattened Controls whether flattened JSON serialization is preferred when JWS JSON Serialization is used. Default is true. Multiple signatures force general JWS JSON Serialization.
UncommonOptions Catch-all property for uncommon needs. Defaults to the empty string and should typically remain empty.
LastErrorText Diagnostic text for the last method or property access. Check after failures or unexpected behavior. Diagnostic information may be available regardless of success or failure.

Serialization Selection

Serialization When Used Related Setting
JWS Compact Serialization Preferred by default when the JWS can be represented compactly. PreferCompact = true
JWS JSON Serialization Used when multiple signatures exist or when any unprotected headers exist. Used regardless of PreferCompact in these cases.
Flattened JWS JSON Serialization Preferred when JSON Serialization is used and the JWS can be flattened. PreferFlattened = true
General JWS JSON Serialization Used when multiple signatures exist. Used regardless of PreferFlattened.
Important rule: Compact serialization is not used when there are multiple signatures or any unprotected headers. Those cases require JWS JSON Serialization.

Payload Methods

Task Method Behavior
Set text payload SetPayload Sets the payload from a string. The charset controls the byte representation. The includeBom flag controls whether a BOM is included when the charset defines one.
Set StringBuilder payload SetPayloadSb Sets the payload from a StringBuilder, using the supplied charset and optional BOM behavior.
Set binary payload SetPayloadBd Sets the payload from the raw bytes in a BinData object.
Get text payload GetPayload Returns the payload as a string. The charset tells Chilkat how to interpret the payload bytes as characters.
Get payload into StringBuilder GetPayloadSb Appends the payload text to a supplied StringBuilder using the supplied charset.
Get binary payload GetPayloadBd Appends the payload bytes to a supplied BinData object.
BOM guidance: For normal text payloads, includeBom should usually be false.

Creating and Loading JWS Data

Task Method Behavior
Create JWS string CreateJws Creates and returns the JWS using the previously set payload, headers, and keys.
Create JWS into StringBuilder CreateJwsSb Creates the JWS and appends it to a supplied StringBuilder.
Load JWS string LoadJws Loads a JWS from a string.
Load JWS from StringBuilder LoadJwsSb Loads a JWS from the contents of a StringBuilder.

Header Methods

Header Type Method Use
Protected header SetProtectedHeader Sets the protected header for a signature index. This is normally where the alg parameter is placed.
Read protected header GetProtectedH Returns the protected header for the signature at the specified index.
Unprotected header SetUnprotectedHeader Sets an optional unprotected header for a signature index. Its presence forces JWS JSON Serialization.
Read unprotected header GetUnprotectedH Returns the original unprotected header for the signature at the specified index.
Indexing rule: Header methods use a signature index. The first signature is index 0.

Signing and Validation Keys

Algorithm Family Signing / Creating Validation
HMAC: HS256, HS384, HS512 SetMacKey or SetMacKeyBd SetMacKey or SetMacKeyBd
RSA PKCS#1 v1.5: RS256, RS384, RS512 SetPrivateKey or SetSigningCert SetPublicKey
ECDSA: ES256, ES384, ES512 SetPrivateKey or SetSigningCert SetPublicKey
RSA-PSS: PS256, PS384, PS512 SetPrivateKey or SetSigningCert SetPublicKey
Certificate signing note: SetSigningCert uses the certificate’s private key for signing. The certificate must have access to its private key.

Supported JWS Algorithms

alg Algorithm Key Type
HS256 HMAC using SHA-256 Shared MAC key
HS384 HMAC using SHA-384 Shared MAC key
HS512 HMAC using SHA-512 Shared MAC key
RS256 RSASSA-PKCS1-v1_5 using SHA-256 RSA private/public key
RS384 RSASSA-PKCS1-v1_5 using SHA-384 RSA private/public key
RS512 RSASSA-PKCS1-v1_5 using SHA-512 RSA private/public key
ES256 ECDSA using P-256 and SHA-256 ECC private/public key
ES384 ECDSA using P-384 and SHA-384 ECC private/public key
ES512 ECDSA using P-521 and SHA-512 ECC private/public key
PS256 RSASSA-PSS using SHA-256 and MGF1 with SHA-256 RSA private/public key
PS384 RSASSA-PSS using SHA-384 and MGF1 with SHA-384 RSA private/public key
PS512 RSASSA-PSS using SHA-512 and MGF1 with SHA-512 RSA private/public key
none No digital signature or MAC performed No signing key

Validation Result Codes

Return Value Meaning Typical Cause
1 Signature or MAC validated successfully. The provided MAC key matches, or the public key corresponds to the signer’s private key.
0 Signature validation failed. The wrong public key or MAC key was provided, or the JWS content does not match the signature.
-1 Error. Missing key for the signature index, malformed input, or another validation error. Check LastErrorText.
Before validating: Provide the public key or MAC key using SetPublicKey, SetMacKey, or SetMacKeyBd before calling Validate.

Method Summary by Category

Category Methods Purpose
Create JWS CreateJws, CreateJwsSb Create a JWS from the previously set payload, headers, and signing keys.
Load JWS LoadJws, LoadJwsSb Load a JWS from a string or StringBuilder.
Payload SetPayload, SetPayloadSb, SetPayloadBd, GetPayload, GetPayloadSb, GetPayloadBd Set or retrieve text and binary payload data.
Headers SetProtectedHeader, SetUnprotectedHeader, GetProtectedH, GetUnprotectedH Configure or inspect protected and unprotected headers for each signature.
Signing keys SetPrivateKey, SetSigningCert, SetMacKey, SetMacKeyBd Provide key material for creating signatures or MACs.
Validation keys SetPublicKey, SetMacKey, SetMacKeyBd Provide key material for validating signatures or MACs.
Validate Validate Validates the Nth signature or MAC and returns 1, 0, or -1.

Diagnostics and Troubleshooting

Problem Area Member What to Check
JWS creation fails SetPayload, SetProtectedHeader, SetPrivateKey, SetMacKey, CreateJws Confirm the payload is set, the protected header has the expected alg, and the correct signing key was supplied for that algorithm.
Validation returns 0 Validate The signature did not validate. Check that the correct public key or MAC key was provided and that the JWS has not been altered.
Validation returns -1 Validate, LastErrorText A required key may be missing, the signature index may be invalid, or another error occurred. Check LastErrorText.
Unexpected JSON Serialization output PreferCompact, SetUnprotectedHeader Multiple signatures or any unprotected headers force JWS JSON Serialization.
Expected flattened JSON but got general JSON PreferFlattened Multiple signatures force general JWS JSON Serialization.
Payload text appears garbled SetPayload, GetPayload Use the correct charset when setting and retrieving text payloads, typically utf-8.
Binary payload is corrupted by text conversion SetPayloadBd, GetPayloadBd Use BinData methods for binary payloads instead of charset-based text methods.

Common Pitfalls

Pitfall Better Approach
Using a public key to create an RSA or ECDSA signature. Use SetPrivateKey or SetSigningCert to create signatures, and SetPublicKey to validate them.
Using different byte representations when signing and reading text payloads. Specify the correct charset consistently. For normal JSON/text payloads, utf-8 is typically used.
Including a BOM in the payload unintentionally. Set includeBom to false unless the payload specifically requires a byte-order mark.
Expecting compact serialization with multiple signatures. Multiple signatures require JWS JSON Serialization.
Expecting compact serialization when unprotected headers are present. Any unprotected header requires JWS JSON Serialization.
Calling Validate before setting a validation key. Call SetPublicKey, SetMacKey, or SetMacKeyBd first.
Using text payload methods for binary payloads. Use SetPayloadBd and GetPayloadBd for binary data.

Best Practices

Recommendation Reason
Set the protected header before creating the JWS. The protected header defines the signing algorithm and is covered by the signature.
Use the key-setting method that matches the alg value. HMAC algorithms use MAC keys, while RSA/ECDSA/RSA-PSS algorithms use private keys for signing and public keys for validation.
Use explicit charsets for text payloads. The charset determines the exact bytes being signed and the interpretation of payload bytes when reading.
Use BinData methods for binary payloads. Binary payloads should not be converted through a text charset.
Expect JSON Serialization for multi-signature or unprotected-header JWSs. Compact serialization is only used when the JWS structure allows it.
Check Validate return values carefully. 1 means valid, 0 means invalid signature or wrong key, and -1 means an error occurred.
Check LastErrorText after failures. It provides the most useful diagnostic detail for loading, payload handling, header setup, key setup, signing, and validation problems.

Summary

Chilkat.Jws is the Chilkat class for creating and validating JSON Web Signatures. It supports compact and JSON serialization, flattened and general JSON output, single and multiple signatures, protected and unprotected headers, text and binary payloads, HMAC signatures, RSA signatures, ECDSA signatures, and RSA-PSS signatures.

The most important practical guidance is to set the protected header and payload before creating the JWS, use the correct key method for the selected alg, use explicit charsets for text payloads, use BinData methods for binary payloads, and interpret Validate return values carefully.