Introduction

JOSE is a set of high quality specifications that specify how data payloads can be signed/validated and/or encrypted/decrypted with the cryptographic properties set in the JSON-formatted metadata (headers). The data to be secured can be in JSON or other format (plain text, XML, binary data).

JOSE is a key piece of the advanced OAuth2-based applications such as OpenIdConnect but can also be successfully used for securing the regular HTTP web service communications.

CXF 3.1.x and 3.2.0 provides a complete implementation of JOSE.

Maven Dependencies

Having the following dependency will let the developers write JOSE code: creating and securing JSON Web Tokens (JWT), and securing the arbitrary data (not only JSON)

<dependency>
  <groupId>org.apache.cxf</groupId>
  <artifactId>cxf-rt-rs-security-jose</artifactId>
  <version>3.1.7</version>
</dependency>

Having the following dependency will let the developers use JAX-RS JOSE filters which will transparently sign and/or encrypt the data streams, and decrypt or/and validate the incoming JOSE sequences and make the original data available for the processing.

<dependency>
  <groupId>org.apache.cxf</groupId>
  <artifactId>cxf-rt-rs-security-jose-jaxrs</artifactId>
  <version>3.1.7</version>
</dependency>

You may also need to include Bouncy Castle:

<dependency>
     <groupId>org.bouncycastle</groupId>
     <artifactId>bcprov-ext-jdk15on</artifactId>
     <version>1.54</version>
</dependency>

Java and JCE Policy 

Java7 or higher is recommended for most cases: Java6 does not support JWE AES-GCM at all while with BouncyCastle it is not possible to submit JWE Header properties as an extra input to the encryption process to get them integrity protected which is not JWE compliant.

Unlimited JCE Policy for Java 7/8/9 needs to be installed if the size of the encrypting key is 256 bits (example, JWE A256GCM).

JOSE Overview and Implementation

JOSE consists of the following key parts:

• JWA - JSON Web Algorithms where all supported signature and encryption algorithms are listed
• JWK - JSON Web Keys - introduces a JSON format for describing the public and private keys used by JWA algorithms
• JWS - JSON Web Signature - describes how the data can be signed or validated and introduces compact and JSON JWS formats for representing the signed data
• JWE - JSON Web Encryption - describes how the data can be encrypted or decrypted and introduces compact and JSON JWE formats for representing the encrypted data  

Additionally, JWT (JSON Web Token), while technically being not part of JOSE, is often used as an input material to JWS and JWE processors, especially in OAuth2 flows (example: OAuth2 access tokens can be represented internally as JWT, OpenIdConnect IdToken and UserInfo are effectively JWTs). JWT describes how a set of claims in JSON format can be either JWS-signed and/or JWE-enctypted. 

JWA Algorithms

All JOSE signature and encryption algorithms are grouped and described in the JWA (JSON Web Algorithms) specification.

The algorithms are split into 3 categories: signature algorithms (HMAC, RSA, Elliptic Curve), algorithms for supporting the encryption of content encryption keys (RSA-OAEP, AES Key Wrap, etc), and algorithms for encrypting the actual content (AES GCM, etc).

All JWS and JWE algorithms process not only the actual data but also the meta-data (the algorithm properties) thus ensuring the algorithm properties are integrity-protected, additionally JWE algorithms produce authentication tags which ensure the already encrypted content won't be manipulated.

Please refer to the specification to get all the information needed (with the follow up links to the corresponding RFC when applicable) about a particular signature or encryption algorithm: the properties, recommended key sizes, other security considerations related to all of or some specific algorithms. CXF JOSE code already enforces a number of the recommended constraints.

CXF offers the utility support for working with JWA algorithms in this package.

Typically one would supply an algorithm property in a type-safe way either to JWS or JWE processor, for example,  SignatureAlgorithm.HS256 for JWS, KeyAlgorithm.A256KW plus ContentAlgorithm.A256GCM for JWE, etc. Each enum has methods for checking a key size, JWA and Java JCA algorithm names.

JWK Keys

