Class KJUR.jws.JWS

JSON Web Signature(JWS) class
Defined in: jws-3.3.js.

Class Summary
Constructor Attributes	Constructor Name and Description
	KJUR.jws.JWS() JSON Web Signature(JWS) class.

Field Summary
Field Attributes	Field Name and Description
<static>	KJUR.jws.JWS.jwsalg2sigalg static associative array of general signature algorithm name from JWS algorithm name

Method Summary
Method Attributes	Method Name and Description
<static>	KJUR.jws.JWS.getEncodedSignatureValueFromJWS(sJWS) get Encoed Signature Value from JWS string.
<static>	KJUR.jws.JWS.getJWKthumbprint(o) get RFC 7638 JWK thumbprint from JWK object This method calculates JWK thmubprint for specified JWK object as described in RFC 7638.
<static>	KJUR.jws.JWS.inArray(item, a) check whether item is included by array
<static>	KJUR.jws.JWS.includedArray(a1, a2) check whether array is included by another array
<static>	KJUR.jws.JWS.isSafeJSONString(s) check whether a String "s" is a safe JSON string or not.
<static>	KJUR.jws.JWS.parse(sJWS) parse header and payload of JWS signature This method parses JWS signature string.
<static>	KJUR.jws.JWS.parseJWS(sJWS) parse JWS string and set public property 'parsedJWS' dictionary.
<static>	KJUR.jws.JWS.readSafeJSONString(s) read a String "s" as JSON object if it is safe.
<static>	KJUR.jws.JWS.sign(alg, spHead, spPayload, key, pass) generate JWS signature by specified key This method supports following algorithms.
<static>	KJUR.jws.JWS.verify(sJWS, key, acceptAlgs) verify JWS signature by specified key or certificate This method verifies a JSON Web Signature Compact Serialization string by the validation algorithm as described in the section 5 of Internet Draft draft-jones-json-web-signature-04.
<static>	KJUR.jws.JWS.verifyJWT(sJWT, key, acceptField) This method verifies a RFC 7519 JSON Web Token(JWT).

Class Detail

KJUR.jws.JWS()

JSON Web Signature(JWS) class.
This class provides JSON Web Signature(JWS)/JSON Web Token(JWT) signing and validation.

METHOD SUMMARY

Here is major methods of KJUR.jws.JWS class.

SIGN
KJUR.jws.JWS.sign - sign JWS
VERIFY
KJUR.jws.JWS.verify - verify JWS signature
KJUR.jws.JWS.verifyJWT - verify properties of JWT token at specified time
UTILITY
KJUR.jws.JWS.getJWKthumbprint - get RFC 7638 JWK thumbprint
KJUR.jws.JWS.isSafeJSONString - check whether safe JSON string or not
KJUR.jws.JWS.readSafeJSONString - read safe JSON string only

SUPPORTED SIGNATURE ALGORITHMS

Here is supported algorithm names for KJUR.jws.JWS.sign and KJUR.jws.JWS.verify methods.

alg value	spec requirement	jsjws support
HS256	REQUIRED	SUPPORTED
HS384	OPTIONAL	SUPPORTED
HS512	OPTIONAL	SUPPORTED
RS256	RECOMMENDED	SUPPORTED
RS384	OPTIONAL	SUPPORTED
RS512	OPTIONAL	SUPPORTED
ES256	RECOMMENDED+	SUPPORTED
ES384	OPTIONAL	SUPPORTED
ES512	OPTIONAL	-
PS256	OPTIONAL	SUPPORTED
PS384	OPTIONAL	SUPPORTED
PS512	OPTIONAL	SUPPORTED
none	REQUIRED	SUPPORTED(signature generation only)

NOTE1

HS384 is supported since jsjws 3.0.2 with jsrsasign 4.1.4.

NOTE2

Some deprecated methods have been removed since jws 3.3 of jsrsasign 4.10.0. Removed methods are following:

