io.jsonwebtoken

Interface JwtParser

All Superinterfaces:

Parser<Jwt<?,?>>

public interface JwtParser
extends Parser<Jwt<?,?>>

A parser for reading JWT strings, used to convert them into a Jwt object representing the expanded JWT. A parser for reading JWT strings, used to convert them into a Jwt object representing the expanded JWT.

Since:

0.1

Method Summary

Methods

Modifier and Type	Method and Description
boolean	isSigned(CharSequence compact) Returns true if the specified JWT compact string represents a signed JWT (aka a 'JWS'), false otherwise.
Jwt<?,?>	parse(CharSequence jwt) Parses the specified compact serialized JWT string based on the builder's current configuration state and returns the resulting JWT, JWS, or JWE instance.
<T> T	parse(CharSequence jwt, JwtHandler<T> handler) Deprecated. since 0.12.0 in favor of parse(CharSequence).accept(visitor);
Jws<Claims>	parseClaimsJws(CharSequence jws) Deprecated. since 0.12.0 in favor of parseSignedClaims(CharSequence).
Jwt<Header,Claims>	parseClaimsJwt(CharSequence jwt) Deprecated. since 0.12.0 in favor of parseUnsecuredClaims(CharSequence).
Jws<byte[]>	parseContentJws(CharSequence jws) Deprecated. since 0.12.0 in favor of parseSignedContent(CharSequence).
Jwt<Header,byte[]>	parseContentJwt(CharSequence jwt) Deprecated. since 0.12.0 in favor of parseUnsecuredContent(CharSequence).
Jwe<Claims>	parseEncryptedClaims(CharSequence jwe) Parses the jwe argument, expected to be an encrypted Claims JWE.
Jwe<byte[]>	parseEncryptedContent(CharSequence jwe) Parses the jwe argument, expected to be an encrypted content JWE.
Jws<Claims>	parseSignedClaims(CharSequence jws) Parses the jws argument, expected to be a cryptographically-signed Claims JWS.
Jws<Claims>	parseSignedClaims(CharSequence jws, byte[] unencodedPayload) Parses a JWS known to use the RFC 7797: JSON Web Signature (JWS) Unencoded Payload Option, using the specified unencodedPayload for signature verification.
Jws<Claims>	parseSignedClaims(CharSequence jws, InputStream unencodedPayload) Parses a JWS known to use the RFC 7797: JSON Web Signature (JWS) Unencoded Payload Option, using the bytes from the specified unencodedPayload stream for signature verification and Claims creation.
Jws<byte[]>	parseSignedContent(CharSequence jws) Parses the jws argument, expected to be a cryptographically-signed content JWS.
Jws<byte[]>	parseSignedContent(CharSequence jws, byte[] unencodedPayload) Parses a JWS known to use the RFC 7797: JSON Web Signature (JWS) Unencoded Payload Option, using the specified unencodedPayload for signature verification.
Jws<byte[]>	parseSignedContent(CharSequence jws, InputStream unencodedPayload) Parses a JWS known to use the RFC 7797: JSON Web Signature (JWS) Unencoded Payload Option, using the bytes from the specified unencodedPayload stream for signature verification.
Jwt<Header,Claims>	parseUnsecuredClaims(CharSequence jwt) Parses the jwt argument, expected to be an unsecured Claims JWT.
Jwt<Header,byte[]>	parseUnsecuredContent(CharSequence jwt) Parses the jwt argument, expected to be an unsecured content JWT.

Methods inherited from interface io.jsonwebtoken.io.Parser

parse, parse, parse

Method Detail

isSigned

boolean isSigned(CharSequence compact)

Returns true if the specified JWT compact string represents a signed JWT (aka a 'JWS'), false otherwise.

Note that if you are reasonably sure that the token is signed, it is more efficient to attempt to parse the token (and catching exceptions if necessary) instead of calling this method first before parsing.

Parameters:

compact - the compact serialized JWT to check

Returns:

true if the specified JWT compact string represents a signed JWT (aka a 'JWS'), false otherwise.

parse

Jwt<?,?> parse(CharSequence jwt)
               throws ExpiredJwtException,
                      MalformedJwtException,
                      SignatureException,
                      SecurityException,
                      IllegalArgumentException

