senselogic.sitevision.api.security

Interface JwtUtil<O>

Type Parameters:

O - script object

@Requireable(value="JwtUtil")
public interface JwtUtil<O>

JSON Web Token (JWT) utilities.

Technical information about JWT:

• Introduction to JSON Web Tokens
• RFC 7519: The JSON Web Token specification

Since:

Sitevision 5.1

Author:

Anders Sjöstrand

Method Summary

Modifier and Type	Method and Description
String	createRSAToken(O aClaims, String aAlgorithm, Node aPrivateKey, String aPassword) Create a JWT token signed with a RSA keypair.
String	createSHAToken(O aClaims, String aAlgorithm, String aPreSharedKey) Create a JWT token with SHA hashing.
O	decodeRSA(String aToken, Node aPublicKey) Validate a JWT token created using a RSA keypair.
O	decodeSHA(String aToken, String aPreSharedKey) Validate a JWT token created with SHA and a pre-shared key.

Method Detail

createSHAToken

String createSHAToken(O aClaims,
                      String aAlgorithm,
                      String aPreSharedKey)
               throws JwtException,
                      IllegalArgumentException

Create a JWT token with SHA hashing.

When creating a JWT token, Sitevision always adds an IAT (issued at) claim. The IAT date is set to the time of creation. Custom claims can be of the following types.

• String
• Boolean
• Integer
• Long
• Array of String
• Array of Long

JWT tokens signed using a pre-shared key can use an algorithm of the following types:

• HS256
• HS384
• HS512

Parameters:

aClaims - The claims to send as payload. Claim values can be of types String, Boolean, Integer, Long and also arrays of Strings or Longs

aAlgorithm - Hashing algorithm used, viable values are HS256, HS384 and HS512

aPreSharedKey - Pre-shared key used for hashing.

Returns:

A JWT token

Throws:

JwtException - If an error occurs when creating the JWT token

IllegalArgumentException - If aPreSharedKey or aAlgorithm is blank.

createRSAToken

String createRSAToken(O aClaims,
                      String aAlgorithm,
                      Node aPrivateKey,
                      String aPassword)
               throws ConstraintViolationException,
                      JwtException,
                      IllegalArgumentException

Create a JWT token signed with a RSA keypair.

When creating a JWT token, Sitevision always adds an IAT (issued at) claim. The IAT date is set to the time of creation. Custom claims can be of the following types.

• String
• Boolean
• Integer
• Long
• Array of String
• Array of Long

JWT tokens signed using a pre-shared key can use an algorithm of the following types:

• RS256
• RS384
• RS512

When signing or decoding JWT using RSA keypair, Sitevision only support keys coded in standard PEM text format. Private keys can use password, but if a key without password is used, an empty string as password must be supplied.

Parameters:

aClaims - The claims to send as payload. Claim values can be of types String, Boolean, Integer, Long and also arrays of Strings or Longs

aAlgorithm - Signing algorithm used, viable values are RS256, RS384 and RS512

aPrivateKey - A sv:file or sv:temporaryFile with the PEM formatted RSA private key.

aPassword - Password for the private key, use an empty string if the key is not password protected.

Returns:

A JWT token

Throws:

ConstraintViolationException - If the private key cannot be found or accessed

JwtException - If an error occurs when creating the JWT token

IllegalArgumentException - If aPassword is null, aAlgorithm is blank, aPrivateKey is null or if aPrivateKey is not a RSA private key.

decodeSHA

O decodeSHA(String aToken,
            String aPreSharedKey)
     throws JwtException,
            IllegalArgumentException

Validate a JWT token created with SHA and a pre-shared key.

The algorithm to decode is automatically detected by Sitevision from the token but it must be one of the following types:

• HS256
• HS384
• HS512

Parameters:

aToken - Token to validate

aPreSharedKey - Pre-shared key that the hash was created with

Returns:

A javascript object with the alg and payload if the token was correctly validated.

Throws:

JwtException - If an error occurs the decoding the JWT token

IllegalArgumentException - If aToken or aPreSharedKey are blank.

decodeRSA

O decodeRSA(String aToken,
            Node aPublicKey)
     throws ConstraintViolationException,
            JwtException,
            IllegalArgumentException

Validate a JWT token created using a RSA keypair.

The algorithm to decode is automatically detected by Sitevision from the token but it must be one of the following types:

• RS256
• RS384
• RS512

When signing or decoding JWT using RSA keypair, Sitevision only support keys coded in standard PEM text format.

Parameters:

aToken - Token to validate.

aPublicKey - A sv:file or sv:temporaryFile containing the PEM formatted RSA public key for decrypting the JWT token.

Returns:

A javascript object with the alg and payload if the token was correctly validated.

Throws:

ConstraintViolationException - If the public key cannot be found or accessed

JwtException - If an error occurs the decoding the JWT token

IllegalArgumentException - If aToken is blank, aPublicKey is null or aPublicKey is not a RSA public key