Class JWS

• TopLevel.Object
  • dw.crypto.JWS

This class represents a JSON Web Signature (JWS) object.

Note: this class handles sensitive security-related data. Pay special attention to PCI DSS v3 requirements 2, 4, and 12.

Property Summary 

Property	Description
algorithm: String (read-only)	Get the algorithm (alg) from the header.
header: JWSHeader (read-only)	Get a copy of the JWS header.
headerMap: Map (read-only)	Get a copy of the JWS header as a Map.
payload: String (read-only)	Get the payload from this object.

Constructor Summary 

Constructor	Description
JWS(JWSHeader, String)	Construct a new JWS for signing.
JWS(JWSHeader, Bytes)	Construct a new JWS for signing.

Method Summary 

Method	Description
getAlgorithm()	Get the algorithm (alg) from the header.
getHeader()	Get a copy of the JWS header.
getHeaderMap()	Get a copy of the JWS header as a Map.
getPayload()	Get the payload from this object.
static parse(String)	Parse a JSON Web Signature (JWS) object from its compact serialization format.
static parse(String, Bytes)	Parse a JSON Web Signature (JWS) object from its compact serialization format.
static parse(String, String)	Parse a JSON Web Signature (JWS) object from its compact serialization format.
serialize(Boolean)	Get this JWS in compact serialization form.
sign(KeyRef)	Sign the payload using the given private key.
verify(CertificateRef)	Verifies the signature of the payload.

Methods inherited from class Object 

assign, create, create, defineProperties, defineProperty, entries, freeze, fromEntries, getOwnPropertyDescriptor, getOwnPropertyNames, getOwnPropertySymbols, getPrototypeOf, hasOwnProperty, is, isExtensible, isFrozen, isPrototypeOf, isSealed, keys, preventExtensions, propertyIsEnumerable, seal, setPrototypeOf, toLocaleString, toString, valueOf, values

Property Details 

algorithm 

algorithm: String (read-only)

Get the algorithm (alg) from the header.

---

header 

header: JWSHeader (read-only)

Get a copy of the JWS header.

---

headerMap 

headerMap: Map (read-only)

Get a copy of the JWS header as a Map.

---

payload 

payload: String (read-only)

Get the payload from this object.

This is available even if the signature has not been verified.

---

Constructor Details 

JWS(JWSHeader, String) 

JWS(header: JWSHeader, payload: String)

Construct a new JWS for signing.

Parameters:

• header - JWS header. This must include a valid algorithm (alg). See verify(CertificateRef) for a list of supported algorithms.
• payload - Content that will be signed.

---

JWS(JWSHeader, Bytes) 

JWS(header: JWSHeader, payload: Bytes)

Construct a new JWS for signing.

Parameters:

• header - JWS header. This must include a valid algorithm (alg). See verify(CertificateRef) for a list of supported algorithms.
• payload - Content that will be signed.

---

Method Details 

getAlgorithm() 

getAlgorithm(): String

Get the algorithm (alg) from the header.

Returns:

• Value of the algorithm or null if missing.

---

getHeader() 

getHeader(): JWSHeader

Get a copy of the JWS header.

Returns:

• Copy of the JWS header.

---

getHeaderMap() 

getHeaderMap(): Map

Get a copy of the JWS header as a Map.

Returns:

• Copy of the JWS header.

---

getPayload() 

getPayload(): String

Get the payload from this object.

This is available even if the signature has not been verified.

Returns:

• UTF-8 encoded payload.

---

parse(String) 

static parse(jws: String): JWS

Parse a JSON Web Signature (JWS) object from its compact serialization format.

Parameters:

• jws - JWS in compact serialization format.

Returns:

• JWS object.

---

parse(String, Bytes) 

static parse(jws: String, payload: Bytes): JWS

Parse a JSON Web Signature (JWS) object from its compact serialization format.

Parameters:

• jws - JWS without a payload in compact serialization format.
• payload - Detached payload

Returns:

• JWS object.

---

parse(String, String) 

static parse(jws: String, payload: String): JWS

Parse a JSON Web Signature (JWS) object from its compact serialization format.

Parameters:

• jws - JWS without a payload in compact serialization format.
• payload - Detached payload

Returns:

• JWS object.

---

serialize(Boolean) 

serialize(detachPayload: Boolean): String

Get this JWS in compact serialization form.

Parameters:

• detachPayload - true for a detached payload compliant with RFC-7797, or false to serialize the payload too.

Returns:

• Compact serialized object.

---

sign(KeyRef) 

sign(keyRef: KeyRef): void

Sign the payload using the given private key.

The key type and size must match the algorithm given in the JWS header.

Parameters:

• keyRef - Reference to the private key.

Throws:

• Exception - if there is an error while signing the payload.

---

verify(CertificateRef) 

verify(certificateRef: CertificateRef): Boolean

Verifies the signature of the payload.

If the x5c header parameter is present, then that certificate chain will be used to verify the signature and the given certificateRef must be its root certificate. If this parameter is not present then the given certificateRef will be used to directly verify the signature.

The following algorithms are supported:

• ES256
• ES256K
• ES384
• ES512
• RS256
• RS384
• RS512
• PS256
• PS384
• PS512

Parameters:

• certificateRef - Reference to the certificate to use for verification.

Returns:

• a boolean indicating success (true) or failure (false).

Throws:

• Exception - if there is an error while processing the certificate (for example if the x5c is not signed by the given certificate) or the algorithm is unsupported.

---