JWK (JSON Web Key) is a JSON document describing the cryptographic key properties. JWKs are very flexible and one can expect JWKs becoming one of the major mechanisms for representing and storing cryptographic keys. While one does not have to represent the keys as JWK in order to sign or encrypt the document and rely on Java JCA secret and asymmetric keys instead, JWK is a preferred representation of signature or encryption keys in JOSE.

For example:

{
   "kty":"oct",
   "k":"AyM1SysPpbyDfgZld3umj1qzKObwVMkoqQ-EstJQLr_T-1qS0gZH75aKtMN3Yj0iPS4hcgUuTwjAzZr1Z9CAow",
   "kid":"Secret HMAC key"
}

or

{
  "kty":"RSA",
  "n": "0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2aiAFbWhM78LhWx
     4cbbfAAtVT86zwu1RK7aPFFxuhDR1L6tSoc_BJECPebWKRXjBZCiFV4n3oknjhMs
     tn64tZ_2W-5JsGY4Hc5n9yBXArwl93lqt7_RN5w6Cf0h4QyQ5v-65YGjQR0_FDW2
     QvzqY368QQMicAtaSqzs8KJZgnYb9c7d0zgdAZHzu6qMQvRL5hajrn1n91CbOpbI
     SD08qNLyrdkt-bFTWhAI4vMQFh6WeZu0fM4lFd2NcRwr3XPksINHaQ-G_xBniIqb
     w0Ls1jF44-csFCur-kEgU8awapJzKnqDKgw",
  "e":"AQAB",
  "alg":"RS256",
  "kid":"Public RSA Key"}

A 'kid' property can be of special interest as it allows to identify a key but also help with the simple key rotation mechanism realized (ex, OIDC Asymmetric Key Rotation).

A collection of JWK keys is called a JWK Key Set which is represented as JSON array of JWKs.

CXF offers a utility support for reading and writing JWK keys and key sets and for working with the encrypted inlined and standalone JWK stores in this package.

For example, a key set containing public JWK keys can be seen here and referred to from the configuration properties. The private (test) key set can be represented in a clear form, though most likely you'd want a private key set encrypted and referred to like this. 

One can inline the encrypted key or the key set directly in the configuration properties. For example, here is how an encrypted single JWK key is inlined. Similarly, here is how an encrypted collection of keys is inlined.

CXF assumes that the JWK keys have been encrypted if a password provider is available in scope, it is typically registered with JAX-RS endpoints. The encryption is done with a password based PBES2 algorithm. 

Support for the pluggable strategies for loading JWKs is on the map.

For example, here is how you can load a JWK key using its 'kid':

InputStream is = JsonWebKeyTest.class.getResourceAsStream(fileName);
JsonWebKeys keySet = JwkUtils.readJwkSet(is);
JsonWebKey key = keySet.getKey("Public RSA Key");
String thumbprint = JwkUtils.getThumbprint(key);
assertEquals("NzbLsXh8uDCcd-6MNwXF4W_7noWXFZAfHkxZsRGC9Xs", thumbprint);
KeyType keyType = key.getKeyType();
assertEquals(KeyType.RSA, thumbprint);

JsonWebKeys also supports the retrieval of keys by their type (RSA, EC, Octet) and operation (ENCRYPT, SIGN, etc). 
Once you have JWK loaded it is typically submitted to JWS or JWE providers.

JWS Signature

JWS (JSON Web Signature) document describes how a document content can be signed. For example, Appendix A1 shows how the content can be signed with an HMAC key

CXF ships JWS related classes in this package and offers a support for all of JWA signature algorithms.

Signature and Verification Providers

JwsSignatureProvider supports signing the content, JwsSignatureVerifier - validating the signatures.

Note the signature and verification capabilities are represented by 2 different interfaces - it was done to keep the interfaces minimalistic and have the concerns separated which can be appreciated most in the cases where the code only signs or only validates.

The following table shows the algorithms and the corresponding providers (org.apache.cxf.rs.security.jose.jws package):

Either of these providers (except for None) can be initialized with the keys loaded from JWK or Java JKS stores or from the in-memory representations.

RS256/384/512 algorithms are likely to be used most often at the moment due to existing JKS stores being available everywhere and a relatively easy way of making the public validation keys available. 'None' algorithm might be useful when a JWS sequence is subsequently JWE-encrypted or when a 2-way TLS (with client and server certificates) is used.

