Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

If you have a requirement to sign the data and then encrypt the signed payload then it can be easily achieved by selecting a required JWS Producer and creating a JWS Compact sequence, and next submitting this sequence to a JWE producer, and processing it all in the reverse sequence

JOSE JAX-RS Filters

 

While working directly with JWS

...

JWE

...

and JWE providers may be needed in the application code, JAX-RS users writing the code like this:

Code Block
languagejava
titleTypical JAX-RS code
@Path("/bookstore")
public class BookStore {
    
    public BookStore() {
    }
    
    @POST
    @Path("/books")
    @Produces("text/plain")
    @Consumes("text/plain")
    public String echoText(String text) {
        return text;
    }
    
    @POST
    @Path("/books")
    @Produces("application/json")
    @Consumes("application/json")
    public Book echoBook(Book book) {
        return book;
    }
}

would expect JWS and/or JWE processing done before the resource method is invoked or after this method returned some response.

This is what CXF JOSE JAX-RS filters do, they help the client or server code get the application data JWS- or JWE-secured. The filters do it by loadng the configuration properties as described below in the Configuration section, and produce or consume JWS or JWE sequences.

Note, JWS Compact and JSON, as well as JWE Compact client and server output filters do the best effort at keeping the streaming process going while they are signing or encrypting the payload. JWE JSON client/server output filter and JWS Compact client/server input filters will be enhanced in due time to support the streaming too. Most of CXF JOSE system tests enable the streaming capable filters to stream by default, however this can be disabled.  

JWS and JWE JSON input filters are expected to process JSON containers with the properties set in a random order hence by default they wil not stream the data in.  

Register both JWS and JWE out filters if the data need to be signed and encrypted (the filters are ordered such that the data are signed first and encrypted next) and JWS and JWE in filters if the signed data need to be decrypted first and then verified.

JWS Compact

JwsWriterInterceptor creates compact JWS sequences on the client or server out directions. For example, if you have the client code posting a Book or the server code returning a Book, with this Book representation expected to be signed, then add JwsWriterInterceptor and set the signature properties on the JAX-RS client or server.

JwsClientResponseFilter and JwsContainerRequestFilter process the incoming client or server Compact JWS sequences.

 

JwsJsonWriterInterceptor creates JWS JSON sequences on the client or server out directions. 

JwsJsonClientResponseFilter and JwsJsonContainerRequestFilter process the incoming client or server Compact JWS sequences.

JWE

JweWriterInterceptor creates Compact JWE sequences on the client or server out directions. For example, if you have the client code posting a Book or the server code returning a Book, with this Book representation expected to be encrypted, then add JweWriterInterceptor and set the encryption properties on the JAX-RS client or server.

JweClientResponseFilter and JweContainerRequestFilter process the incoming client or server Compact JWE sequences.

 

JweJsonWriterInterceptor creates JWE JSON sequences on the client or server out directions. 

JweJsonClientResponseFilter and JweContainerRequestFilter process the incoming client or server JWE JSON sequences.

 

Linking JWT authentications to JWS or JWE content

CXF introduced a "JWT" HTTP authentication scheme, with a Base64Url encoded JWT token representing a user authentication against an IDP capable of issuing JWT assertions (or simply JWT tokens). JWT assertion is like SAML assertion except that it is in a JSON format. If you'd like to cryptographically bind this JWT token to a data secured by JWS and/or JWE processors then simply add JwtAuthenticationClientFilteron the client side and JwtAuthenticationFilter on the server side. These filters link the authentication token with a randomly generated secure value which is added to both the token and the body JWS/JWE protected headers.

This approach is more effective compared to the ones where the body hash is calculated before it is submitted to a signature creation function, with the signature added as HTTP header.

 

 

Configuration

CXF JOSE configuration provides for loading JWS and JWE keys and supporting various processing options. Configuration properties can be shared between JWS and JWE processors or in/out only JWS and or JWE properties can be set.

...

rs.security.encryption.out.properties

The encryption properties file for Compact or JSON encryption creation. If not specified then it falls back to "rs.security.encryption.properties".

rs.security.encryption.in.properties

The encryption properties file for Compact or JSON decryption. If not specified then it falls back to "rs.security.encryption.properties".

rs.security.encryption.propertiesThe signature properties file for encryption/decryption.

 Note that these property containers can be used for creating/processing JWS and JWE Compact and JSON sequences. If it is either JWS JSON or JWE JSON and you wish to have more than one signature or encryption be created then let the property value be a commas separated list of locations, with each location pointing to a unique signature or encryption operation property file.

Once the properties are loaded the runtime proceeds with initializing JWS/JWE providers accordingly. The following section lists the properties, some oif them being common and some - unique to the signature/verification and encryption/decryption processes.

...

rs.security.decryption.key.password.provider

A reference to a PrivateKeyPasswordProvider instance used to retrieve passwords to access keys for decryption. If this is not specified it falls back to use "rs.security.key.password.provider".

rs.security.encryption.content.algorithmThe encryption content algorithm to use. The default algorithm if not specified is 'A128GCM'.
rs.security.encryption.key.algorithm

The encryption key algorithm to use. The default algorithm if not specified is 'RSA-OAEP' if the key is an RSA key, and 'A128GCMKW' if it is an octet sequence.

rs.security.encryption.zip.algorithmThe encryption zip algorithm to use.
rs.security.encryption.include.public.keyInclude the JWK public key for encryption in the "jwk" header.
rs.security.encryption.include.certInclude the X.509 certificate for encryption in the "x5c" header.
rs.security.encryption.include.key.idInclude the JWK key id for encryption in the "kid" header.
rs.security.encryption.include.cert.sha1Include the JWK key id X.509 certificate SHA-1 digest for encryption in the "kidx5t" header.

Configuration that applies to JWT tokens only

encryption.include.cert.sha1

rs.security.enable.

Include the X.509 certificate SHA-1 digest for encryption in the "x5t" header.

Configuration that applies to JWT tokens only

rs.security.enable.unsigned-jwt.principal

Whether to allow unsigned JWT tokens as SecurityContext Principals. The default is false.

...

unsigned-jwt.principal

Whether to allow unsigned JWT tokens as SecurityContext Principals. The default is false.

Interoperability

 

JOSE is already widely supported in OAuth2 and OIDC applications. Besides that CXF JOSE client or server will interoperate with a 3rd party client/server able to produce or consume JWS/JWE sequences.  For example, see the following WebCrypto API use case, the following demo demonstrates how a JWS sequence produced by a browser-hosted script can be validated by a server application capable of processing JWS, with the demo browser client being tested against a CXF JWS server too. 

 

Third-Party Libraries

Jose4J

Nimbus JOSE