...

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

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.

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"
}

...

{
  "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.

...

The following table shows the algorithms and the corresponding providers:

HmacJwsSignatureProvider

HmacJwsSignatureVerifier

Either of these providers (except for None) can be initialized with the keys loaded from JWK or JCA 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 usedEither of these providers (except for None) can be initialized with the keys loaded from JWK or JCA stores or from the in-memory representations.

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.

...

// Sign
// Algorithm properties are set in the headers
JoseHeaders headers = new JoseHeaders();
headers.setAlgorithm(SignatureAlgorithm.HS256);

// This is the actual data content, JWT in this case, but can be an arbitrary JSON or non-JSON data
JwtClaims claims = new JwtClaims();
claims.setIssuer("joe");
claims.setExpiryTime(1300819380L);
claims.setClaim("http://example.com/is_root", Boolean.TRUE);
JwtToken token = new JwtToken(headers, claims);

JwsCompactProducer jws = new JwsJwtCompactProducer(token);

jws.signWith(new HmacJwsSignatureProvider(ENCODED_MAC_KEY, SignatureAlgorithm.HS256));
assertEquals(ENCODED_TOKEN_SIGNED_BY_MAC, jws.getSignedEncodedJws());

// validate
JwsJwtCompactConsumer jws = new JwsJwtCompactConsumer(ENCODED_TOKEN_SIGNED_BY_MAC);
assertTrue(jws.verifySignatureWith(new HmacJwsSignatureVerifier(ENCODED_MAC_KEY,
                                      SignatureAlgorithm.HS256)));
JwtToken token = jws.getJwtToken();
JoseHeaders headers = token.getHeaders();
assertEquals(SignatureAlgorithm.HS256, headers.getAlgorithm());
validateClaims(token.getClaims());

JWS JSON

JWS with Detached Content

JWS with Clear Payload

JWE Encryption

...

The following table shows the key encryption algorithms and the corresponding providersprov,iders:

RSA1_5

RSAKeyEncryptionAlgorithm

RSAKeyDecryptionAlgorithm

RSA-OAEP, RSA-OAEP-256

A128KW, A192KW, A256KW

ECDH-ES+A128KW (+A192KW, +256KW)

ECDH-ES

A128GCMKW, A192GCMKW, A256GCMKW

PBES2-HS256+A128KW 

PBES2-HS384+A192KW

PBES2-HS512+A256KW 

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:

A128CBC-HS256(-HS384, -HS512)

AesCbcHmacJweEncryption,

AesCbcHmacJweDecryption

A128GCM, A92GCM, A256GCM

...