JWS.verifyJWSByNE
JWS.verifyJWSByKey
JWS.generateJWSByNED
JWS.generateJWSByKey
JWS.generateJWSByP1PrvKey

EXAMPLE

// JWS signing 
sJWS = KJUR.jws.JWS.sign(null, '{"alg":"HS256", "cty":"JWT"}', '{"age": 21}', {"utf8": "password"});
// JWS validation
isValid = KJUR.jws.JWS.verify('eyJjdHkiOiJKV1QiLCJhbGc...', {"utf8": "password"});
// JWT validation
isValid = KJUR.jws.JWS.verifyJWT('eyJh...', {"utf8": "password"}, {
  alg: ['HS256', 'HS384'],
  iss: ['http://foo.com']
});

Since:: jsjws 1.0

See:: 'jwjws'(JWS JavaScript Library) home page https://kjur.github.io/jsjws/; 'jwrsasign'(RSA Sign JavaScript Library) home page https://kjur.github.io/jsrsasign/; IETF I-D JSON Web Algorithms (JWA)

Field Detail

<static> KJUR.jws.JWS.jwsalg2sigalg

static associative array of general signature algorithm name from JWS algorithm name

Since:: jws 3.0.0

Method Detail

<static> {String} KJUR.jws.JWS.getEncodedSignatureValueFromJWS(sJWS)

get Encoed Signature Value from JWS string.

Parameters:
{String} sJWS: JWS signature string to be verified

Throws:
: if sJWS is not comma separated string such like "Header.Payload.Signature".

Returns:: {String} string of Encoded Signature Value

<static> {String} KJUR.jws.JWS.getJWKthumbprint(o)

get RFC 7638 JWK thumbprint from JWK object This method calculates JWK thmubprint for specified JWK object as described in RFC 7638. It supports all type of "kty". (i.e. "RSA", "EC" and "oct" (for symmetric key)) Working sample is here.

jwk = {"kty":"RSA", "n":"0vx...", "e":"AQAB", ...};
thumbprint = KJUR.jws.JWS.getJWKthumbprint(jwk);

Parameters:
{Object} o: JWK object to be calculated thumbprint

Since:: jsrsasign 5.0.2 jws 3.3.2

Returns:: {String} Base64 URL encoded JWK thumbprint value

<static> {Boolean} KJUR.jws.JWS.inArray(item, a)

check whether item is included by array

KJUR.jws.JWS.inArray('b', ['b', 'c', 'a']) => true
KJUR.jws.JWS.inArray('a', ['b', 'c', 'a']) => true
KJUR.jws.JWS.inArray('a', ['b', 'c']) => false

Parameters:
{String} item: check whether item is included by array
{Array} a: check whether item is included by array

Since:: jws 3.2.3 This method verifies whether an item is included by an array. It doesn't care about item ordering in an array.

Returns:: {Boolean} check whether item is included by array

<static> {Boolean} KJUR.jws.JWS.includedArray(a1, a2)

check whether array is included by another array

KJUR.jws.JWS.includedArray(['b'], ['b', 'c', 'a']) => true
KJUR.jws.JWS.includedArray(['a', 'b'], ['b', 'c', 'a']) => true
KJUR.jws.JWS.includedArray(['a', 'b'], ['b', 'c']) => false

Parameters:
{Array} a1: check whether set a1 is included by a2
{Array} a2: check whether set a1 is included by a2

Since:: jws 3.2.3 This method verifies whether an array is included by another array. It doesn't care about item ordering in a array.

Returns:: {Boolean} check whether set a1 is included by a2

<static> {Number} KJUR.jws.JWS.isSafeJSONString(s)

check whether a String "s" is a safe JSON string or not.
If a String "s" is a malformed JSON string or an other object type this returns 0, otherwise this returns 1.

Parameters:
{String} s: JSON string

Returns:: {Number} 1 or 0

<static> {Array} KJUR.jws.JWS.parse(sJWS)