Parses the specified compact serialized JWT string based on the builder's current configuration state and returns the resulting JWT, JWS, or JWE instance.

Because it is often cumbersome to determine if the result is a JWT, JWS or JWE, or if the payload is a Claims or byte[] array with instanceof checks, it may be useful to call the result's accept(JwtVisitor) method for a type-safe callback approach instead of using if-then-else instanceof conditionals. For example, instead of:

 // NOT RECOMMENDED:
 Jwt<?,?> jwt = parser.parse(input);
 if (jwt instanceof Jwe<?>) {
     Jwe<?> jwe = (Jwe<?>)jwt;
     if (jwe.getPayload() instanceof Claims) {
         Jwe<Claims> claimsJwe = (Jwe<Claims>)jwe;
         // do something with claimsJwe
     }
 }

the following alternative is usually preferred:

 Jwe<Claims> jwe = parser.parse(input).accept(Jwe.CLAIMS);

Specified by:

parse in interface Parser<Jwt<?,?>>

Parameters:

jwt - the compact serialized JWT to parse

Returns:

the parsed JWT instance

Throws:

MalformedJwtException - if the specified JWT was incorrectly constructed (and therefore invalid). Invalid JWTs should not be trusted and should be discarded.

SignatureException - if a JWS signature was discovered, but could not be verified. JWTs that fail signature validation should not be trusted and should be discarded.

SecurityException - if the specified JWT string is a JWE and decryption fails

ExpiredJwtException - if the specified JWT is a Claims JWT and the Claims has an expiration time before the time this method is invoked.

IllegalArgumentException - if the specified string is null or empty or only whitespace.

SignatureException

See Also:

Jwt.accept(JwtVisitor)

parse

@Deprecated
<T> T parse(CharSequence jwt,
                     JwtHandler<T> handler)
        throws ExpiredJwtException,
               UnsupportedJwtException,
               MalformedJwtException,
               SignatureException,
               SecurityException,
               IllegalArgumentException

Deprecated. since 0.12.0 in favor of parse(CharSequence).accept(visitor);

Deprecated since 0.12.0 in favor of calling any parse* method immediately followed by invoking the parsed JWT's accept method with your preferred visitor. For example:

 parse(jwt).accept(visitor);

This method will be removed before the 1.0 release.

Type Parameters:

T - the type of object returned from the handler

Parameters:

jwt - the compact serialized JWT to parse

handler - the handler to invoke when encountering a specific type of JWT

Returns:

the result returned by the JwtHandler

Throws:

MalformedJwtException - if the specified JWT was incorrectly constructed (and therefore invalid). Invalid JWTs should not be trusted and should be discarded.

SignatureException - if a JWS signature was discovered, but could not be verified. JWTs that fail signature validation should not be trusted and should be discarded.

SecurityException - if the specified JWT string is a JWE and decryption fails

ExpiredJwtException - if the specified JWT is a Claims JWT and the Claims has an expiration time before the time this method is invoked.

IllegalArgumentException - if the specified string is null or empty or only whitespace, or if the handler is null.

UnsupportedJwtException

SignatureException

Since:

0.2

See Also:

Jwt.accept(JwtVisitor)

parseContentJwt

@Deprecated
Jwt<Header,byte[]> parseContentJwt(CharSequence jwt)
                                   throws UnsupportedJwtException,
                                          MalformedJwtException,
                                          SignatureException,
                                          SecurityException,
                                          IllegalArgumentException

Deprecated. since 0.12.0 in favor of parseUnsecuredContent(CharSequence).

Deprecated since 0.12.0 in favor of parseUnsecuredContent(CharSequence).

This method will be removed before the 1.0 release.

Parameters:

jwt - a compact serialized unsecured content JWT string.

Returns:

the Jwt instance that reflects the specified compact JWT string.

Throws:

UnsupportedJwtException - if the jwt argument does not represent an unsecured content JWT

MalformedJwtException - if the jwt string is not a valid JWT

SignatureException - if the jwt string is actually a JWS and signature validation fails

SecurityException - if the jwt string is actually a JWE and decryption fails

IllegalArgumentException - if the jwt string is null or empty or only whitespace

SignatureException

Since:

0.2

See Also:

parseUnsecuredContent(CharSequence), Jwt.accept(JwtVisitor)

parseClaimsJwt

@Deprecated
Jwt<Header,Claims> parseClaimsJwt(CharSequence jwt)
                                  throws ExpiredJwtException,
                                         UnsupportedJwtException,
                                         MalformedJwtException,
                                         SignatureException,
                                         SecurityException,
                                         IllegalArgumentException

Deprecated. since 0.12.0 in favor of parseUnsecuredClaims(CharSequence).

Deprecated since 0.12.0 in favor of parseUnsecuredClaims(CharSequence).

This method will be removed before the 1.0 release.

Parameters:

jwt - a compact serialized unsecured Claims JWT string.

Returns:

the Jwt instance that reflects the specified compact JWT string.

Throws:

UnsupportedJwtException - if the jwt argument does not represent an unsecured Claims JWT

MalformedJwtException - if the jwt string is not a valid JWT

SignatureException - if the jwt string is actually a JWS and signature validation fails

SecurityException - if the jwt string is actually a JWE and decryption fails

IllegalArgumentException - if the jwt string is null or empty or only whitespace

ExpiredJwtException

SignatureException

Since:

0.2

See Also:

parseUnsecuredClaims(CharSequence), Jwt.accept(JwtVisitor)

parseContentJws

@Deprecated
Jws<byte[]> parseContentJws(CharSequence jws)
                            throws UnsupportedJwtException,
                                   MalformedJwtException,
                                   SignatureException,
                                   SecurityException,
                                   IllegalArgumentException

Deprecated. since 0.12.0 in favor of parseSignedContent(CharSequence).

Deprecated since 0.12.0 in favor of parseSignedContent(CharSequence).

This method will be removed before the 1.0 release.

Parameters:

jws - a compact content JWS string

Returns:

the parsed and validated content JWS

Throws:

UnsupportedJwtException - if the jws argument does not represent a content JWS

MalformedJwtException - if the jws string is not a valid JWS

SignatureException - if the jws JWS signature validation fails

SecurityException - if the jws string is actually a JWE and decryption fails

IllegalArgumentException - if the jws string is null or empty or only whitespace

SignatureException

Since:

0.2

See Also:

parseSignedContent(CharSequence), parseEncryptedContent(CharSequence), parse(CharSequence)

parseClaimsJws

@Deprecated
Jws<Claims> parseClaimsJws(CharSequence jws)
                           throws ExpiredJwtException,
                                  UnsupportedJwtException,
                                  MalformedJwtException,
                                  SignatureException,
                                  SecurityException,
                                  IllegalArgumentException

Deprecated. since 0.12.0 in favor of parseSignedClaims(CharSequence).

Deprecated since 0.12.0 in favor of parseSignedClaims(CharSequence).

Parameters:

jws - a compact Claims JWS string.

Returns:

the parsed and validated Claims JWS

Throws:

UnsupportedJwtException - if the claimsJws argument does not represent an Claims JWS

MalformedJwtException - if the claimsJws string is not a valid JWS

SignatureException - if the claimsJws JWS signature validation fails

SecurityException - if the jws string is actually a JWE and decryption fails

ExpiredJwtException - if the specified JWT is a Claims JWT and the Claims has an expiration time before the time this method is invoked.

IllegalArgumentException - if the claimsJws string is null or empty or only whitespace

SignatureException

Since:

0.2

See Also:

parseSignedClaims(CharSequence), parseEncryptedClaims(CharSequence), parse(CharSequence)

parseUnsecuredContent

Jwt<Header,byte[]> parseUnsecuredContent(CharSequence jwt)
                                         throws JwtException,
                                                IllegalArgumentException

Parses the jwt argument, expected to be an unsecured content JWT. If the JWT creator set the (optional) contentType header value, the application may inspect that value to determine how to convert the byte array to the final content type as desired.

This is a convenience method logically equivalent to the following:

 parse(jwt).accept(Jwt.UNSECURED_CONTENT);

Parameters:

jwt - a compact unsecured content JWT.

Returns:

the parsed unsecured content JWT.

Throws:

UnsupportedJwtException - if the jwt argument does not represent an unsecured content JWT

JwtException - if the jwt string cannot be parsed or validated as required.