Once you have decided which algorithm needs to be supported you can initialize an appropriate pair of JwsSignatureProvider and JwsSignatureVerifier if both signing the data and the verification are needed. If only the signing is needed - select JwsSignatureProvider, only the verification - select JwsSignatureVerifier. The selected providers are submitted directly or indirectly to JWS Compact or JWS JSON producers or consumers.

JWS Compact

JWS Compact representation is the most often used JOSE sequence. It is the concatenation of Base64URL-encoded sequence if JWS headers (algorithm and other properties),  Base64URL-encoded sequence of the actual data being protected and Base64URL-encoded sequence of the signature algorithm output bytes.

JwsCompactProducer and JwsCompactConsumer offer a support for producing and consuming compact JWS sequences, protecting the data in JSON or non-JSON formats.

JwsJwtCompactProducer and JwsJwtCompactConsumer are their simple extensions which help with processing typed JWT Tokens.

 For example, here is how an Appendix A1 example can be done in CXF:

JwtClaims claims = new JwtClaims();
claims.setIssuer("joe");
claims.setExpiryTime(1300819380L);
claims.setClaim("http://example.com/is_root", Boolean.TRUE);

JwsCompactProducer jwsProducer = new JwsJwtCompactProducer(claims);

// Sign
// Load HmacJwsSignatureProvider directly, see the next example for the alternative approach
String jwsSequence = jwsProducer.signWith(new HmacJwsSignatureProvider(ENCODED_MAC_KEY, SignatureAlgorithm.HS256));

// Validate
JwsJwtCompactConsumer jwsConsumer = new JwsJwtCompactConsumer(jwsSequence);

// Load HmacJwsSignatureVerifier directly, see the next example for the alternative approach
jwsConsumer.verifySignatureWith(new HmacJwsSignatureVerifier(ENCODED_MAC_KEY, SignatureAlgorithm.HS256)));

// Get the data
JwtClaims protectedClaims = jws.getJwtClaims();

In the above example, the data (JwtToken) is submitted to an instance of JwsCompactProducer (JwsJwtCompactProducer) and signed with an HMac key.

Here is another example:

JwsCompactProducer jwsProducer = new JwsCompactProducer("Hello World");

// Load private RSA key from the JWK Key set stored on the disk
InputStream is = JsonWebKeyTest.class.getResourceAsStream(fileName);
JsonWebKeys keySet = JwkUtils.readJwkSet(is);
JsonWebKey jwkPrivateRsaKey = keySet.getKey("Private RSA Key");

// Sign
String jwsSequence = jwsProducer.signWith(jwkPrivateRsaKey);

// Validate
JwsCompactConsumer jwsConsumer = new JwsCompactConsumer(jwsSequence);

// Load Public RSA Key from Java JKS Store
PublicKey publicRsaKey = CryptoUtils.loadPublicKey(keyStoreLocation, keyStorePassword, keyAlias, KeyStore.getDefaultType()); 

jws.verifySignatureWith(publicRsaKey);

// Get the data
String helloWorldString = jwsConsumer.getDecodedJwsPayload();

In this latest example a plain text sequence is encoded with a private RSA key loaded from the JWK store and validated with a public RSA key loaded from the existing Java JKS store.

JwsUtils utility class has a lot of helper methods to get JWS sequences created and validated.

JWS JSON

While JWS Compact is optimized and represents a concatenation of up to 3 Base64URL values, JWS JSON is an open JSON container, see Appendix 6.

The most interesting feature of JWS JSON is that allows a content be signed for multiple recipients. For example,  the immediate consumer will validate a signature with one key, forward the payload to the next consumer which will also validate the content with another key, etc.  

JwsJsonProducer and JwsJsonConsumer support producing and consuming JWS JSON sequences.

JwsJsonProducer producer = new JwsJsonProducer(UNSIGNED_PLAIN_JSON_DOCUMENT);
JwsHeaders headerEntries = new JwsHeaders(SignatureAlgorithm.HS256);
              
