Jws ActiveX Reference Documentation
Jws
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
Note: For a specific major version, use "Chilkat.Jws.<major_version>", such as "Chilkat.Jws.10" for Chilkat v10.*.* See Chilkat ActiveX Object Creation (ASP) set obj = Server.CreateObject("Chilkat.Jws") (AutoIt) $obj = ObjCreate("Chilkat.Jws") (Visual Basic 6.0) Dim obj As New ChilkatJws (VBScript) set obj = CreateObject("Chilkat.Jws") (VBA, such as Excel) Dim obj As New ChilkatJws See How to Use ActiveX in Excel (Delphi) obj := TChilkatJws.Create(Self); (FoxPro) loObject = CreateObject('Chilkat.Jws') (PowerBuilder) lole_object = create oleobject li_rc = lole_object.ConnectToNewObject("Chilkat.Jws") (SQL Server) EXEC @hr = sp_OACreate 'Chilkat.Jws', @obj OUT (Javascript) var obj = new ActiveXObject("Chilkat.Jws");
Properties
DebugLogFilePath
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.
LastBinaryResult
This property is mainly used in SQL Server stored procedures to retrieve binary data from the last method call that returned binary data. It is only accessible if Chilkat.Global.KeepBinaryResult is set to 1. This feature allows for the retrieval of large varbinary results in an SQL Server environment, which has restrictions on returning large data via method calls, though temp tables can handle binary properties.
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
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
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
Indicates the success or failure of the most recent method call: 1 means success, 0 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.
LastStringResult
In SQL Server stored procedures, this property holds the string return value of the most recent method call that returns a string. It is accessible only when Chilkat.Global.KeepStringResult is set to TRUE. SQL Server has limitations on string lengths returned from methods and properties, but temp tables can be used to access large strings.
LastStringResultLen
The length, in characters, of the string contained in the LastStringResult property.
topNumSignatures
Returns the number of signatures currently represented by this object.
After loading a JWS, this is the number of signatures found in the serialization. During JWS creation, it reflects the configured signature indexes. Compact and flattened JSON serializations contain one signature; general JWS JSON Serialization can contain one or more.
topPreferCompact
Controls whether Chilkat prefers JWS Compact Serialization when creating a JWS. The default is 1
| Setting | Behavior when permitted |
|---|---|
| Use the compact form protected.payload.signature. |
| Use JWS JSON Serialization, with PreferFlattened selecting flattened or general form when possible. |
Compact Serialization is possible only for a single signature and has no unprotected-header member. If multiple signatures or any unprotected header is configured, Chilkat uses JWS JSON Serialization regardless of this property.
PreferFlattened
Controls whether Chilkat prefers flattened JWS JSON Serialization when JSON serialization is used. The default is 1
| Setting | Behavior for one signature |
|---|---|
| Use flattened JSON, placing protected, header, and signature directly in the top-level object. |
| Use general JSON, placing signature objects in the top-level signatures array. |
When more than one signature exists, general JWS JSON Serialization is required and this preference is ignored. This property has no effect when Compact Serialization is selected.
topUncommonOptions
Provides a catch-all string for specialized compatibility options that are not exposed as ordinary properties. The default is an empty string, which is appropriate for normal use.
VerboseLogging
If set to 1, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. The default value is 0. Verbose logging should only be used for debugging. The potentially large quantity of logged information may adversely affect peformance.
Version
Version of the component/library, such as "10.1.0"
Methods
CreateJws
Creates and returns a JWS from the payload, headers, and signing or MAC keys previously configured on this object. The result contains one signature for each configured signature index.
The serialization format is selected by PreferCompact and PreferFlattened, subject to the structural requirements of JWS: Compact Serialization can contain only one signature and no unprotected header; flattened JSON can contain only one signature; general JSON is used for multiple signatures.
alg value for each signature, and provide the matching MAC key, private key, or signing certificate before calling this method.Returns Nothing on failure
CreateJwsSb
Creates a JWS from the payload, headers, and keys previously configured on this object and appends the serialized JWS to sbJws.
The same serialization-selection rules as CreateJws apply. Existing text in the destination StringBuilder is preserved because the new JWS is appended rather than replacing it.
1LastErrorText for missing headers, keys, payload state, or an unsupported key/algorithm combination.Returns 1 for success, 0 for failure.
topGetPayload
Returns the loaded JWS payload as text by interpreting the payload bytes using the character encoding named by charset, such as utf-8, windows-1252, or utf-16.
If the payload is binary or its text encoding is unknown, use GetPayloadBd to retrieve the exact bytes.
Validate returns 1 for every signature required by the application.Returns Nothing on failure
GetPayloadBd
Appends the exact payload bytes from the loaded JWS to binData. Existing bytes in the destination BinData are preserved.
This method performs no character-set conversion and is therefore appropriate for binary payloads or when the original payload bytes must be retained exactly.
Validate returns 1 for the signature or signatures required by the application.Returns 1 for success, 0 for failure.
topGetPayloadSb
Interprets the loaded JWS payload bytes using the character encoding named by charset and appends the resulting text to sbPayload. Existing text in the destination StringBuilder is preserved.
Use the same charset that was used to create the payload. If the payload is binary or its encoding is unknown, use GetPayloadBd instead.
Validate returns 1 for the required signature or signatures.Returns 1 for success, 0 for failure.
topGetProtectedH
Loads json with the decoded protected header of signature index. Signature indexes are zero-based; index 0 is the first signature.
The returned JSON is the header object obtained after base64url decoding the JWS protected-header value. The original encoded representation remains part of the signing input.
Returns 1 for success, 0 for failure.
topGetUnprotectedH
Loads json with the optional unprotected header of signature index. Signature indexes are zero-based; index 0 is the first signature.
Unprotected headers exist only in JWS JSON Serialization. An absent unprotected header and an invalid signature are separate conditions; retrieving this JSON does not perform signature validation.
Returns 1 for success, 0 for failure.
topLoadJws
Loads and parses a serialized JWS from jwsStr, making its payload, protected and unprotected headers, and signatures available to the other methods and properties of this object.
Compact Serialization, flattened JWS JSON Serialization, and general JWS JSON Serialization are accepted when structurally valid.
Validate before trusting any loaded content.Returns 1 for success, 0 for failure.
LoadJwsSb
Loads and parses a serialized JWS from the current contents of sbJws, making its payload, protected and unprotected headers, and signatures available to the other methods and properties of this object.
Compact Serialization, flattened JWS JSON Serialization, and general JWS JSON Serialization are accepted when structurally valid.
Validate before trusting any loaded content.Returns 1 for success, 0 for failure.
SetMacKey
Sets the symmetric MAC key for creating or validating signature index when its alg value is HS256, HS384, or HS512. Signature indexes are zero-based.
key contains an encoded representation of the key bytes. encoding names that representation, such as base64url, base64, or hex. This argument describes binary-to-text encoding; it is not a character set and the key should not be passed as an ordinary human-readable password unless the protocol explicitly defines how that password is converted to key bytes.
alg | Minimum recommended key size |
|---|---|
HS256 | 256 bits (32 bytes) |
HS384 | 384 bits (48 bytes) |
HS512 | 512 bits (64 bytes) |
Returns 1 for success, 0 for failure.
SetMacKeyBd
Sets the symmetric MAC key for creating or validating signature index when its alg value is HS256, HS384, or HS512. Signature indexes are zero-based, and key supplies the key as raw bytes.
alg | Minimum recommended key size |
|---|---|
HS256 | 256 bits (32 bytes) |
HS384 | 384 bits (48 bytes) |
HS512 | 512 bits (64 bytes) |
Returns 1 for success, 0 for failure.
topSetPayload
Sets the JWS payload from payload. charset names the character encoding used to convert the string to payload bytes, such as utf-8, windows-1252, or utf-16.
If includeBom is 1includeBom should be 0
Returns 1 for success, 0 for failure.
SetPayloadBd
Sets the JWS payload to the binary bytes currently contained in binData. Use this method when the payload is not text or when the application must preserve an exact byte sequence without character-set conversion.
Returns 1 for success, 0 for failure.
topSetPayloadSb
Sets the JWS payload from the current contents of sbPayload. charset names the character encoding used to convert the string to payload bytes, such as utf-8, windows-1252, or utf-16.
If includeBom is 1includeBom should be 0
Returns 1 for success, 0 for failure.
topSetPrivateKey
Sets the private key used to create signature index. Signature indexes are zero-based. The key type and parameters must match the alg value in that signature's JOSE header.
| Algorithms | Required key |
|---|---|
RS256, RS384, RS512 | RSA; RSASSA-PKCS1-v1_5 with the corresponding SHA-2 hash. |
PS256, PS384, PS512 | RSA; RSASSA-PSS with the corresponding SHA-2 hash and MGF1. |
ES256 | EC key on curve P-256. |
ES384 | EC key on curve P-384. |
ES512 | EC key on curve P-521, used with SHA-512. |
This method is for RSA and ECDSA signatures. Use SetMacKey or SetMacKeyBd for the HS* algorithms.
R and S integers, not as an ASN.1 DER SEQUENCE. Chilkat performs this JOSE-specific formatting automatically.alg value alone to determine what algorithms the application is willing to accept.Returns 1 for success, 0 for failure.
topSetProtectedHeader
Sets the protected header for the signature at index. Signature indexes are zero-based; index 0 is the first and, for a typical single-signature JWS, the only signature.
The supplied JsonObject contains JOSE header parameters such as alg, kid, typ, cty, or crit. When the JWS is created, this JSON is serialized, UTF-8 encoded, and base64url encoded. The encoded protected header becomes part of the JWS Signing Input and is therefore covered by the signature or MAC.
alg and any parameter used to select a verification key or processing rule—in the protected header. A parameter name must not appear in both the protected and unprotected headers for the same signature.Returns 1 for success, 0 for failure.
SetPublicKey
Sets the public key used to validate signature index. Signature indexes are zero-based. The key type and parameters must match the signature's alg value.
| Algorithms | Required key |
|---|---|
RS256, RS384, RS512 | RSA; RSASSA-PKCS1-v1_5 with the corresponding SHA-2 hash. |
PS256, PS384, PS512 | RSA; RSASSA-PSS with the corresponding SHA-2 hash and MGF1. |
ES256 | EC key on curve P-256. |
ES384 | EC key on curve P-384. |
ES512 | EC key on curve P-521, used with SHA-512. |
This method is for RSA and ECDSA verification. Use SetMacKey or SetMacKeyBd for HMAC verification.
pubKey from a trusted configuration or a securely validated key-distribution mechanism. Do not blindly trust a jwk, jku, x5c, x5u, or kid value supplied by the same unverified JWS.Returns 1 for success, 0 for failure.
topSetSigningCert
Sets the certificate whose associated private key will be used to create signature index. Signature indexes are zero-based. The certificate must have an accessible RSA or EC private key, and that key must match the signature's alg value.
| Algorithms | Required key |
|---|---|
RS256, RS384, RS512 | RSA; RSASSA-PKCS1-v1_5 with the corresponding SHA-2 hash. |
PS256, PS384, PS512 | RSA; RSASSA-PSS with the corresponding SHA-2 hash and MGF1. |
ES256 | EC key on curve P-256. |
ES384 | EC key on curve P-384. |
ES512 | EC key on curve P-521, used with SHA-512. |
This method is convenient when the private key is associated with a certificate in an operating-system store, smart card, hardware token, or other key provider. It selects the private key for signing; applications should separately add any required x5c, x5t, x5t#S256, or related certificate header parameters to the appropriate protected header.
Returns 1 for success, 0 for failure.
topSetUnprotectedHeader
Sets the optional unprotected header for the signature at index. Signature indexes are zero-based; index 0 is the first signature.
An unprotected header is available only in JWS JSON Serialization. Its members are transmitted as ordinary JSON and are not included in the JWS Signing Input. Consequently, setting an unprotected header prevents Compact Serialization from being used, regardless of PreferCompact.
alg, trusted key-selection data, or other security decisions here unless the surrounding protocol independently protects and validates them. A parameter name must not also appear in the protected header for the same signature.Returns 1 for success, 0 for failure.
topValidate
Validates signature index using the public key or MAC key configured for that same zero-based signature index.
| Return value | Meaning |
|---|---|
1 | The signature or MAC is valid for the loaded payload and protected header using the supplied key. |
0 | Cryptographic validation completed, but the signature or MAC did not match. This commonly indicates the wrong key or modified signed content. |
-1 | Validation could not be performed because of an error, such as a missing key, invalid index, malformed JWS, unsupported algorithm, or incompatible key type. Inspect LastErrorText. |
Before calling this method, set the appropriate verification key with SetPublicKey, SetMacKey, or SetMacKeyBd.
Deprecated
GetProtectedHeader
Deprecated. Use GetProtectedH instead.
Returns a JsonObject containing the decoded protected header for the signature at index. Signature indexes are zero-based.
Returns Nothing on failure
GetUnprotectedHeader
Deprecated. Use GetUnprotectedH instead.
Returns a JsonObject containing the optional unprotected header for the signature at index. Signature indexes are zero-based.
Returns Nothing on failure