IllegalArgumentException - if the jwt string is null or empty or only whitespace

Since:

0.12.0

See Also:

parse(CharSequence), Jwt.accept(JwtVisitor)

parseUnsecuredClaims

Jwt<Header,Claims> parseUnsecuredClaims(CharSequence jwt)
                                        throws JwtException,
                                               IllegalArgumentException

Parses the jwt argument, expected to be an unsecured Claims JWT. This is a convenience method logically equivalent to the following:

 parse(jwt).accept(Jwt.UNSECURED_CLAIMS);

Parameters:

jwt - a compact unsecured Claims JWT.

Returns:

the parsed unsecured Claims JWT.

Throws:

UnsupportedJwtException - if the jwt argument does not represent an unsecured Claims JWT

JwtException - if the jwt string cannot be parsed or validated as required.

IllegalArgumentException - if the jwt string is null or empty or only whitespace

Since:

0.12.0

See Also:

parse(CharSequence), Jwt.accept(JwtVisitor)

parseSignedContent

Jws<byte[]> parseSignedContent(CharSequence jws)
                               throws JwtException,
                                      IllegalArgumentException

Parses the jws argument, expected to be a cryptographically-signed content JWS. If the JWS creator set the (optional) contentType header value, the application may inspect that value to determine how to convert the byte array to the final content type as desired.

This is a convenience method logically equivalent to the following:

 parse(jws).accept(Jws.CONTENT);

Parameters:

jws - a compact cryptographically-signed content JWS.

Returns:

the parsed cryptographically-verified content JWS.

Throws:

UnsupportedJwtException - if the jws argument does not represent a signed content JWS

JwtException - if the jws string cannot be parsed or validated as required.

IllegalArgumentException - if the jws string is null or empty or only whitespace

Since:

0.12.0

See Also:

parse(CharSequence), Jwt.accept(JwtVisitor)

parseSignedContent

Jws<byte[]> parseSignedContent(CharSequence jws,
                             byte[] unencodedPayload)

Parses a JWS known to use the RFC 7797: JSON Web Signature (JWS) Unencoded Payload Option, using the specified unencodedPayload for signature verification.

Unencoded Non-Detached Payload

