Author: buildbot Date: Tue May 24 12:47:34 2016 New Revision: 989035 Log: Production update by buildbot for cxf
Modified: websites/production/cxf/content/cache/docs.pageCache websites/production/cxf/content/docs/jax-rs-jose.html Modified: websites/production/cxf/content/cache/docs.pageCache ============================================================================== Binary files - no diff available. Modified: websites/production/cxf/content/docs/jax-rs-jose.html ============================================================================== --- websites/production/cxf/content/docs/jax-rs-jose.html (original) +++ websites/production/cxf/content/docs/jax-rs-jose.html Tue May 24 12:47:34 2016 @@ -119,11 +119,11 @@ Apache CXF -- JAX-RS JOSE <!-- Content --> <div class="wiki-content"> <div id="ConfluenceContent"><p> </p><p> </p><p><style type="text/css">/*<![CDATA[*/ -div.rbtoc1464090423757 {padding: 0px;} -div.rbtoc1464090423757 ul {list-style: disc;margin-left: 0px;} -div.rbtoc1464090423757 li {margin-left: 0px;padding-left: 0px;} +div.rbtoc1464094020290 {padding: 0px;} +div.rbtoc1464094020290 ul {list-style: disc;margin-left: 0px;} +div.rbtoc1464094020290 li {margin-left: 0px;padding-left: 0px;} -/*]]>*/</style></p><div class="toc-macro rbtoc1464090423757"> +/*]]>*/</style></p><div class="toc-macro rbtoc1464094020290"> <ul class="toc-indentation"><li><a shape="rect" href="#JAX-RSJOSE-Introduction">Introduction</a></li><li><a shape="rect" href="#JAX-RSJOSE-MavenDependencies">Maven Dependencies</a></li><li><a shape="rect" href="#JAX-RSJOSE-JavaandJCEPolicy">Java and JCE Policy </a></li><li><a shape="rect" href="#JAX-RSJOSE-JOSEOverviewandImplementation">JOSE Overview and Implementation</a> <ul class="toc-indentation"><li><a shape="rect" href="#JAX-RSJOSE-JWAAlgorithms">JWA Algorithms</a></li><li><a shape="rect" href="#JAX-RSJOSE-JWKKeys">JWK Keys</a></li><li><a shape="rect" href="#JAX-RSJOSE-JWSSignature">JWS Signature</a> <ul class="toc-indentation"><li><a shape="rect" href="#JAX-RSJOSE-SignatureandVerificationProviders">Signature and Verification Providers</a></li><li><a shape="rect" href="#JAX-RSJOSE-JWSCompact">JWS Compact</a></li><li><a shape="rect" href="#JAX-RSJOSE-JWSJSON">JWS JSON</a></li><li><a shape="rect" href="#JAX-RSJOSE-JWSwithDetachedContent">JWS with Detached Content</a></li><li><a shape="rect" href="#JAX-RSJOSE-JWSwithUnencodedPayload">JWS with Unencoded Payload</a></li></ul> @@ -375,7 +375,7 @@ public class BookStore { return book; } }</pre> -</div></div><p>would expect JWS and/or JWE processing done before the resource method is invoked or after this method returned some response.</p><p>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.</p><p>Note, JWS Compact and JSON, as well as JWE Compact client and server output filters can do the best effort at keeping the <strong>streaming</strong> 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.  </p><p>JWS and JWE JSON input filters are expected to process JSON containers with the properties set in a random order hence by def ault they wil not stream the data in.  </p><p>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.</p><h2 id="JAX-RSJOSE-JWS">JWS</h2><p><a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/jose-parent/jose-jaxrs/src/main/java/org/apache/cxf/rs/security/jose/jaxrs/JwsWriterInterceptor.java" rel="nofollow">JwsWriterInterceptor</a> 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 <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/jose-parent/jose-jaxrs/src/main/java/org/apache/cxf/rs/security/jose/jaxrs/JwsW riterInterceptor.java" rel="nofollow">JwsWriterInterceptor</a> and set the signature properties on the JAX-RS client or server.</p><p><a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/jose-parent/jose-jaxrs/src/main/java/org/apache/cxf/rs/security/jose/jaxrs/JwsClientResponseFilter.java" rel="nofollow">JwsClientResponseFilter</a> and <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/jose-parent/jose-jaxrs/src/main/java/org/apache/cxf/rs/security/jose/jaxrs/JwsContainerRequestFilter.java" rel="nofollow">JwsContainerRequestFilter</a> process the incoming client or server Compact JWS sequences.</p><p>Here is an example of a JSON Book representation being signed and converted into  Compact JWS and POSTed to the target service:</p><div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent"> +</div></div><p>would expect JWS and/or JWE processing done before the resource method is invoked or after this method returned some response.</p><p>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.</p><p>Note, JWS Compact and JSON, as well as JWE Compact client and server output filters can do the best effort at keeping the <strong>streaming</strong> 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.  </p><p>JWS and JWE JSON input filters are expected to process JSON containers with the properties set in a random order hence by def ault they wil not stream the data in.  </p><p>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.</p><h2 id="JAX-RSJOSE-JWS">JWS</h2><p><a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/jose-parent/jose-jaxrs/src/main/java/org/apache/cxf/rs/security/jose/jaxrs/JwsWriterInterceptor.java" rel="nofollow">JwsWriterInterceptor</a> 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 <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/jose-parent/jose-jaxrs/src/main/java/org/apache/cxf/rs/security/jose/jaxrs/JwsW riterInterceptor.java" rel="nofollow">JwsWriterInterceptor</a> and set the signature properties on the JAX-RS client or server.</p><p><a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/jose-parent/jose-jaxrs/src/main/java/org/apache/cxf/rs/security/jose/jaxrs/JwsClientResponseFilter.java" rel="nofollow">JwsClientResponseFilter</a> and <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/jose-parent/jose-jaxrs/src/main/java/org/apache/cxf/rs/security/jose/jaxrs/JwsContainerRequestFilter.java" rel="nofollow">JwsContainerRequestFilter</a> process the incoming client or server Compact JWS sequences.</p><p>Here is an example of a JSON Book representation being HS256 signed and converted into  Compact JWS and POSTed to the target service:</p><div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent"> <pre>Address: https://localhost:9001/jwsjwkhmac/bookstore/books Http-Method: POST Content-Type: application/jose @@ -384,11 +384,11 @@ eyJhbGciOiJIUzI1NiIsImN0eSI6Impzb24ifQ. eyJCb29rIjp7ImlkIjoxMjMsIm5hbWUiOiJib29rIn19. hg1T41ESuX6JvRR--huTA3HnbrsdIZSwkxQdyWj9j6c -May 24, 2016 10:53:32 AM org.apache.cxf.rs.security.jose.common.JoseUtils traceHeaders +org.apache.cxf.rs.security.jose.common.JoseUtils traceHeaders INFO: JWS Headers: {"alg":"HS256", "cty":"json"}</pre> -</div></div><p> </p><p>You can see 3 JWS parts (put on separate lines for the better readibility) separated by dots. The 1st part is Base64Url encoded protected headers, next one - Base64Url encoded Book JSON payload, finally - the signature. Note that the protected headers can be traced by enabling a "jose.debug" contextual property.</p><p>The following client code can be used to set the client JOSE interceptors:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>Client JWS SetUp</b></div><div class="codeContent panelContent pdl"> +</div></div><p> </p><p>You can see 3 JWS parts (put on separate lines for the better readibility) separated by dots. The 1st part is Base64Url encoded protected headers, next one - Base64Url encoded Book JSON payload, finally - the signature.</p><p>Note that the protected headers can be traced by enabling a "jose.debug" contextual property: once can see the signature algorithm is "HS256" and the content type of the signed payload is "json" which is a shorcut for a content type "application/json" where "application" is omitted.</p><p>The following client code can be used to set the client JWS Compact interceptors:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>Client JWS SetUp</b></div><div class="codeContent panelContent pdl"> <pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;"> public void testJwsJwkBookHMac() throws Exception { String address = "https://localhost:" + PORT + "/jwsjwkhmac"; BookStore bs = createJwsBookStore(address); @@ -420,32 +420,84 @@ INFO: JWS Headers: return bean.create(BookStore.class); }</pre> -</div></div><p>The above code shows a client proxy code but WebClient can be created instead. The server is configured <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/systests/rs-security/src/test/resources/org/apache/cxf/systest/jaxrs/security/jose/jwejws/server.xml#L197" rel="nofollow">here</a>. The client can be configured in Spring/Blueprint too.</p><p><a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/jose-parent/jose-jaxrs/src/main/java/org/apache/cxf/rs/security/jose/jaxrs/JwsJsonWriterInterceptor.java" rel="nofollow">JwsJsonWriterInterceptor</a> creates JWS JSON sequences on the client or server out directions. </p><p><a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/jose-parent/jose-jaxrs/src/main/java/org/apache/cxf/rs/security/jose/jaxrs/JwsJsonClientResponseFilter.java" rel="nofollow">JwsJsonClientResponseFilter</a> and <a shape= "rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/jose-parent/jose-jaxrs/src/main/java/org/apache/cxf/rs/security/jose/jaxrs/JwsJsonContainerRequestFilter.java" rel="nofollow">JwsJsonContainerRequestFilter</a> process the incoming client or server Compact JWS sequences.</p><p>Here is an example of a JSON Book representation being signed and converted into JWS JSON and POSTed to the target service:</p><div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent"> +</div></div><p>The above code shows a client proxy code but WebClient can be created instead. The server is configured <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/systests/rs-security/src/test/resources/org/apache/cxf/systest/jaxrs/security/jose/jwejws/server.xml#L197" rel="nofollow">here</a>. The client can be configured in Spring/Blueprint too.</p><p><a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/jose-parent/jose-jaxrs/src/main/java/org/apache/cxf/rs/security/jose/jaxrs/JwsJsonWriterInterceptor.java" rel="nofollow">JwsJsonWriterInterceptor</a> creates JWS JSON sequences on the client or server out directions. </p><p><a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/jose-parent/jose-jaxrs/src/main/java/org/apache/cxf/rs/security/jose/jaxrs/JwsJsonClientResponseFilter.java" rel="nofollow">JwsJsonClientResponseFilter</a> and <a shape= "rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/jose-parent/jose-jaxrs/src/main/java/org/apache/cxf/rs/security/jose/jaxrs/JwsJsonContainerRequestFilter.java" rel="nofollow">JwsJsonContainerRequestFilter</a> process the incoming client or server Compact JWS sequences.</p><p>Here is an example of a plain text "book" being HS256-signed, converted into JWS JSON and POSTed to the target service:</p><div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent"> <pre>Http-Method: POST Content-Type: application/jose+json Payload: { - "payload" : "eyJCb29rIjp7ImlkIjoxMjMsIm5hbWUiOiJib29rIn19", + "payload" : "Ym9vaw", "signatures": [ { "protected" : "eyJhbGciOiJIUzI1NiIsImN0eSI6Impzb24ifQ", - "signature" : "hg1T41ESuX6JvRR--huTA3HnbrsdIZSwkxQdyWj9j6c" + "signature" : "dRUibW7F6LyXuOc78DHubUIave0QUSvte5iv6xoJaL4" } ] }</pre> </div></div><p>Note the Base64Url encoded payload goes first, followed by the 'signatures' array, with each element containing the protected headers and the actual signature specific to a given signature key.</p><p>Enabling the clear JWS payload option wilkl produce:</p><div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent"> <pre>{ - "payload" : "{"Book":{"id":123,"name":"book"}}", + "payload" : "book", "signatures": [ { - "protected" : "eyJhbGciOiJIUzI1NiIsImN0eSI6Impzb24iLCJiNjQiOmZhbHNlLCJjcml0IjpbImI2NCJdfQ", - "signature" : "AwHX5IVrGLXQicma-aaRAyLuHQcKc65fE3ucl_LonO8" + "protected" : "eyJhbGciOiJIUzI1NiIsImN0eSI6InRleHQvcGxhaW4iLCJiNjQiOmZhbHNlLCJjcml0IjpbImI2NCJdfQ", + "signature" : "fM7O2IVO3NsQeTGrFiMeLf_TKTsMSqnqmjnK40PwQ88" } ] }</pre> -</div></div><p>The client code and server configuration is nearly identical to a code/configuration needed to set up JWS Compact filters as shown above, simply replace JwsWriterInterceptor/JwsClientResponseFilter with JwsJsonWriterInterceptor/JwsJsonClientResponseFilter in the client code, and JwsContainerRequestFilter/JwsContainerResponseFilter with JwsJsonContainerRequestFilter/JwsJsonContainerResponseFilter</p><h2 id="JAX-RSJOSE-JWE">JWE</h2><p><a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/jose-parent/jose-jaxrs/src/main/java/org/apache/cxf/rs/security/jose/jaxrs/JweWriterInterceptor.java" rel="nofollow">JweWriterInterceptor</a> 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 <a shape="rect" class="external-link" href="https://github.com/apache /cxf/blob/master/rt/rs/security/jose-parent/jose-jaxrs/src/main/java/org/apache/cxf/rs/security/jose/jaxrs/JweWriterInterceptor.java" rel="nofollow">JweWriterInterceptor</a> and set the encryption properties on the JAX-RS client or server.</p><p><a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/jose-parent/jose-jaxrs/src/main/java/org/apache/cxf/rs/security/jose/jaxrs/JweClientResponseFilter.java" rel="nofollow">JweClientResponseFilter</a> and <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/jose-parent/jose-jaxrs/src/main/java/org/apache/cxf/rs/security/jose/jaxrs/JweContainerRequestFilter.java" rel="nofollow">JweContainerRequestFilter</a> process the incoming client or server Compact JWE sequences.</p><p> </p><p><a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/jose-parent/jose-jaxrs/src/main/java/org/apache/cxf/rs/security/ jose/jaxrs/JweWriterInterceptor.java" rel="nofollow">JweJsonWriterInterceptor</a> creates JWE JSON sequences on the client or server out directions. </p><p><a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/jose-parent/jose-jaxrs/src/main/java/org/apache/cxf/rs/security/jose/jaxrs/JweJsonClientResponseFilter.java" rel="nofollow">JweJsonClientResponseFilter</a> and <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/jose-parent/jose-jaxrs/src/main/java/org/apache/cxf/rs/security/jose/jaxrs/JweContainerRequestFilter.java" rel="nofollow">JweContainerRequestFilter</a> process the incoming client or server JWE JSON sequences.</p><p> </p><h2 id="JAX-RSJOSE-LinkingJWTauthenticationstoJWSorJWEcontent">Linking JWT authentications to JWS or JWE content</h2><p>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 <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/jose-parent/jose-jaxrs/src/main/java/org/apache/cxf/rs/security/jose/jaxrs/JwtAuthenticationClientFilter.java" rel="nofollow">JwtAuthenticationClientFilter</a>on the client side and <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/jose-parent/jose-jaxrs/src/main/java/org/apache/cxf/rs/security/jose/jaxrs/JwtAuthenticationFilter.java" rel="nofollow">JwtAuthenticationFilter</a> 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.</p><p>This approach is more effe ctive 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.</p><p> </p><p> </p><h1 id="JAX-RSJOSE-Configuration">Configuration</h1><p>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.</p><p>Typically a secure JAX-RS endpoint or client is initialized with JWS and or JWE properties.</p><p>For example, <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/systests/rs-security/src/test/resources/org/apache/cxf/systest/jaxrs/security/jose/jwejws/server.xml#L197" rel="nofollow">this endpoint</a> is configured with a <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/systests/rs-security/src/test/resources/org/apache/cxf/systest/jaxrs/security /jose/jwejws/server.xml#L207" rel="nofollow">single JWS properties file</a> which will apply to both input (signature verification) and output (signature creation) JWS operations. <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/systests/rs-security/src/test/resources/org/apache/cxf/systest/jaxrs/security/jose/jwejws/server.xml#L210" rel="nofollow">This endpoint</a> depends on <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/systests/rs-security/src/test/resources/org/apache/cxf/systest/jaxrs/security/jose/jwejws/server.xml#L218" rel="nofollow">two JWS properties files</a>, one - for input JWS, another one - for output JWS. Similarly, <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/systests/rs-security/src/test/resources/org/apache/cxf/systest/jaxrs/security/jose/jwejws/server.xml#L153" rel="nofollow">this endpoint</a> uses a <a shape="rect" class="external-link" href="htt ps://github.com/apache/cxf/blob/master/systests/rs-security/src/test/resources/org/apache/cxf/systest/jaxrs/security/jose/jwejws/server.xml#L162" rel="nofollow">single JWE properties file</a> for encrypting/decrypting the data, while <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/systests/rs-security/src/test/resources/org/apache/cxf/systest/jaxrs/security/jose/jwejws/server.xml#L139" rel="nofollow">this endpoint</a> uses <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/systests/rs-security/src/test/resources/org/apache/cxf/systest/jaxrs/security/jose/jwejws/server.xml#L139" rel="nofollow">two JWE properties files</a>. <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/systests/rs-security/src/test/resources/org/apache/cxf/systest/jaxrs/security/jose/jwejws/server.xml#L178" rel="nofollow">This endpoint</a> support both JWS and JSON with <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/systests/rs-security/src/test/resources/org/apache/cxf/systest/jaxrs/security/jose/jwejws/server.xml#L189" rel="nofollow">in/out specific properties</a>. If either JWS or JWE private key needs to be loaded from the password-protected storage (JKS, encryped JWK)  then a <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/jose-parent/jose/src/main/java/org/apache/cxf/rs/security/jose/common/PrivateKeyPasswordProvider.java" rel="nofollow">password provider</a> needs be <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/systests/rs-security/src/test/resources/org/apache/cxf/systest/jaxrs/security/jose/jwejws/server.xml#L194" rel="nofollow">registered</a> as well, it can be shared between JWS or JWS or be in/out specific for either JWS or JWE.</p><p>These configuration propertie are of major help when JAX-RS JOSE filters process the in/out payload without the application service code being aware of it. While filters can be injected with JWS or JWE providers directly, one would usually set the relevant properties as part of the endpoint or client set-up and expect the filters load the required JWS or JWE providers as needed. </p><p>If you need to do JWS or JWE processing directly in your service or interceptor code then having the properties may also be helpful, for example, the following code works because it is indirectly supported by the properties indicating which signature or encryption algorithm is used, where to get the key if needed, etc:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>Loading JWS and JWE Providers </b></div><div class="codeContent panelContent pdl"> +</div></div><p>The client code and server configuration is nearly identical to a code/configuration needed to set up JWS Compact filters as shown above, simply replace JwsWriterInterceptor/JwsClientResponseFilter with JwsJsonWriterInterceptor/JwsJsonClientResponseFilter in the client code, and JwsContainerRequestFilter/JwsContainerResponseFilter with JwsJsonContainerRequestFilter/JwsJsonContainerResponseFilter</p><h2 id="JAX-RSJOSE-JWE">JWE</h2><p><a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/jose-parent/jose-jaxrs/src/main/java/org/apache/cxf/rs/security/jose/jaxrs/JweWriterInterceptor.java" rel="nofollow">JweWriterInterceptor</a> 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 <a shape="rect" class="external-link" href="https://github.com/apache /cxf/blob/master/rt/rs/security/jose-parent/jose-jaxrs/src/main/java/org/apache/cxf/rs/security/jose/jaxrs/JweWriterInterceptor.java" rel="nofollow">JweWriterInterceptor</a> and set the encryption properties on the JAX-RS client or server.</p><p><a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/jose-parent/jose-jaxrs/src/main/java/org/apache/cxf/rs/security/jose/jaxrs/JweClientResponseFilter.java" rel="nofollow">JweClientResponseFilter</a> and <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/jose-parent/jose-jaxrs/src/main/java/org/apache/cxf/rs/security/jose/jaxrs/JweContainerRequestFilter.java" rel="nofollow">JweContainerRequestFilter</a> process the incoming client or server Compact JWE sequences.</p><p>Here is an example of a plain text "book" being encrypted with the A128KW key and A128GCM content encryption (see JWE section above), converted into Compact JWE and POSTed to the target service:</p><div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent"> +<pre>Address: https://localhost:9001/jwejwkaeswrap/bookstore/books +Http-Method: POST +Content-Type: application/jose +Payload: +eyJhbGciOiJBMTI4S1ciLCJlbmMiOiJBMTI4R0NNIiwiY3R5IjoidGV4dC9wbGFpbiJ9. +SQul1USvHmADDLpBvY2Dnqk5GpoowOkJ. +cFuCSzRsl6GZuvHL. +akVT5g. +i8rpTk-v0b1IyE1sVT1IOA + +org.apache.cxf.rs.security.jose.common.JoseUtils traceHeaders +INFO: JWE Headers: +{"alg":"A128KW", + "enc":"A128GCM", + "cty":"text/plain"}</pre> +</div></div><p>You can see 5 JWE parts (put on separate lines for the better readibility) separated by dots. The 1st part is Base64Url encoded protected headers, next one - Base64Url encoded content encryption key, next one - Base64Url encoded IV, next one - Base64Url encoded ciphertext, finally - the authentication tag.</p><p>Note that the protected headers can be traced by enabling a "jose.debug" contextual property: once can see the key encryption algorithm is "A128KW", content encryption algorithm is "A128GCM" and the content type of the encrypted payload is "text/plain".</p><p>The following client code can be used to set the client JWE Compact interceptors:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>Client JWE SetUp</b></div><div class="codeContent panelContent pdl"> +<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;"> public void testJweJwkAesWrap() throws Exception { + String address = "https://localhost:" + PORT + "/jwejwkaeswrap"; + JAXRSClientFactoryBean bean = new JAXRSClientFactoryBean(); + bean.setServiceClass(BookStore.class); + bean.setAddress(address); + List<Object> providers = new LinkedList<Object>(); + JweWriterInterceptor jweWriter = new JweWriterInterceptor(); + jweWriter.setUseJweOutputStream(true); + providers.add(jweWriter); + providers.add(new JweClientResponseFilter()); + bean.setProviders(providers); + bean.getProperties(true).put("rs.security.encryption.properties", + "org/apache/cxf/systest/jaxrs/security/secret.jwk.properties"); + bean.getProperties(true).put("jose.debug", true); + BookStore bs = bean.create(BookStore.class); + String text = bs.echoText("book"); + assertEquals("book", text); + }</pre> +</div></div><p>The above code shows a client proxy code but WebClient can be created instead. The server is configured <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/systests/rs-security/src/test/resources/org/apache/cxf/systest/jaxrs/security/jose/jwejws/server.xml#L153" rel="nofollow">here</a>. The client can be configured in Spring/Blueprint too.</p><p><a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/jose-parent/jose-jaxrs/src/main/java/org/apache/cxf/rs/security/jose/jaxrs/JweWriterInterceptor.java" rel="nofollow">JweJsonWriterInterceptor</a> creates JWE JSON sequences on the client or server out directions. </p><p><a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/jose-parent/jose-jaxrs/src/main/java/org/apache/cxf/rs/security/jose/jaxrs/JweJsonClientResponseFilter.java" rel="nofollow">JweJsonClientResponseFilter</a> and <a shape="rec t" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/jose-parent/jose-jaxrs/src/main/java/org/apache/cxf/rs/security/jose/jaxrs/JweContainerRequestFilter.java" rel="nofollow">JweContainerRequestFilter</a> process the incoming client or server JWE JSON sequences.</p><p>Here is the same example for encrypting "book" but with JWS JSON interceptors:</p><div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent"> +<pre>Address: https://localhost:9001/jwejsonhmac/bookstore/books +Http-Method: POST +Content-Type: application/jose+json +Payload: +{ + "protected" : "eyJlbmMiOiJBMTI4R0NNIiwiY3R5IjoidGV4dC9wbGFpbiIsImFsZyI6IkExMjhLVyJ9", + "recipients": + [ + { + "encrypted_key": "iq1vJBpOHKRkMDoY2GTakWE6M_uPGVsh" + } + ], + "iv":"SUpOEf-7Q1tT0JV_", + "ciphertext":"alKm_g", + "tag":"DkW2pZCd7lhR0KqIGQ69-A" +}</pre> +</div></div><p>Note the Base64Url encoded protected headers go first, followed by the 'recipients' array, with each element containing the encrypted content encryption key which can be decrypted by the recipient private key, with the array of recipients followed by the IV, ciphertext and authentication tag Base64Url sequences.</p><h2 id="JAX-RSJOSE-LinkingJWTauthenticationstoJWSorJWEcontent">Linking JWT authentications to JWS or JWE content</h2><p>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 <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/jose-parent/jose-jaxrs/src/main/java/org/apache/cxf/rs/secu rity/jose/jaxrs/JwtAuthenticationClientFilter.java" rel="nofollow">JwtAuthenticationClientFilter</a>on the client side and <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/jose-parent/jose-jaxrs/src/main/java/org/apache/cxf/rs/security/jose/jaxrs/JwtAuthenticationFilter.java" rel="nofollow">JwtAuthenticationFilter</a> 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.</p><p>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.</p><p> </p><p> </p><h1 id="JAX-RSJOSE-Configuration">Configuration</h1><p>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.</p><p>Typically a secure JAX-RS endpoint or client is initialized with JWS and or JWE properties.</p><p>For example, <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/systests/rs-security/src/test/resources/org/apache/cxf/systest/jaxrs/security/jose/jwejws/server.xml#L197" rel="nofollow">this endpoint</a> is configured with a <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/systests/rs-security/src/test/resources/org/apache/cxf/systest/jaxrs/security/jose/jwejws/server.xml#L207" rel="nofollow">single JWS properties file</a> which will apply to both input (signature verification) and output (signature creation) JWS operations. <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/systests/rs-security/src/test/resources/org/apache/cxf/systest/jaxrs/security/jose/jwejws/server.xml#L210" rel="nofollow">This endpoint</a> depends on <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/systests/rs-security/src/test/resources/org/apache/cxf/systest/jaxrs/security/jose/jwejws/server.xml#L218" rel="nofollow">two JWS properties files</a>, one - for input JWS, another one - for output JWS. Similarly, <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/systests/rs-security/src/test/resources/org/apache/cxf/systest/jaxrs/security/jose/jwejws/server.xml#L153" rel="nofollow">this endpoint</a> uses a <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/systests/rs-security/src/test/resources/org/apache/cxf/systest/jaxrs/security/jose/jwejws/server.xml#L162" rel="nofollow">single JWE properties file</a> for encrypting/decrypting the data, while <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/systests/rs-security/src/test/resources/org/apache/cxf/systest/jaxrs/security/jose/jwejws/server. xml#L139" rel="nofollow">this endpoint</a> uses <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/systests/rs-security/src/test/resources/org/apache/cxf/systest/jaxrs/security/jose/jwejws/server.xml#L139" rel="nofollow">two JWE properties files</a>. <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/systests/rs-security/src/test/resources/org/apache/cxf/systest/jaxrs/security/jose/jwejws/server.xml#L178" rel="nofollow">This endpoint</a> support both JWS and JSON with <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/systests/rs-security/src/test/resources/org/apache/cxf/systest/jaxrs/security/jose/jwejws/server.xml#L189" rel="nofollow">in/out specific properties</a>. If either JWS or JWE private key needs to be loaded from the password-protected storage (JKS, encryped JWK)  then a <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt /rs/security/jose-parent/jose/src/main/java/org/apache/cxf/rs/security/jose/common/PrivateKeyPasswordProvider.java" rel="nofollow">password provider</a> needs be <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/systests/rs-security/src/test/resources/org/apache/cxf/systest/jaxrs/security/jose/jwejws/server.xml#L194" rel="nofollow">registered</a> as well, it can be shared between JWS or JWS or be in/out specific for either JWS or JWE.</p><p>These configuration propertie are of major help when JAX-RS JOSE filters process the in/out payload without the application service code being aware of it. While filters can be injected with JWS or JWE providers directly, one would usually set the relevant properties as part of the endpoint or client set-up and expect the filters load the required JWS or JWE providers as needed. </p><p>If you need to do JWS or JWE processing directly in your service or interceptor code then having the properties may also b e helpful, for example, the following code works because it is indirectly supported by the properties indicating which signature or encryption algorithm is used, where to get the key if needed, etc:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>Loading JWS and JWE Providers </b></div><div class="codeContent panelContent pdl"> <pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">JwsSignatureProvider jwsOut = JwsUtils.loadSignatureProvider(true); JwsSignatureVerifier jwsIn = JwsUtils.loadSignatureVerifier(true);