All Versions
25
Latest Version
Avg Release Cycle
-
Latest Release
-

Changelog History
Page 3

  • v0.5.1 Changes

    • ๐Ÿš€ Minor bug fix release that ensures correct Base64 padding in Android runtimes.
  • v0.5 Changes

    • ๐Ÿ‘ Android support! Android's built-in Base64 codec will be used if JJWT detects it is running in an Android environment. Other than Base64, all other parts of JJWT were already Android-compliant. Now it is fully compliant.

    • ๐Ÿ‘ Elliptic Curve signature algorithms! SignatureAlgorithm.ES256, ES384 and ES512 are now supported.

    • Super convenient key generation methods, so you don't have to worry how to do this safely:

      • MacProvider.generateKey(); //or generateKey(SignatureAlgorithm)
      • RsaProvider.generateKeyPair(); //or generateKeyPair(sizeInBits)
      • EllipticCurveProvider.generateKeyPair(); //or generateKeyPair(SignatureAlgorithm)

    The generate* methods that accept an SignatureAlgorithm argument know to generate a key of sufficient strength that reflects the specified algorithm strength.

    ๐Ÿ‘€ Please see the full 0.5 closed issues list for more information.

  • v0.4 Changes

    • Issue 8: Add ability to find signing key by inspecting the JWS values before verifying the signature.

    ๐Ÿ“œ This is a handy little feature. If you need to parse a signed JWT (a JWS) and you don't know which signing key was used to sign it, you can now use the new SigningKeyResolver concept.

    A SigningKeyresolver can inspect the JWS header and body (Claims or String) before the JWS signature is verified. By inspecting the data, you can find the key and return it, and the parser will use the returned key to validate the signature. For example:

    SigningKeyResolver resolver = new MySigningKeyResolver();
    
    Jws<Claims> jws = Jwts.parser().setSigningKeyResolver(resolver).parseClaimsJws(compact);
    

    ๐Ÿ‘€ The signature is still validated, and the JWT instance will still not be returned if the jwt string is invalid, as expected. You just get to 'see' the JWT data for key discovery before the parser validates. Nice.

    This of course requires that you put some sort of information in the JWS when you create it so that your SigningKeyResolver implementation can look at it later and look up the key. The standard way to do this is to use the JWS kid ('key id') field, for example:

    Jwts.builder().setHeaderParam("kid", your_signing_key_id_NOT_THE_SECRET).build();
    

    0๏ธโƒฃ You could of course set any other header parameter or claims parameter instead of setting kid if you want - that's just the default field reserved for signing key identification. If you can locate the signing key based on other information in the header or claims, you don't need to set the kid field - just make sure your resolver implementation knows how to look up the key.

    Finally, a nice SigningKeyResolverAdapter is provided to allow you to write quick and simple subclasses or anonymous classes instead of having to implement the SigningKeyResolver interface directly. 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
                String keyId = header.getKeyId(); //or any other field that you need to inspect
                return getSigningKey(keyId); //implement me
            }})
        .parseClaimsJws(compact);
    
  • v0.3 Changes

    • ๐Ÿ“œ Issue 6: Parsing an expired Claims JWT or JWS (as determined by the exp claims field) will now throw an ExpiredJwtException.
    • ๐Ÿ“œ Issue 7: Parsing a premature Claims JWT or JWS (as determined by the nbf claims field) will now throw a PrematureJwtException.
  • v0.2 Changes

    ๐Ÿ— More convenient Claims building

    ๐Ÿš€ This release adds convenience methods to the JwtBuilder interface so you can set claims directly on the builder without having to create a separate Claims instance/builder, reducing the amount of code you have to write. For example, this:

    Claims claims = Jwts.claims().setSubject("Joe");
    
    String compactJwt = Jwts.builder().setClaims(claims).signWith(HS256, key).compact();
    

    can now be written as:

    String compactJwt = Jwts.builder().setSubject("Joe").signWith(HS256, key).compact();
    

    ๐Ÿ›ฐ A Claims instance based on the specified claims will be created and set as the JWT's payload automatically.

    Type-safe handling for JWT and JWS with generics

    The following < 0.2 code produced a JWT as expected:

    Jwt jwt = Jwts.parser().setSigningKey(key).parse(compact);
    

    ๐Ÿ“œ But you couldn't easily determine if the jwt was a JWT or JWS instance or if the body was a Claims instance or a plaintext String without resorting to a bunch of yucky instanceof checks. In 0.2, we introduce the JwtHandler when you don't know the exact format of the compact JWT string ahead of time, and parsing convenience methods when you do.

    JwtHandler

    ๐Ÿ“œ If you do not know the format of the compact JWT string at the time you try to parse it, you can determine what type it is after parsing by providing a JwtHandler instance to the JwtParser with the new parse(String compactJwt, JwtHandler handler) method. For example:

    T returnVal = Jwts.parser().setSigningKey(key).parse(compact, new JwtHandler<T>() {
        @Override
        public T onPlaintextJwt(Jwt<Header, String> jwt) {
            //the JWT parsed was an unsigned plaintext JWT
            //inspect it, then return an instance of T (see returnVal above)
        }
    
        @Override
        public T onClaimsJwt(Jwt<Header, Claims> jwt) {
            //the JWT parsed was an unsigned Claims JWT
            //inspect it, then return an instance of T (see returnVal above)
        }
    
        @Override
        public T onPlaintextJws(Jws<String> jws) {
            //the JWT parsed was a signed plaintext JWS
            //inspect it, then return an instance of T (see returnVal above)
        }
    
        @Override
        public T onClaimsJws(Jws<Claims> jws) {
            //the JWT parsed was a signed Claims JWS
            //inspect it, then return an instance of T (see returnVal above)
        }
    });
    

    ๐Ÿ“œ Of course, if you know you'll only have to parse a subset of the above, you can use the JwtHandlerAdapter and implement only the methods you need. For example:

    T returnVal = Jwts.parser().setSigningKey(key).parse(plaintextJwt, new JwtHandlerAdapter<Jwt<Header, T>>() {
        @Override
        public T onPlaintextJws(Jws<String> jws) {
            //the JWT parsed was a signed plaintext JWS
            //inspect it, then return an instance of T (see returnVal above)
        }
    
        @Override
        public T onClaimsJws(Jws<Claims> jws) {
            //the JWT parsed was a signed Claims JWS
            //inspect it, then return an instance of T (see returnVal above)
        }
    });
    
    ๐Ÿ“œ Known Type convenience parse methods

    ๐Ÿ“œ If, unlike above, you are confident of the compact string format and know which type of JWT or JWS it will produce, you can just use one of the 4 new convenience parsing methods to get exactly the type of JWT or JWS you know exists. For example:

    
    //for a known plaintext jwt string:
    Jwt<Header,String> jwt = Jwts.parser().parsePlaintextJwt(compact);
    
    //for a known Claims JWT string:
    Jwt<Header,Claims> jwt = Jwts.parser().parseClaimsJwt(compact);
    
    //for a known signed plaintext JWT (aka a plaintext JWS):
    Jws<String> jws = Jwts.parser().setSigningKey(key).parsePlaintextJws(compact);
    
    //for a known signed Claims JWT (aka a Claims JWS):
    Jws<Claims> jws = Jwts.parser().setSigningKey(key).parseClaimsJws(compact);