Note that if the JWS contains a valid unencoded Payload string (what RFC 7797 calls an "unencoded non-detached payload", the unencodedPayload method argument will be ignored, as the JWS already includes the payload content necessary for signature verification.

Parameters:

jws - the Unencoded Payload JWS to parse.

unencodedPayload - the JWS's associated required unencoded payload used for signature verification.

Returns:

the parsed Unencoded Payload.

Since:

0.12.0

parseSignedContent

Jws<byte[]> parseSignedContent(CharSequence jws,
                             InputStream unencodedPayload)

Parses a JWS known to use the RFC 7797: JSON Web Signature (JWS) Unencoded Payload Option, using the bytes from the specified unencodedPayload stream for signature verification.

Because it is not possible to know how large the unencodedPayload stream will be, the stream bytes will not be buffered in memory, ensuring the resulting Jws return value's Jwt.getPayload() is always empty. This is generally not a concern since the caller already has access to the stream bytes and may obtain them independently before or after calling this method if they are needed otherwise.

Unencoded Non-Detached Payload

Note that if the JWS contains a valid unencoded payload String (what RFC 7797 calls an "unencoded non-detached payload", the unencodedPayload method argument will be ignored, as the JWS already includes the payload content necessary for signature verification. In this case the resulting Jws return value's Jwt.getPayload() will contain the embedded payload String's UTF-8 bytes.

Parameters:

jws - the Unencoded Payload JWS to parse.

unencodedPayload - the JWS's associated required unencoded payload used for signature verification.

Returns:

the parsed Unencoded Payload.

Since:

0.12.0

parseSignedClaims

Jws<Claims> parseSignedClaims(CharSequence jws)
                              throws JwtException,
                                     IllegalArgumentException

Parses the jws argument, expected to be a cryptographically-signed Claims JWS. This is a convenience method logically equivalent to the following:

 parse(jws).accept(Jws.CLAIMS);

Parameters:

jws - a compact cryptographically-signed Claims JWS.

Returns:

the parsed cryptographically-verified Claims JWS.

Throws:

UnsupportedJwtException - if the jwt argument does not represent a signed Claims JWT

JwtException - if the jwt string cannot be parsed or validated as required.

IllegalArgumentException - if the jwt string is null or empty or only whitespace

Since:

0.12.0

See Also:

parse(CharSequence), Jwt.accept(JwtVisitor)

parseSignedClaims

Jws<Claims> parseSignedClaims(CharSequence jws,
                            byte[] unencodedPayload)
                              throws JwtException,
                                     IllegalArgumentException

Parses a JWS known to use the RFC 7797: JSON Web Signature (JWS) Unencoded Payload Option, using the specified unencodedPayload for signature verification.

Unencoded Non-Detached Payload

Note that if the JWS contains a valid unencoded payload String (what RFC 7797 calls an "unencoded non-detached payload", the unencodedPayload method argument will be ignored, as the JWS already includes the payload content necessary for signature verification and claims creation.

Parameters:

jws - the Unencoded Payload JWS to parse.

unencodedPayload - the JWS's associated required unencoded payload used for signature verification.

Returns:

the parsed and validated Claims JWS.

Throws:

JwtException - if parsing, signature verification, or JWT validation fails.

IllegalArgumentException - if either the jws or unencodedPayload are null or empty.

Since:

0.12.0

parseSignedClaims

Jws<Claims> parseSignedClaims(CharSequence jws,
                            InputStream unencodedPayload)
                              throws JwtException,
                                     IllegalArgumentException

Parses a JWS known to use the RFC 7797: JSON Web Signature (JWS) Unencoded Payload Option, using the bytes from the specified unencodedPayload stream for signature verification and Claims creation.

NOTE: however, because calling this method indicates a completed Claims instance is desired, the specified unencodedPayload JSON stream will be fully read into a Claims instance. If this will be problematic for your application (perhaps if you expect extremely large Claims), it is recommended to use the parseSignedContent(CharSequence, InputStream) method instead.

Unencoded Non-Detached Payload

Note that if the JWS contains a valid unencoded Payload string (what RFC 7797 calls an "unencoded non-detached payload", the unencodedPayload method argument will be ignored, as the JWS already includes the payload content necessary for signature verification and Claims creation.

Parameters:

jws - the Unencoded Payload JWS to parse.

unencodedPayload - the JWS's associated required unencoded payload used for signature verification.

Returns:

the parsed and validated Claims JWS.

Throws:

JwtException - if parsing, signature verification, or JWT validation fails.

IllegalArgumentException - if either the jws or unencodedPayload are null or empty.

Since:

0.12.0

parseEncryptedContent

Jwe<byte[]> parseEncryptedContent(CharSequence jwe)
                                  throws JwtException,
                                         IllegalArgumentException

Parses the jwe argument, expected to be an encrypted content JWE. If the JWE creator set the (optional) contentType header value, the application may inspect that value to determine how to convert the byte array to the final content type as desired.

This is a convenience method logically equivalent to the following:

 parse(jwe).accept(Jwe.CONTENT);

Parameters:

jwe - a compact encrypted content JWE.

Returns:

the parsed decrypted content JWE.

Throws:

UnsupportedJwtException - if the jwe argument does not represent an encrypted content JWE

JwtException - if the jwe string cannot be parsed or validated as required.

IllegalArgumentException - if the jwe string is null or empty or only whitespace

Since:

0.12.0

See Also:

parse(CharSequence), Jwt.accept(JwtVisitor)

parseEncryptedClaims

Jwe<Claims> parseEncryptedClaims(CharSequence jwe)
                                 throws JwtException,
                                        IllegalArgumentException

Parses the jwe argument, expected to be an encrypted Claims JWE. This is a convenience method logically equivalent to the following:

 parse(jwe).accept(Jwe.CLAIMS);

Parameters:

jwe - a compact encrypted Claims JWE.

Returns:

the parsed decrypted Claims JWE.

Throws:

UnsupportedJwtException - if the jwe argument does not represent an encrypted Claims JWE.

JwtException - if the jwe string cannot be parsed or validated as required.

IllegalArgumentException - if the jwe string is null or empty or only whitespace

Since:

0.12.0

See Also:

parse(CharSequence), Jwt.accept(JwtVisitor)