producer.signWith(new HmacJwsSignatureProvider(ENCODED_MAC_KEY_1, SignatureAlgorithm.HS256),
                  headerEntries);
producer.signWith(new HmacJwsSignatureProvider(ENCODED_MAC_KEY_2, SignatureAlgorithm.HS256),
                  headerEntries);
assertEquals(DUAL_SIGNED_JWS_JSON_DOCUMENT, producer.getJwsJsonSignedDocument());

JwsJsonConsumer consumer = new JwsJsonConsumer(DUAL_SIGNED_DOCUMENT); 

// Validate both signatures, see below how to validate and produce
JsonWebKeys jwks = readKeySet("jwkSet.txt");
        
List<JwsJsonSignatureEntry> sigEntries = consumer.getSignatureEntries();
assertEquals(2, sigEntries.size());

// 1st signature
String firstKid = (String)sigEntries.get(0).getKeyId();
JsonWebKey firstKey = jwks.getKey(firstKid);
assertTrue(sigEntries.get(0).verifySignatureWith(firstKey));
// 2nd signature
String secondKid = (String)sigEntries.get(1).getKeyId();
JsonWebKey secondKey = jwks.getKey(secondKid);
assertTrue(sigEntries.get(1).verifySignatureWith(secondKey));

// or if you wish to validate (ex with the firstKey loaded above) and forward it to the next consumer, do:
JwsSignatureProvider provider = JwsUtils.getSignatureProvider(firstKey);
String nextJwsJson = consumer.validateAndProduce(Collections.singletonList(provider));
// use WebClient to post nextJwsJson to the next consumer, with nextJwsJson being nearly identical to the original
// double-signed JWS JSON signature, minus the signature which was already validated, in this case nextJwsJson will 
// only have a single signature 

The above code produces a JWS JSON sequence containing two signatures, similarly to this example. If the sequence contains a single signature only then the JWS JSON 'signatures' array will contain a single 'signature' element, or the whole sequence can be flattened with the actual 'signatures' array dropped. JwsJsonProducer  does not produce the flattened sequence when only a single signature is used by default because 3rd party JWS JSON consumers may only be able to process the sequences with the 'signatures' array, so pass a 'supportFlattened' flag to JwsJsonProducer if needed. 

Does it make sense to use JWS JSON if you do not plan to do multiple signatures ? Indeed, if it is only a single signature then using JWS Compact is a good alternative, likely to be used most often.

However, even if you do a single signature, you may still want to try JWS JSON because is is easier to observe the individual JWS JSON structure parts when, example, checking the logs or TCP-tracing HTTP requests/responses. This is especially true when we start talking about an unencoded payload option, see below.

JWS with Detached Content

JWS with a Detached Content provides a way to integrity-protect some data without actually having these data included in the resulting JWS sequence.

For example, if the producer and consumer can both access the same shared piece of data, then the producer can sign these data, post the JWS sequence (without the data) to the consumer. The consumer will validate this JWS sequence and assert the data have not been modified by the time it has received and started validating the sequence. JWS Compact and JWS JSON Producer and Consumer provider constructors accept an optional 'detached' flag in cases were it is required.      

JWS with Unencoded Payload

By default, JWS Compact and JWS JSON sequences have the data first Base64Url encoded and then inlined in the resulting sequence. This is useful especially for JWS Compact which is used in OAuth2/OIDC  flows to represent the signed access or id tokens. 

One concern around the data being inlined is that it takes an extra time to Base64Url encode them which may become noticeable with large payloads, and another one is that one can not see the data while looking at JWS sequences in the logs or trace screens.

Thus a JWS with Unencoded Payload option (JWS header 'b64' property set to false) has been introduced to let users configure JWS Signature providers not to encode the actual data payload. As it happens it appears to be most useful when JWS JSON sequences are produced, see this example.

Note that JWS Compact also supports 'b64' property but only with the detached payloads. It is easier to appreciate the value of disabling Base64Url encoding with JWS JSON as seen in the example.

In CXF you can apply this option to both JWS Compact and JWS JSON sequences, here is a JWS JSON code fragment:

