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.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.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.

Supported 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}', "password");
// JWS validation
isValid = KJUR.jws.JWS.verify('eyJjdHkiOiJKV1QiLCJhbGc...', "password");
// JWT validation
isValid = KJUR.jws.JWS.verifyJWT('eyJh...', "password", {
  alg: ['HS256', 'HS384'],
  iss: ['http://foo.com']
});

Since:: jsjws 1.0

See:: 'jwjws'(JWS JavaScript Library) home page http://kjur.github.com/jsjws/; 'jwrsasign'(RSA Sign JavaScript Library) home page http://kjur.github.com/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> {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> 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

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.
- Payload.exp (expire) - Validation time is smaller than Payloead.exp.
- Payload.nbf (not before) - Validation time is greater than Payloead.nbf.
- Payload.iat (issued at) - Validation time is greater than Payloead.iat.
Payload.jti (JWT id) - Payload.jti is included in acceptField.jti if specified. (OPTION)
JWS signature of JWS is valid for specified key.

// 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'
});

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

Supported Algorithms