parse header and payload of JWS signature
This method parses JWS signature string. Resulted associative array has following properties:

headerObj - JSON object of header
payloadObj - JSON object of payload if payload is JSON string otherwise undefined
headerPP - pretty printed JSON header by stringify
payloadPP - pretty printed JSON payload by stringify if payload is JSON otherwise Base64URL decoded raw string of payload
sigHex - hexadecimal string of signature

KJUR.jws.JWS.parse(sJWS) ->
{ 
  headerObj: {"alg": "RS256", "typ": "JWS"},
  payloadObj: {"product": "orange", "quantity": 100},
  headerPP: 
  '{
    "alg": "RS256",
    "typ": "JWS"
  }',
  payloadPP: 
  '{
    "product": "orange",
    "quantity": 100
  }',
  sigHex: "91f3cd..." 
}

Parameters:
{String} sJWS: string of JWS signature to parse

Since:: jws 3.3.3

Throws:
: if sJWS is malformed JWS signature

Returns:: {Array} associative array of parsed header and payload. See below.

<static> KJUR.jws.JWS.parseJWS(sJWS)

parse JWS string and set public property 'parsedJWS' dictionary.

Parameters:
{String} sJWS: JWS signature string to be parsed.

Since:: jws 1.1

Throws:
: if sJWS is not comma separated string such like "Header.Payload.Signature".
: if JWS Header is a malformed JSON string.

<static> {Object} KJUR.jws.JWS.readSafeJSONString(s)

read a String "s" as JSON object if it is safe.
If a String "s" is a malformed JSON string or not JSON string, this returns null, otherwise returns JSON object.

Parameters:
{String} s: JSON string

Since:: 1.1.1

Returns:: {Object} JSON object or null

<static> {String} KJUR.jws.JWS.sign(alg, spHead, spPayload, key, pass)

generate JWS signature by specified key
This method supports following algorithms.

alg value	spec requirement	jsjws support
HS256	REQUIRED	SUPPORTED
HS384	OPTIONAL	SUPPORTED
HS512	OPTIONAL	SUPPORTED
RS256	RECOMMENDED	SUPPORTED
RS384	OPTIONAL	SUPPORTED
RS512	OPTIONAL	SUPPORTED
ES256	RECOMMENDED+	SUPPORTED
ES384	OPTIONAL	SUPPORTED
ES512	OPTIONAL	-
PS256	OPTIONAL	SUPPORTED
PS384	OPTIONAL	SUPPORTED
PS512	OPTIONAL	SUPPORTED
none	REQUIRED	SUPPORTED(signature generation only)

NOTE1:: salt length of RSAPSS signature is the same as the hash algorithm length because of IETF JOSE ML discussion.
NOTE2:: To support HS384, patched version of CryptoJS is used. See here for detail.
NOTE3: From jsrsasign 4.10.0 jws 3.3.0, Way to provide password for HS* algorithm is changed. The 'key' attribute value is passed to KJUR.crypto.Mac.setPassword so please see KJUR.crypto.Mac.setPassword for detail. As for backword compatibility, if key is a string, has even length and 0..9, A-F or a-f characters, key string is treated as a hexadecimal otherwise it is treated as a raw string.

EXAMPLE

// sign HS256 signature with password "aaa" implicitly handled as string
sJWS = KJUR.jws.JWS.sign(null, {alg: "HS256", cty: "JWT"}, {age: 21}, "aaa");
// sign HS256 signature with password "6161" implicitly handled as hex
sJWS = KJUR.jws.JWS.sign(null, {alg: "HS256", cty: "JWT"}, {age: 21}, "6161");
// sign HS256 signature with base64 password
sJWS = KJUR.jws.JWS.sign(null, {alg: "HS256"}, {age: 21}, {b64: "Mi/8..a="});
// sign RS256 signature with PKCS#8 PEM RSA private key
sJWS = KJUR.jws.JWS.sign(null, {alg: "RS256"}, {age: 21}, "-----BEGIN PRIVATE KEY...");
// sign RS256 signature with PKCS#8 PEM ECC private key with passcode
sJWS = KJUR.jws.JWS.sign(null, {alg: "ES256"}, {age: 21}, 
                         "-----BEGIN PRIVATE KEY...", "keypass");