JwsJsonProducer producer = new JwsJsonProducer(UNSIGNED_PLAIN_JSON_DOCUMENT, true);
JwsHeaders headers = new JwsHeaders(SignatureAlgorithm.HS256);
headers.setPayloadEncodingStatus(false);
producer.signWith(new HmacJwsSignatureProvider(ENCODED_MAC_KEY_1, SignatureAlgorithm.HS256),
                  headers);

JWE Encryption

JWE (JSON Web Encryption) document describes how a document content, and, when applicable, a content encryption key, can be encrypted. For example, Appendix A1 shows how the content can be encrypted with a secret key using AesGcm with the actual content encryption key being encrypted using RSA-OAEP.

CXF ships JWE related classes in this package and offers a support for all of JWA key encryption and content encryption algorithms.

Key and Content Encryption Providers

JWE Encryption process typically involves a content-encryption key being generated with this key being subsequently encrypted/wrapped with a key known to the consumer. Thus CXF offers the providers for supporting the key-encryption algorithms and providers for supporting the content-encryption algorithms. Direct key encryption (where the content-encryption key is established out of band) is also supported.

KeyEncryptionProvider supports encrypting a content-encryption key, KeyDecryptionProvider - decrypting it.

The following table shows the key encryption algorithms and the corresponding providers (org.apache.cxf.rs.security.jose.jwe package):

RSA-OAEP algorithms are likely to be used most often at the moment due to existing JKS stores being available everywhere and a relatively easy way of making the public validation keys available.

ContentEncryptionProvider supports encrypting a generated content-encryption key, ContentDecryptionProvider - decrypting it.

The following table shows the content encryption algorithms and the corresponding providers:

All of the above providers can be initialized with the keys loaded from JWK or Java JKS stores or from the in-memory representations.

JWE Compact

JweEncryptionProvider supports encrypting the content, JweDecryptionProvider - decrypting the content. Encryptors and Decryptors for all of JWE algorithms are shipped.

Here is the example of doing AES CBC HMAC and AES Key Wrap in CXF:

final String specPlainText = "Live long and prosper.";
        
byte[] cekEncryptionKey = Base64UrlUtility.decode(KEY_ENCRYPTION_KEY_A3);
        
AesWrapKeyEncryptionAlgorithm keyEncryption = new AesWrapKeyEncryptionAlgorithm(cekEncryptionKey, KeyAlgorithm.A128KW);
JweEncryptionProvider encryption = new AesCbcHmacJweEncryption(ContentAlgorithm.A128CBC_HS256,
                                                               keyEncryption);
String jweContent = encryption.encrypt(specPlainText.getBytes("UTF-8"), null);
        
AesWrapKeyDecryptionAlgorithm keyDecryption = new AesWrapKeyDecryptionAlgorithm(cekEncryptionKey);
JweDecryptionProvider decryption = new AesCbcHmacJweDecryption(keyDecryption);
String decryptedText = decryption.decrypt(jweContent).getContentText();
assertEquals(specPlainText, decryptedText);

JWE JSON

JSON Web Token

JWT (JSON Web Token) is a collection of claims in JSON format. It offers a standard JSON container for representing various properties or claims.

JWT can be signed and or encrypted, i.e, serve as a JOSE signature or encryption input like any other data structure.

JWT has been primarily used in OAuth2 applications to represent self-contained access tokens but can also be used in other contexts.

CXF offers an initial JWT support in this package.

JOSE JAX-RS Filters

JWS

JWE

Linking JWT authentications to JWS or JWE content

Configuration

Configuration that applies to both encryption and signature

Configuration that applies to signature only

Configuration that applies to encryption only

Configuration that applies to JWT tokens only

OAuth2 and Jose

CXF OAuth2 module depends on its JOSE module. This will be used to support OAuth2 POP tokens. Authorization code JOSE requests can already be processed. Utility support for validating JWT-based access tokens is provided.

Add more...

OIDC and Jose

OIDC heavily depends on JOSE. CXF OIDC module utilizes a JOSE module to support OIDC RP and IDP code. Add more...

Future Work

OAuth2, WebCrypto, OIDC, etc

Third-Party Alternatives

Jose4J

Nimbus JOSE