Class KJUR.jws.JWS

JSON Web Signature(JWS) class
Defined in: jws-3.2.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
	parsedJWS This property is set after JWS signature verification.
	parsedJWS_headB64U string of Encrypted JWS Header
	parsedJWS_headS string of decoded JWS Header
	parsedJWS_payloadB64U string of Encrypted JWS Payload
	parsedJWS_si string of Signature Input
	parsedJWS_sigvalB64U string of Encrypted JWS signature value
	parsedJWS_sigvalBI BigInteger(defined in jsbn.js) object of JWS signature value
	parsedJWS_sigvalH hexadecimal string of JWS signature value

Method Summary
Method Attributes	Method Name and Description
<static>	KJUR.jws.JWS.generateJWSByKey(sHead, sPayload, RSA) generate JWS signature by Header, Payload and a RSA private key.
<static>	KJUR.jws.JWS.generateJWSByNED(sHead, sPayload, hN, hE, hD) generate JWS signature by Header, Payload and a naked RSA private key.
<static>	KJUR.jws.JWS.generateJWSByP1PrvKey(sHead, sPayload, string) generate JWS signature by Header, Payload and a PEM formatted PKCS#1 RSA private key.
<static>	KJUR.jws.JWS.getEncodedSignatureValueFromJWS(sJWS) get Encoed Signature Value from JWS string.
<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, sHead, sPayload, 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.verifyJWSByKey(sJWS, key) verify JWS signature with RSA public key.
<static>	KJUR.jws.JWS.verifyJWSByNE(sJWS, hN, hE) verify JWS signature with naked RSA public key.
<static>	KJUR.jws.JWS.verifyJWSByPemX509Cert(sJWS, sPemX509Cert) verify JWS signature by PEM formatted X.509 certificate.

Class Detail

KJUR.jws.JWS()

JSON Web Signature(JWS) class.

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.

Since:: jsjws 1.0

Requires:: base64x.js, json-sans-eval.js and jsrsasign library

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

{Dictionary} parsedJWS

This property is set after JWS signature verification.
Following "parsedJWS_*" properties can be accessed as "parsedJWS.*" because of JsDoc restriction.

{String} parsedJWS_headB64U

string of Encrypted JWS Header

{String} parsedJWS_headS

string of decoded JWS Header

{String} parsedJWS_payloadB64U

string of Encrypted JWS Payload

{String} parsedJWS_si

string of Signature Input

{String} parsedJWS_sigvalB64U

string of Encrypted JWS signature value

{String} parsedJWS_sigvalBI

BigInteger(defined in jsbn.js) object of JWS signature value

{String} parsedJWS_sigvalH

hexadecimal string of JWS signature value

Method Detail

<static> {String} KJUR.jws.JWS.generateJWSByKey(sHead, sPayload, RSA)

generate JWS signature by Header, Payload and a RSA private key.
This only supports "RS256", "RS512", "PS256" and "PS512" algorithms.

Parameters:
{String} sHead: string of JWS Header
{String} sPayload: string of JWS Payload
{RSAKey} RSA: private key

Deprecated:
from 3.0.0 please move to KJUR.jws.JWS.sign

Throws:
: if sHead is a malformed JSON string.
: if supported signature algorithm was not specified in JSON Header.

Returns:: {String} JWS signature string

<static> {String} KJUR.jws.JWS.generateJWSByNED(sHead, sPayload, hN, hE, hD)

generate JWS signature by Header, Payload and a naked RSA private key.
This only supports "RS256" and "RS512" algorithm.

Parameters:
{String} sHead: string of JWS Header
{String} sPayload: string of JWS Payload
{String} hN: hexadecimal string for modulus of RSA public key
{String} hE: hexadecimal string for public exponent of RSA public key
{String} hD: hexadecimal string for private exponent of RSA private key

Deprecated:
from 3.0.0 please move to KJUR.jws.JWS.sign

Throws:
: if sHead is a malformed JSON string.
: if supported signature algorithm was not specified in JSON Header.

Returns:: {String} JWS signature string

<static> {String} KJUR.jws.JWS.generateJWSByP1PrvKey(sHead, sPayload, string)

generate JWS signature by Header, Payload and a PEM formatted PKCS#1 RSA private key.
This only supports "RS256" and "RS512" algorithm.

Parameters:
{String} sHead: string of JWS Header
{String} sPayload: string of JWS Payload
{String} string: for sPemPrvKey PEM formatted PKCS#1 RSA private key
Heading and trailing space characters in PEM key will be ignored.

Deprecated:
from 3.0.0 please move to KJUR.jws.JWS.sign

Since:: 1.1

Throws:
: if sHead is a malformed JSON string.
: if supported signature algorithm was not specified in JSON Header.

Returns:: {String} JWS signature string

<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> {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, sHead, sPayload, key, pass)

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

alg value	spec requirement	jsjws support
HS256	REQUIRED	SUPPORTED
HS384	OPTIONAL	-
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:: The reason of HS384 unsupport is CryptoJS HmacSHA384 bug.

Parameters:
{String} alg: JWS algorithm name to sign and force set to sHead or null
{String} sHead: string of JWS Header
{String} sPayload: string of JWS Payload
{String} key: string of private key or key object to sign
{String} pass: (OPTION)passcode to use encrypted 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.

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

// 2) verify a HS256 JWS signature by a certificate string.
var isValid = KJUR.jws.JWS.verify('eyJh...', '6f62ad...', ['HS256']);

// 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.verifyJWSByKey(sJWS, key)

verify JWS signature with RSA public key.
This only supports "RS256", "RS512", "PS256" and "PS512" algorithms.

Parameters:
{String} sJWS: JWS signature string to be verified
{RSAKey} key: RSA public key

Deprecated:
from 3.0.0 please move to KJUR.jws.JWS.verify

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

Returns:: {Boolean} returns true when JWS signature is valid, otherwise returns false

<static> {String} KJUR.jws.JWS.verifyJWSByNE(sJWS, hN, hE)

verify JWS signature with naked RSA public key.
This only supports "RS256" and "RS512" algorithm.

Parameters:
{String} sJWS: JWS signature string to be verified
{String} hN: hexadecimal string for modulus of RSA public key
{String} hE: hexadecimal string for public exponent of RSA public key

Deprecated:
from 3.0.0 please move to KJUR.jws.JWS.verify

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

Returns:: {String} returns 1 when JWS signature is valid, otherwise returns 0

<static> {String} KJUR.jws.JWS.verifyJWSByPemX509Cert(sJWS, sPemX509Cert)

verify JWS signature by PEM formatted X.509 certificate.
This only supports "RS256" and "RS512" algorithm.

Parameters:
{String} sJWS: JWS signature string to be verified
{String} sPemX509Cert: string of PEM formatted X.509 certificate

Deprecated:
from 3.0.0 please move to KJUR.jws.JWS.verify

Since:: 1.1

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

Returns:: {String} returns 1 when JWS signature is valid, otherwise returns 0

Classes

Class KJUR.jws.JWS

Supported Algorithms