// header and payload can be passed by both string and object
sJWS = KJUR.jws.JWS.sign(null, '{alg:"HS256",cty:"JWT"}', '{age:21}', "aaa");

Parameters:
{String} alg: JWS algorithm name to sign and force set to sHead or null
{String} spHead: string or object of JWS Header
{String} spPayload: string or object of JWS Payload
{String} key: string of private key or mac key object to sign
{String} pass: (OPTION)passcode to use encrypted asymmetric private key

Since:: jws 3.0.0

Returns:: {String} JWS signature string

See:: jsrsasign KJUR.crypto.Signature method; jsrsasign KJUR.crypto.Mac method

<static> {Boolean} KJUR.jws.JWS.verify(sJWS, key, acceptAlgs)

verify JWS signature by specified key or certificate

This method verifies a JSON Web Signature Compact Serialization string by the validation algorithm as described in the section 5 of Internet Draft draft-jones-json-web-signature-04.

Since 3.2.0 strict key checking has been provided against a JWS algorithm in a JWS header.

In case 'alg' is 'HS*' in the JWS header, 'key' shall be hexadecimal string for Hmac{256,384,512} shared secret key. Otherwise it raise an error.
In case 'alg' is 'RS*' or 'PS*' in the JWS header, 'key' shall be a RSAKey object or a PEM string of X.509 RSA public key certificate or PKCS#8 RSA public key. Otherwise it raise an error.
In case 'alg' is 'ES*' in the JWS header, 'key' shall be a KJUR.crypto.ECDSA object or a PEM string of X.509 ECC public key certificate or PKCS#8 ECC public key. Otherwise it raise an error.
In case 'alg' is 'none' in the JWS header, validation not supported after jsjws 3.1.0.

NOTE1: The argument 'acceptAlgs' is supported since 3.2.0. Strongly recommended to provide acceptAlgs to mitigate signature replacement attacks.

NOTE2: From jsrsasign 4.9.0 jws 3.2.5, Way to provide password for HS* algorithm is changed. The 'key' attribute value is passed to KJUR.crypto.Mac.setPassword so please see KJUR.crypto.Mac.setPassword for detail. As for backword compatibility, if key is a string, has even length and 0..9, A-F or a-f characters, key string is treated as a hexadecimal otherwise it is treated as a raw string.

// 1) verify a RS256 JWS signature by a certificate string.
isValid = KJUR.jws.JWS.verify('eyJh...', '-----BEGIN...', ['RS256']);

// 2) verify a HS256 JWS signature by a certificate string.
isValid = KJUR.jws.JWS.verify('eyJh...', {hex: '6f62ad...'}, ['HS256']);
isValid = KJUR.jws.JWS.verify('eyJh...', {b64: 'Mi/ab8...a=='}, ['HS256']);
isValid = KJUR.jws.JWS.verify('eyJh...', {utf8: 'Secret秘密'}, ['HS256']);
isValid = KJUR.jws.JWS.verify('eyJh...', '6f62ad', ['HS256']); // implicit hex
isValid = KJUR.jws.JWS.verify('eyJh...', '6f62ada', ['HS256']); // implicit raw string

// 3) verify a ES256 JWS signature by a KJUR.crypto.ECDSA key object.
var pubkey = KEYUTIL.getKey('-----BEGIN CERT...');
var isValid = KJUR.jws.JWS.verify('eyJh...', pubkey);

Parameters:
{String} sJWS: string of JWS signature to verify
{Object} key: string of public key, certificate or key object to verify
{String} acceptAlgs: array of algorithm name strings (OPTION)

Since:: jws 3.0.0

