Skip to content

Commit

Permalink
JWE support (#279)
Browse files Browse the repository at this point in the history
* JWE support. Resolves #113

Huge feature/code change - see CHANGELOG.MD for an in-depth review of changes.

Commit note log:

- Added JWE AeadAlgorithm and KeyAlgorithm and supporting interfaces/implementations, and refactored SignatureAlgorithm to be an interface instead of an enum to enable custom algorithms
- NoneSignatureAlgorithm cleanup. Added UnsupportedKeyExceptionTest.
- Added JWK support!

* Removed the previous SignatureAlgorithm implementation concepts (Provider/Signer/Validator implementations).  Implementations are now interface-driven and fully pluggable.

* adding tests, working towards 100% coverage.  Moved api static factory class tests to impl module to avoid mocking static calls due to bridge/reflection logic.

* adding tests, removed unused class

* implementation checkpoint (safety save)

* clean build checkpoint

* continued testing w/ more coverage.  Replaced PbeKey concept with PasswordKey

* fixed erroneous optimize imports

* Added ECDH-ES key algorithms + RFC tests

* 1. Enabled targeted/limited use of BouncyCastle only when required by eliminating use of RuntimeEnvironment in favor of new Providers implementation.  JJWT will no longer modify the system providers list.
2. Changed SecretKeyGenerator.generateKey() to KeyBuilderSupplier.keyBuilder() and a new SecretKeyBuilder interface.  This allows users to customize the Provider and SecureRandom used during key generation if desired.
3. Added KeyLengthSupplier to allow certain algorithms the ability to determine a key bit length without forcing a key generation.
4. Ensured Pbes2 algorithms defaulted to OWASP-recommended iteration counts if not specified by the user.

* 1. EcdhKeyAlgorithm: consolidated duplicate logic to a single private helper method
2. Updated RequiredTypeConverter exception message to represent the expected type as well as the found type

* Minor javadoc update

* 1. Javadoc cleanup.
2. Ensured CompressionException extends from io.jsonwebtoken.io.IOException
3. Deleted old POC unused JwkParser interface
4. Ensured NoneSignatureAlgorithm reflected the correct exception message for `sign`

* Fixed erroneous JavaDoc, enhanced code coverage for DefaultClaims

* Added jwe compression test

* Added TestKeys concept for Groovy test authoring

* Added tests, cleaned up state assertions for code coverage

* Added tests, cleaned up state assertions for code coverage

* Removed unused code

* Merge branch 'master' into jwe-merge

* using groovy syntax to avoid conflict with legacy SignatureAlgorithm type

* JavaDoc fixes

* JavaDoc fixes, test additions to work on JDK >= 15

* JavaDoc fixes, test additions to work on JDK 7 and JDK >= 15

* Test adjustment to work on Java 7

* Test adjustment to work on Java 7

* code coverage work cont'd

* code coverage work cont'd

* JavaDoc fix

* Update impl/src/main/java/io/jsonwebtoken/impl/JwtTokenizer.java

Co-authored-by: sonatype-lift[bot] <37194012+sonatype-lift[bot]@users.noreply.github.com>

* lift edits

* lift edits

* lift edits

* code coverage testing cont'd

* PayloadSupplier renamed to Message

* Added new KeyPairBuilder/KeyPairBuilderSupplier for parity with KeyBuilder/KeyBuilderSupplier.  Switched all generate* calls to use the new API methods.

* - Added lots of JavaDoc
- JwtMap: Ensured Groovy GString implementations that invoke Groovy's InvokerHelper on a JwtMap implementation will print redacted values instead of the actual secret values.

* - JavaDoc additions cont'd

* - JavaDoc additions and syntax cleanup cont'd
- Minor work to fix compilation errors on a few Groovy test classes

* - JavaDoc additions and syntax cleanup cont'd
- Minor work to fix compilation errors on a few Groovy test classes

* - JavaDoc additions and syntax cleanup cont'd
- Minor work to fix compilation errors on a few Groovy test classes

* - JavaDoc additions and syntax cleanup cont'd
- Minor work to fix compilation errors on a few Groovy test classes

* - JavaDoc cont'd

* Code coverage updates cont'd

* Propagating exception wrapper function enhancements

* 100% code coverage!

* Minor test changes to work with JDK >= 11

* Ensured all JWK secret or private values were wrapped in a RedactedSupplier instance to prevent accidental printing of secure values

* - Updated JavaDoc to reflect JWK toString safety and property access
- Updated README to reflect new GsonSerializer requirements for io.jsonwebtoken.lang.Supplier

* Documentation enhancements

* Fixed erroneous JavaDoc element

* Fixed LocatorAdapter usage now that it's abstract

* Minor JavaDoc fix

* JavaDoc is now complete (no warnings) for api module

* Ensured JWS signatures are computed first before deserializing the body if no SigningKeyResolver has been configured.

* Removed EllipticCurveSignatureAlgorithm and RsaSignatureAlgorithm concepts due to some PKCS11 and HSM security providers that cannot provide keys that implement the ECKey or RSAKey interfaces.

* Removed reliance on io.jsonwebtoken.security.KeyPair now that KeyPairBuilder implementations cannot guarantee RSAKey or ECKey types

* Ensured RsaKeyAlgorithm used PublicKey and PrivateKey parameters due to PKCS11 and HSM key stores that may not expose the RSAKey interface on their RSA key implementations

* cleaned up EC point addition/doubling logic to be more readable and match equations in literature

* Deprecated JwtParserBuilder setSigningKey* methods in favor of verifyWith for name accuracy and congruence with decryptWith

* Added PositiveIntegerConverter and PublicJwkConverter for JWE Header "p2c" and "jwk" fields

* Ensured CompressionCodec inherited Identifiable for consistency w/ all other algorithms

* Ensured CompressionCodec inherited Identifiable for consistency w/ all other algorithms

* Ensured CompressionCodec inherited Identifiable for consistency w/ all other algorithms

* JavaDoc enhancement

* Added Jwks.parserBuilder(), JwkParserBuilder and JwkParser concepts

* Ensured ProtoJwkBuilder method names were all congruent (remaining set* methods were renamed to for*)

* Minor JavaDoc organization change

* Changed JweBuilder to have only two encryptWith* methods for consistency with JwtBuilder signWith* methods.  Also prevents incorrect configuration by forgetting to call follow-up methods.

* Removed DefaultValueGetter in favor of new FieldReadable concept to leverage Field instances instead of duplicating logic.

* Adding copyright headers

* Deprecated CompressionCodecResolver in favor of Locator<CompressionCodec>

* Deprecated CompressionCodecResolver in favor of Locator<CompressionCodec>

* Folded in JweBuilder concept and implementation into the existing JwtBuilder

* Cleanup to reduce duplicate logic

* Changed plaintext JWT payload type from String to byte[]

* Minor internal doc fixes

* - Added UnprotectedHeader interface
- Renamed DefaultHeader to AbstractHeader
- Renamed JwtParser 'plaintext'* methods to 'payload'* methods to more accurately reflect the JWT nomenclature

* Updated changelog to reflect the following changes:
- Added UnprotectedHeader interface
- Renamed DefaultHeader to AbstractHeader
- Renamed JwtParser 'plaintext'* methods to 'payload'* methods to more accurately reflect the JWT nomenclature

* Adding RFC 7520 test cases.

* Changed JwtBuilder/JwtParser/JwtHandler/JwtHandlerAdapter `payload` concept to `content` concept

* JavaDoc error fix

* Added JwtParserBuilder#addCompressionCodecs method and supporting tests

* Updated changelog to reflect recent changes

* doc updates

* Fixed minor types in JWE related change log

* Enabled Mutator and HeaderBuilder interfaces and implementations

* Fixed erroneous JavaDoc

* Added additional .pem files for testing PEM parsing (TBD at a later date)

* Updating documentation to prepare for JWE release

* more docs

* docs cont'd

* Update README.md

Trying to prevent table wrap

* Update README.md

testing table whitespace wrap

* Update README.md

formatting testing

* Update README.md

formatting testing cont'd

* docs cont'd

* docs cont'd

* docs cont'd

* documentation checkpoint

* documentation checkpoint, still work in progress

* added extra info about Android BouncyCastle registration

* added extra info about Android BouncyCastle registration

* added extra info about Android BouncyCastle registration

* documentation cont'd

* documentation cont'd

* documentation cont'd

* documentation cont'd

* documentation cont'd

* Upgraded Jackson to 2.12.7 due to Jackson CVE

* trying to get sonatype lift working again

* Removed unnecessary println statement in test

* Added JDK 19

* Removing JDK 19 until we can resolve incompatible groovy version

* doc formatting test

* Update README.md

Fixed 'JWE Encryption Algorithms' table formatting

* renamed PasswordKey to just Password, removed unnecessary WrappedSecretKey class and its one usage in favor of JDK-standard SecretKeySpec

* Updated PasswordKey references to Password

* Renamed DefaultPassword to PasswordSpec while also implementing KeySpec per JDK conventions.

* documentation cont'd

* documentation cont'd

* documentation cont'd

* JWT expired exception is now shows difference as now - expired

Instead of now + skew - expired

Fixes: #660

* documentation cont'd

* Fixed erroneous error message (should be '521' not '512').

* - Removed EcKeyAlgorithm and RsaKeyAlgorithm in favor of KeyAlgorithm<PublicKey, PrivateKey> due to HSM key types unable to conform to respective ECKey or RSAKey types
- added Curve concept with DefaultCurve and ECCurve implementations for use across EC/EdEC SignatureAlgorithm and KeyAlgorithm implementations
- disabled Zulu JDK 10 - compiler was failing, and that is a short-term-supported version anyway
- added Temurin JDK 19 and Zulu JDK 19 to the build

* Removed JDK 19 builds due to error with Groovy compiler version compatibility

* removed unused test, created #765 to address later

* updated test case to reflect Edwards keys algorithm name differences between BouncyCastle and JDK 11/15

* - Reordered JwtBuilder .encryptWith method arguments to match signWith conventions
- Added key validation logic to DefaultRsaKeyAlgorithm

* - Reordered JwtBuilder .encryptWith method arguments to match signWith conventions
- Added key validation logic to DefaultRsaKeyAlgorithm
- Removed mutation methods on InvalidClaimException and its subclasses, IncorrectClaimException and MissingClaimException
- renamed Jwks.parserBuilder() to Jwks.parser() to reduce verbosity since we'll never likely offer a Jwts.parser() that returns a Parser instance directly.

* Documentation updates

* Documentation updates

* Documentation updates

* Adding Java-based tests for README.md code snippets (e.g. new Examples section).

* Testing README code snippet in examples

* Testing README code snippet in examples

* Testing README code snippet in examples

* Ensured README.md examples would compile/run by testing code in a JavaReadmeTest.java class

* Ensured README.md examples would compile/run by testing code in a JavaReadmeTest.java class

* Ensured README.md examples would compile/run by testing code in a JavaReadmeTest.java class

* Ensured README.md examples would compile/run by testing code in a JavaReadmeTest.java class

* Ensured README.md examples would compile/run by testing code in a JavaReadmeTest.java class

* Ensured README.md examples would compile/run by testing code in a JavaReadmeTest.java class

* Ensured README.md examples would compile/run by testing code in a JavaReadmeTest.java class

* Ensured README.md examples would compile/run by testing code in a JavaReadmeTest.java class

* Ensured README.md examples would compile/run by testing code in a JavaReadmeTest.java class

* Ensured README.md examples would compile/run by testing code in a JavaReadmeTest.java class

* Ensured README.md examples would compile/run by testing code in a JavaReadmeTest.java class

* Ensured README.md examples would compile/run by testing code in a JavaReadmeTest.java class

* Ensured README.md examples would compile/run by testing code in a JavaReadmeTest.java class

* Testing coveralls failure fix for JavaReadmeTest (unnecessary for coverage)

* Message* API refactoring cleanup

* Refactored SignatureAlgorithm(s) concept as a new DigestAlgorithm hierarchy to support non-keyed digests, as well as to reflect correct cryptographic taxonomy.  Renamed SignatureAlgorithms utility class to JwsAlgorithms.

* - Added JwkThumbprint and JWK Thumbprint URI support
- Fixed various copyright headers

* Updated README with JWK examples

* - Added logic and test to ensure Parser builder does not allow both a signature verification key and SigningKeyResolver to be configured.
- Updated README code example, and added test for verification

* - Added proactive checks to ensure PublicKey instances cannot be specified on JwtBuilder to create digital signatures
- Added additional tests to ensure that Password instances cannot be used with Mac algorithm instances (HS256, HS384, HS512, etc)

* minor edit to reflect latest # of test cases

* Minor JavaDoc improvement

* Disabled parsing of unsecured compressed payloads by default, with a JwtParserBuilder#enableUnsecuredDecompression method added for override if necessary.

* Refactored JcaTemplate to avoid reflection

* minor readme clarification

* Edwards Curve keys checkpoint

* Edwards Curve keys and related functionality checkpoint.  Added lots of tests.

* Edwards Curve keys and related functionality checkpoint.  Reached 100% code coverage.

* Addressed EdwardsCurve differences (and a JDK 11 PKCS8 encoding bug) between JDK versions (1.7 through 15+).

* Addressed EdwardsCurve differences (and a JDK 11 PKCS8 encoding bug) between JDK versions (1.7 through 18).

* Adding --add-opens lines to surefire/test config to avoid unnecessary build warnings

* Improved Edwards Key encoding error checks

* added some code to test errors in CI

* added some code to test errors in CI

* added some code to test errors in CI

* added some code to test errors in CI

* added some code to test errors in CI

* added some code to test errors in CI

* added some code to test errors in CI

* added some code to test errors in CI

* added some code to test errors in CI

* added some code to test errors in CI

* added some code to test errors in CI

* added some code to test errors in CI

* added some code to test errors in CI

* Improved Field/FieldBuilder implementation to make it more robust and catch type errors.  JwkBuilder/Factory refactoring is likely to follow on subsequent commits.

* Updating CI config to use the Oracle no-fee JDK builds

* Updating CI config to use the Oracle no-fee JDK builds

* Updating CI config to use the Oracle no-fee JDK builds

* JavaDoc fixes

* JavaDoc fixes

* JavaDoc fixes

* Ensured license headers are updated with correct dates based on git history, as well as ensured this is enforced in CI

* fixed various build warnings and javadoc errors

* Maven license plugin config cleanup. Removed now-unused header_format.xml file.

* fixed javadoc error causing build failures

* Changed Algorithms + Bridge concept to allow nested inner classes for simpler authoring all stemming from an 'Algorithms' class (easier to find algorithms via code completion than knowing off the top of your head which *Algorithms classes to reference).

* Added license headers

* Moved JwsAlgorithms to an inner class of Algorithms.  Will rename to `StandardSecureDigestAlgorithms` to maintain the convention used with the other Algorithms inner classes.

* Extracting Algorithms inner classes up a level - cleaner/easier to maintain, document and reference as JavaDoc links.

* Extracting Algorithms inner classes up a level - cleaner/easier to maintain, document and reference as JavaDoc links.  Renamed JwsAlgorithms to StandardSecureDigestAlgorithms to retain the JDK 'Standard*' convention.

* Removed Algorithms class in favor of direct `Standard*` `Registry` references in `Jwts` and `Jwks` helper classes to keep the references 'close' to where they are used the most.

* Minor README.md documentation updates.

* Copying over 6e74486 to test on the jwe branch

* Ensured CI license-check build pulls full (non-shallow) git history to perform full year checks.

* JavaDoc + impl + test checkpoint

* JavaDoc + impl + test checkpoint. Returned to 100% code coverage

* JavaDoc + impl + test checkpoint. Returned to 100% code coverage

* - Ensured Edwards Curve keys (X25519 and X448) worked with ECDH-ES algorithms
- Ensured JWT Header ephemeral PublicKey ('epk' field) could be any Public JWK, not just an EcPublicJwk
- Updated README.md to ensure the installation instructions for uncommenting BouncyCastle were a little less confusing (having commented out stuff be at the end of the code block so it couldn't be confused with other lines)

* Ensured correct message assertion on all JDKs (value was different on JDK 15 and later)

* Ensured correct message assertion on all JDKs (value was different on JDK 15 and later)

* - enabled more IANA algorithms in StandardHashAlgorithms
- JavaDoc update

* - JavaDoc fixes/enhancements
- Fixed erroneous README.md method name reference
- ensured DefaultJwkContext#getName() supports Octet keys as well.

* - JavaDoc fixes/enhancements

* - JavaDoc fixes/enhancements required to pass the build on later JDKs

* Minor JavaDoc typo fix

* Finished implementing all [RFC 8037](https://www.rfc-editor.org/rfc/rfc8037) test vectors in the Appendix

* Removed accidentally-committed visibility modifier

* Added copyright header

* Enabled PublicKey derivation from Edwards curve PrivateKey

* Enabled PublicKey derivation from Edwards curve PrivateKey.  Updated documentation and code example showing this.

* Enabled PublicKey derivation from Edwards curve PrivateKey.  Updated documentation and code example showing this.

* Doc update to reference Octet JWK RFC.

* Minor JavaDoc fix

* Fixed OctetPrivateJwk discrepancy with generic parameter ordering (compared to other PrivateJwk interfaces)

* Changed Jwts.header to Jwts.unprotectedHeader, and Jwts.headerBuilder is now Jwts.header

---------

Co-authored-by: sonatype-lift[bot] <37194012+sonatype-lift[bot]@users.noreply.github.com>
Co-authored-by: Brian Demers <bdemers@apache.org>
  • Loading branch information
3 people committed May 18, 2023
1 parent c260e55 commit 760c542
Show file tree
Hide file tree
Showing 616 changed files with 46,485 additions and 6,409 deletions.
23 changes: 22 additions & 1 deletion .github/workflows/ci.yml
Expand Up @@ -73,6 +73,27 @@ jobs:
if [ "$JDK_MAJOR_VERSION" == "7" ]; then export MAVEN_OPTS="-Xmx512m -XX:MaxPermSize=128m"; fi
${{env.MVN_CMD}} verify -Possrh -Dgpg.skip=true
# ensure all of our files have the correct/updated license header
license-check:
runs-on: 'ubuntu-latest'
env:
MVN_CMD: ./mvnw --no-transfer-progress -B
steps:
- uses: actions/checkout@v3
with:
fetch-depth: 0 # avoid license plugin history warnings (plus it needs full history)
- name: Set up JDK
uses: actions/setup-java@v3
with:
distribution: 'zulu'
java-version: '8'
cache: 'maven'
check-latest: true
- name: License Check
# This adds about 1 minute to any build, which is why we don't want to do it on every other build:
run: |
${{env.MVN_CMD}} license:check
code-coverage:
# (commented out for now - see the comments in 'Wait to start' below for why. Keeping this here as a placeholder
# as it may be better to use instead of an artificial delay once we no longer need to build on JDK 7):
Expand Down Expand Up @@ -107,4 +128,4 @@ jobs:
${{env.MVN_CMD}} -pl . clover:clover clover:check coveralls:report \
-DrepoToken="${{ secrets.GITHUB_TOKEN }}" \
-DserviceName=github \
-DserviceBuildNumber="${{ env.GITHUB_RUN_ID }}"
-DserviceBuildNumber="${{ env.GITHUB_RUN_ID }}"
1 change: 0 additions & 1 deletion .gitignore
@@ -1,4 +1,3 @@
*.class
.DS_Store

# Mobile Tools for Java (J2ME)
Expand Down
23 changes: 20 additions & 3 deletions .lift/config.toml
@@ -1,4 +1,21 @@
ignoreRules = ["MissingOverride"]
ignoreFiles = '''
#
# Copyright © 2022 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.
#

ignoreRules = ["MissingOverride", "MissingSummary", "InconsistentCapitalization", "JavaUtilDate", "TypeParameterUnusedInFormals", "JavaLangClash", "InlineFormatString"]
ignoreFiles = """
impl/**
**/test/**
'''
"""
211 changes: 209 additions & 2 deletions CHANGELOG.md
Expand Up @@ -2,8 +2,215 @@

### JJWT_RELEASE_VERSION

* Adds a simplified "starter" jar that automatically pulls in `jjwt-api`, `jjwt-impl` and `jjwt-jackson`, useful when
upgrading from the older `io.jsonwebtoken:jjwt:*` to the project's current flexible module structure.
This is a big release! JJWT now fully supports Encrypted JSON Web Tokens (JWE) and JSON Web Keys (JWK)! See the
sections below enumerating all new features as well as important notes on breaking changes or backwards-incompatible
changes made in preparation for the upcoming 1.0 release.

#### Simplified Starter Jar

Those upgrading to new modular JJWT versions from old single-jar versions will transparently obtain everything
they need in their Maven, Gradle or Android projects.

JJWT's early releases had one and only one .jar: `jjwt.jar`. Later releases moved to a modular design with 'api' and
'impl' jars including 'plugin' jars for Jackson, GSON, org.json, etc. Some users upgrading from the earlier single
jar to JJWT's later versions have been frustrated by being forced to learn how to configure the more modular .jars.

This release re-introduces the `jjwt.jar` artifact again, but this time it is simply an empty .jar with Maven
metadata that will automatically transitively download the following into a project, retaining the old single-jar
behavior:
* `jjwt-api.jar`
* `jjwt-impl.jar`
* `jjwt-jackson.jar`

Naturally, developers are still encouraged to configure the modular .jars as described in JJWT's documentation for
greater control and to enable their preferred JSON parser, but this stop-gap should help those unaware when upgrading.

#### JSON Web Encryption (JWE) Support!

This has been a long-awaited feature for JJWT, years in the making, and it is quite extensive - so many encryption
algorithms and key management algorithms are defined by the JWA specification, and new API concepts had to be
introduced for all of them, as well as extensive testing with RFC-defined test vectors. The wait is over!
All JWA-defined encryption algorithms and key management algorithms are fully implemented and supported and
available immediately. For example:

```java
AeadAlgorithm enc = Jwts.ENC.A256GCM;
SecretKey key = enc.keyBuilder().build();
String compact = Jwts.builder().setSubject("Joe").encryptWith(key, enc).compact();

Jwe<Claims> jwe = Jwts.parserBuilder().decryptWith(key).build().parseClaimsJwe(compact);
```

Many other RSA and Elliptic Curve examples are in the full README documentation.

#### JSON Web Key (JWK) Support!

Representing cryptographic keys - SecretKeys, RSA Public and Private Keys, Elliptic Curve Public and
Private keys - as fully encoded JSON objects according to the JWK specification - is now fully implemented and
supported. The new `Jwks` utility class exists to create JWK builders and parsers as desired. For example:

```java
SecretKey key = Jwts.SIG.HS256.keyBuilder().build();
SecretJwk jwk = Jwks.builder().forKey(key).build();
assert key.equals(jwk.toKey());

// or if receiving a JWK string:
Jwk<?> parsedJwk = Jwks.parser().build().parse(jwkString);
assert jwk.equals(parsedJwk);
assert key.equals(parsedJwk.toKey());
```

Many JJWT users won't need to use JWKs explicitly, but some JWA Key Management Algorithms (and lots of RFC test
vectors) utilize JWKs when transmitting JWEs. As this was required by JWE, it is now implemented in full for
JWE use as well as general-purpose JWK support.

#### Better PKCS11 and Hardware Security Module (HSM) support

Previous versions of JJWT enforced that Private Keys implemented the `RSAKey` and `ECKey` interfaces to enforce key
length requirements. With this release, JJWT will still perform those checks when those data types are available,
but if not, as is common with keys from PKCS11 and HSM KeyStores, JJWT will still allow those Keys to be used,
expecting the underlying Security Provider to enforce any key requirements. This should reduce or eliminate any
custom code previously written to extend JJWT to use keys from those KeyStores or Providers.

#### Custom Signature Algorithms

The `io.jsonwebtoken.SignatureAlgorithm` enum has been deprecated in favor of new
`io.jsonwebtoken.security.SecureDigestAlgorithm`, `io.jsonwebtoken.security.MacAlgorithm`, and
`io.jsonwebtoken.security.SignatureAlgorithm` interfaces to allow custom algorithm implementations. The new
`SIG` constant in the `Jwts` helper class is a registry of all standard JWS algorithms as expected, exactly like the
old enum. This change was made because enums are a static concept by design and cannot
support custom values: those who wanted to use custom signature algorithms could not do so until now. The new
interface now allows anyone to plug in and support custom algorithms with JJWT as desired.

#### KeyBuilder and KeyPairBuilder

Because the `io.jsonwebtoken.security.Keys#secretKeyFor` and `io.jsonwebtoken.security.Keys#keyPairFor` methods
accepted the now-deprecated `io.jsonwebtoken.SignatureAlgorithm` enum, they have also been deprecated in favor of
calling new `keyBuilder()` or `keyPairBuilder()` methods on `MacAlgorithm` and `SignatureAlgorithm` instances directly.
For example:

```java
SecretKey key = Jwts.SIG.HS256.keyBuilder().build();
KeyPair pair = Jwts.SIG.RS256.keyPairBuilder().build();
```

The builders allow for customization of the JCA `Provider` and `SecureRandom` during Key or KeyPair generation if desired, whereas
the old enum-based static utility methods did not.

#### Preparation for 1.0

Now that the JWE and JWK specifications are implemented, only a few things remain for JJWT to be considered at
version 1.0. We have been waiting to apply the 1.0 release version number until the entire set of JWT specifications
are fully supported and we drop JDK 7 support (to allow users to use JDK 8 APIs). To that end, we have had to
deprecate some concepts, or in some rare cases, completely break backwards compatibility to ensure the transition to
1.0 (and JDK 8 APIs) are possible. Any backwards-incompatible changes are listed in the next section below.

#### Backwards Compatibility Breaking Changes, Warnings and Deprecations

* `io.jsonwebtoken.Jwts`'s `header(Map)`, `jwsHeader()` and `jwsHeader(Map)` methods have been deprecated in favor
of the new `header()` builder-based method to support method chaining and dynamic Header type creation.


* `io.jsonwebtoken.Jwt`'s `getBody()` method has been deprecated in favor of a new `getPayload()` method to
reflect correct JWT specification nomenclature/taxonomy.


* `io.jsonwebtoken.CompressionCodec` now inherits a new `io.jsonwebtoken.Identifiable` interface and its `getId()`
method is preferred over the now-deprecated `getAlgorithmName()` method. This is to guarantee API congruence with
all other JWT-identifiable algorithm names that can be set as a header value.


* `io.jsonwebtoken.Header` has been changed to accept a type-parameter for sub-type method return values, i.e.
`io.jsonwebtoken.Header<T extends Header>` and a new `io.jsonwebtoken.UnprotectedHeader` interface has been
introduced to represent the concrete type of header without integrity protection. This new `UnprotectedHeader` is
to be used where the previous generic `Header` (non-`JweHeader` and non-`JwsHeader`) interface was used.


* Accordingly, the `Jwts.header()` and `Jwts.header(Map<String,?>)` now return instances of `UnprotectedHeader` instead
of just `Header`.


#### Breaking Changes

* **JWTs that do not contain JSON Claims now have a payload type of `byte[]` instead of `String`** (that is,
`Jwt<byte[]>` instead of `Jwt<String>`). This is because JWTs, especially when used with the
`cty` (Content Type) header, are capable of handling _any_ type of payload, not just Strings. The previous JJWT
releases didn't account for this, and now the API accurately reflects the JWT RFC specification payload
capabilities. Additionally, the name of `plaintext` has been changed to `content` in method names and JavaDoc to
reflect this taxonomy. This change has impacted the following JJWT APIs:

* The `JwtBuilder`'s `setPayload(String)` method has been deprecated in favor of two new methods:

* `setContent(byte[])`, and
* `setContent(byte[], String contentType)`

These new methods allow any kind of content
within a JWT, not just Strings. The existing `setPayload(String)` method implementation has been changed to
delegate to this new `setContent(byte[])` method with the argument's UTF-8 bytes, for example
`setContent(payloadString.getBytes(StandardCharsets.UTF_8))`.

* The `JwtParser`'s `Jwt<Header, String> parsePlaintextJwt(String plaintextJwt)` and
`Jws<String> parsePlaintextJws(String plaintextJws)` methods have been changed to
`Jwt<UnprotectedHeader, byte[]> parseContentJwt(String plaintextJwt)` and
`Jws<byte[]> parseContentJws(String plaintextJws)` respectively.

* `JwtHandler`'s `onPlaintextJwt(String)` and `onPlaintextJws(String)` methods have been changed to
`onContentJwt(byte[])` and `onContentJws(byte[])` respectively.

* `io.jsonwebtoken.JwtHandlerAdapter` has been changed to reflect the above-mentioned name and `String`-to-`byte[]`
argument changes, as well adding the `abstract` modifier. This class was never intended
to be instantiated directly, and is provided for subclassing only. The missing modifier has been added to ensure
the class is used as it had always been intended.

* `io.jsonwebtoken.SigningKeyResolver`'s `resolveSigningKey(JwsHeader, String)` method has been changed to
`resolveSigningKey(JwsHeader, byte[])`.

* `io.jsonwebtoken.Jwts`'s `parser()` method deprecated 4 years ago has been renamed to `legacyParser()` to
allow an updated `parser()` method to return a `JwtParserBuilder` instead of a direct `JwtParser` instance.
This `legacyParser()` method will be removed entirely for the 1.0 release - please change your code to use the
updated `parser()` method that returns a builder as soon as possible.

* `io.jsonwebtoken.Jwts`'s `header()` method has been renamed to `unprotectedHeader()` to allow a newer/updated
`header()` method to return a `DynamicHeaderBuilder` instead of a direct `Header` instance. This new method /
return value is the recommended approach for building headers, as it will dynamically create an `UnprotectedHeader`,
`JwsHeader` or `JweHeader` automatically based on builder state.

* `io.jsonwebtoken.Jwts`'s `headerBuilder()` method has been renamed to `header()` and returns a
`DynamicHeaderBuilder` instead of a direct `Header` instance. This builder method is the recommended approach
for building headers in the future, as it will dynamically create an `UnprotectedHeader`, `JwsHeader` or `JweHeader`
automatically based on builder state.

* `io.jsonwebtoken.Jwts`'s `header()` method now returns a `DynamicHeaderBuilder` instead of a
direct `Header` instance. This new method / return value is the recommended approach for building headers
in the future, as it will dynamically create an `UnprotectedHeader`, `JwsHeader` or `JweHeader` automatically
based on builder state.

* Prior to this release, if there was a serialization problem when serializing the JWT Header, an `IllegalStateException`
was thrown. If there was a problem when serializing the JWT claims, an `IllegalArgumentException` was
thrown. This has been changed up to ensure consistency: any serialization error with either headers or claims
will now throw a `io.jsonwebtoken.io.SerializationException`.


* Parsing of unsecured JWTs (`alg` header of `none`) are now disabled by default as mandated by
[RFC 7518, Section 3.6](https://www.rfc-editor.org/rfc/rfc7518.html#section-3.6). If you require parsing of
unsecured JWTs, you must call the `enableUnsecuredJws` method on the `JwtParserBuilder`, but note the security
implications mentioned in that method's JavaDoc before doing so.


* `io.jsonwebtoken.gson.io.GsonSerializer` now requires `Gson` instances that have a registered
`GsonSupplierSerializer` type adapter, for example:
```java
new GsonBuilder()
.registerTypeHierarchyAdapter(io.jsonwebtoken.lang.Supplier.class, GsonSupplierSerializer.INSTANCE)
.disableHtmlEscaping().create();
```
This is to ensure JWKs have `toString()` and application log safety (do not print secure material), but still
serialize to JSON correctly.

* `io.jsonwebtoken.InvalidClaimException` and it's two subclasses (`IncorrectClaimException` and `MissingClaimException`)
were previously mutable, allowing the corresponding claim name and claim value to be set on the exception after
creation. These should have always been immutable without those setters (just getters), and this was a previous
implementation oversight. This release has ensured they are immutable without the setters.

### 0.11.5

Expand Down

0 comments on commit 760c542

Please sign in to comment.