/* * Copyright (C) 2019 jsonwebtoken.io * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package io.jsonwebtoken; import java.security.Key; import java.util.Date; import java.util.Map; /** * A builder to construct a {@link JwtParser}. Example usage: * 
{@code
 *     Jwts.parserBuilder()
 *         .setSigningKey(...)
 *         .requireIssuer("https://issuer.example.com")
 *         .build()
 *         .parse(jwtString)
 * }
* @since 0.11.0 */ public interface JwtParserBuilder { /** * Sets the signing key used to verify any discovered JWS digital signature. If the specified JWT string is not * a JWS (no signature), this key is not used. *

*

Note that this key MUST be a valid key for the signature algorithm found in the JWT header * (as the {@code alg} header parameter).

*

*

This method overwrites any previously set key.

* * @param key the algorithm-specific signature verification key used to validate any discovered JWS digital * signature. * @return the parser builder for method chaining. */ JwtParserBuilder setSigningKey(byte[] key); /** * Sets the signing key used to verify any discovered JWS digital signature. If the specified JWT string is not * a JWS (no signature), this key is not used. * *

Note that this key MUST be a valid key for the signature algorithm found in the JWT header * (as the {@code alg} header parameter).

* *

This method overwrites any previously set key.

* *

This is a convenience method: the string argument is first BASE64-decoded to a byte array and this resulting * byte array is used to invoke {@link #setSigningKey(byte[])}.

* *

Deprecation Notice: Deprecated as of 0.10.0, will be removed in 1.0.0

* *

This method has been deprecated because the {@code key} argument for this method can be confusing: keys for * cryptographic operations are always binary (byte arrays), and many people were confused as to how bytes were * obtained from the String argument.

* *

This method always expected a String argument that was effectively the same as the result of the following * (pseudocode):

* *

{@code String base64EncodedSecretKey = base64Encode(secretKeyBytes);}

* *

However, a non-trivial number of JJWT users were confused by the method signature and attempted to * use raw password strings as the key argument - for example {@code setSigningKey(myPassword)} - which is * almost always incorrect for cryptographic hashes and can produce erroneous or insecure results.

* *

See this * * StackOverflow answer explaining why raw (non-base64-encoded) strings are almost always incorrect for * signature operations.

* *

Finally, please use the {@link #setSigningKey(Key) setSigningKey(Key)} instead, as this method and the * {@code byte[]} variant will be removed before the 1.0.0 release.

* * @param base64EncodedSecretKey the BASE64-encoded algorithm-specific signature verification key to use to validate * any discovered JWS digital signature. * @return the parser builder for method chaining. */ JwtParserBuilder setSigningKey(String base64EncodedSecretKey); /** * Sets the signing key used to verify any discovered JWS digital signature. If the specified JWT string is not * a JWS (no signature), this key is not used. *

*

Note that this key MUST be a valid key for the signature algorithm found in the JWT header * (as the {@code alg} header parameter).

*

*

This method overwrites any previously set key.

* * @param key the algorithm-specific signature verification key to use to validate any discovered JWS digital * signature. * @return the parser builder for method chaining. */ JwtParserBuilder setSigningKey(Key key); /** * Sets the {@link SigningKeyResolver} used to acquire the signing key that should be used to verify * a JWS's signature. If the parsed String is not a JWS (no signature), this resolver is not used. *

*

Specifying a {@code SigningKeyResolver} is necessary when the signing key is not already known before parsing * the JWT and the JWT header or payload (plaintext body or Claims) must be inspected first to determine how to * look up the signing key. Once returned by the resolver, the JwtParser will then verify the JWS signature with the * returned key. For example:

*

* 

     * Jws<Claims> jws = Jwts.parser().setSigningKeyResolver(new SigningKeyResolverAdapter() {
     *         @Override
     *         public byte[] resolveSigningKeyBytes(JwsHeader header, Claims claims) {
     *             //inspect the header or claims, lookup and return the signing key
     *             return getSigningKey(header, claims); //implement me
     *         }})
     *     .parseClaimsJws(compact);
     *
*

*

A {@code SigningKeyResolver} is invoked once during parsing before the signature is verified.

*

*

This method should only be used if a signing key is not provided by the other {@code setSigningKey*} builder * methods.

* * @param signingKeyResolver the signing key resolver used to retrieve the signing key. * @return the parser builder for method chaining. */ JwtParserBuilder setSigningKeyResolver(SigningKeyResolver signingKeyResolver); /** * Returns an immutable/thread-safe {@link JwtParser} created from the configuration from this JwtParserBuilder. * @return an immutable/thread-safe JwtParser created from the configuration from this JwtParserBuilder. */ JwtParser build(); }