Class Index | File Index

Classes


Class KJUR.jws.JWS

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

Class Summary
Constructor Attributes Constructor Name and Description
 
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>  
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.

SUPPORTED SIGNATURE ALGORITHMS

Here is supported algorithm names for KJUR.jws.JWS.sign and KJUR.jws.JWS.verify methods.
alg valuespec requirementjsjws support
HS256REQUIREDSUPPORTED
HS384OPTIONALSUPPORTED
HS512OPTIONALSUPPORTED
RS256RECOMMENDEDSUPPORTED
RS384OPTIONALSUPPORTED
RS512OPTIONALSUPPORTED
ES256RECOMMENDED+SUPPORTED
ES384OPTIONALSUPPORTED
ES512OPTIONAL-
PS256OPTIONALSUPPORTED
PS384OPTIONALSUPPORTED
PS512OPTIONALSUPPORTED
noneREQUIREDSUPPORTED(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:
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 valuespec requirementjsjws support
HS256REQUIREDSUPPORTED
HS384OPTIONALSUPPORTED
HS512OPTIONALSUPPORTED
RS256RECOMMENDEDSUPPORTED
RS384OPTIONALSUPPORTED
RS512OPTIONALSUPPORTED
ES256RECOMMENDED+SUPPORTED
ES384OPTIONALSUPPORTED
ES512OPTIONAL-
PS256OPTIONALSUPPORTED
PS384OPTIONALSUPPORTED
PS512OPTIONALSUPPORTED
noneREQUIREDSUPPORTED(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.

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:

acceptField parameters

Here is available acceptField argument parameters:
// 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

© 2012-2023 Kenji Urushima, All rights reserved
Documentation generated by JsDoc Toolkit 2.4.0