Returns:: {Boolean} true if the signature is valid otherwise false including no signature case or without head and payload

See:: jsrsasign KJUR.crypto.Signature method; jsrsasign KJUR.crypto.Mac method

<static> {Boolean} KJUR.jws.JWS.verifyJWT(sJWT, key, acceptField)

This method verifies a RFC 7519 JSON Web Token(JWT). It will verify following:

Header.alg
- alg is specified in JWT header.
- alg is included in acceptField.alg array. (MANDATORY)
- alg is proper for key.
Payload.iss (issuer) - Payload.iss is included in acceptField.iss array if specified. (OPTION)
Payload.sub (subject) - Payload.sub is included in acceptField.sub array if specified. (OPTION)
Payload.aud (audience) - Payload.aud is included in acceptField.aud array or the same as value if specified. (OPTION)
Time validity
- If acceptField.verifyAt as number of UNIX origin time is specifed for validation time, this method will verify at the time for it, otherwise current time will be used to verify.
- Clock of JWT generator or verifier can be fast or slow. If these clocks are very different, JWT validation may fail. To avoid such case, 'jsrsasign' supports 'acceptField.gracePeriod' parameter which specifies acceptable time difference of those clocks in seconds. So if you want to accept slow or fast in 2 hours, you can specify acceptField.gracePeriod = 2 * 60 * 60;. "gracePeriod" is zero by default. "gracePeriod" is supported since jsrsasign 5.0.12.
- Payload.exp (expire) - Validation time is smaller than Payload.exp + gracePeriod.
- Payload.nbf (not before) - Validation time is greater than Payload.nbf - gracePeriod.
- Payload.iat (issued at) - Validation time is greater than Payload.iat - gracePeriod.
Payload.jti (JWT id) - Payload.jti is included in acceptField.jti if specified. (OPTION)
JWS signature of JWS is valid for specified key.

acceptField parameters

Here is available acceptField argument parameters:

alg - array of acceptable signature algorithm names (ex. ["HS256", "HS384"])
iss - array of acceptable issuer names (ex. ['http://foo.com'])
sub - array of acceptable subject names (ex. ['mailto:john@foo.com'])
aud - array of acceptable audience name (ex. ['http://foo.com'])
jti - string of acceptable JWT ID (OPTION) (ex. 'id1234')
verifyAt - time to verify 'nbf', 'iat' and 'exp' in UNIX seconds (OPTION) (ex. 1377663900). If this is not specified, current time of verifier will be used. KJUR.jws.IntDate may be useful to specify it.
gracePeriod - acceptable time difference between signer and verifier in seconds (ex. 3600). If this is not specified, zero will be used.

// simple validation for HS256
isValid = KJUR.jws.JWS.verifyJWT("eyJhbG...", "616161", {alg: ["HS256"]}),

// full validation for RS or PS
pubkey = KEYUTIL.getKey('-----BEGIN CERT...');
isValid = KJUR.jws.JWS.verifyJWT('eyJh...', pubkey, {
  alg: ['RS256', 'RS512', 'PS256', 'PS512'],
  iss: ['http://foo.com'],
  sub: ['mailto:john@foo.com', 'mailto:alice@foo.com'],
  verifyAt: KJUR.jws.IntDate.get('20150520235959Z'),
  aud: ['http://foo.com'], // aud: 'http://foo.com' is fine too.
  jti: 'id123456',
  gracePeriod: 1 * 60 * 60 // accept 1 hour slow or fast
});

Parameters:
{String} sJWT: string of JSON Web Token(JWT) to verify
{Object} key: string of public key, certificate or key object to verify
{Array} acceptField: associative array of acceptable fields (OPTION)

Since:: jws 3.2.3 jsrsasign 4.8.0

Returns:: {Boolean} true if the JWT token is valid otherwise false

Classes

Class KJUR.jws.JWS

METHOD SUMMARY

SUPPORTED SIGNATURE ALGORITHMS

acceptField parameters