Author: buildbot Date: Thu Jun 15 12:47:45 2017 New Revision: 1014072 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 Thu Jun 15 12:47:45 2017 @@ -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.rbtoc1495802825236 {padding: 0px;} -div.rbtoc1495802825236 ul {list-style: disc;margin-left: 0px;} -div.rbtoc1495802825236 li {margin-left: 0px;padding-left: 0px;} +div.rbtoc1497530828795 {padding: 0px;} +div.rbtoc1497530828795 ul {list-style: disc;margin-left: 0px;} +div.rbtoc1497530828795 li {margin-left: 0px;padding-left: 0px;} -/*]]>*/</style></p><div class="toc-macro rbtoc1495802825236"> +/*]]>*/</style></p><div class="toc-macro rbtoc1497530828795"> <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> @@ -136,6 +136,16 @@ div.rbtoc1495802825236 li {margin-left: </li><li><a shape="rect" href="#JAX-RSJOSE-SigningandVerificationofHTTPAttachments">Signing and Verification of HTTP Attachments</a></li><li><a shape="rect" href="#JAX-RSJOSE-JWE">JWE</a> <ul class="toc-indentation"><li><a shape="rect" href="#JAX-RSJOSE-JWECompact.1">JWE Compact</a></li><li><a shape="rect" href="#JAX-RSJOSE-JWEJSON.1">JWE JSON</a></li></ul> </li><li><a shape="rect" href="#JAX-RSJOSE-LinkingJWTauthenticationstoJWSorJWEcontent">Linking JWT authentications to JWS or JWE content</a></li><li><a shape="rect" href="#JAX-RSJOSE-OptionalprotectionofHTTPheaders">Optional protection of HTTP headers</a></li></ul> +</li><li><a shape="rect" href="#JAX-RSJOSE-JOSEinJAX-RSapplicationcode">JOSE in JAX-RS application code</a> +<ul class="toc-indentation"><li><a shape="rect" href="#JAX-RSJOSE-Option1:ProcessJOSEdirectly">Option 1:  Process JOSE directly</a></li><li><a shape="rect" href="#JAX-RSJOSE-Option2:UseJOSElibraryhelpersandEndpointConfiguration">Option 2:  Use JOSE library helpers and Endpoint Configuration</a> +<ul class="toc-indentation"><li><a shape="rect" href="#JAX-RSJOSE-ProduceJOSEdata">Produce JOSE data</a> +<ul class="toc-indentation"><li><a shape="rect" href="#JAX-RSJOSE-Step1.UseJoseProducerorJoseJwtProducer">Step1. Use JoseProducer or JoseJwtProducer</a></li><li><a shape="rect" href="#JAX-RSJOSE-Step2.Setthekeystorelocation">Step2. Set the key store location</a></li></ul> +</li><li><a shape="rect" href="#JAX-RSJOSE-ConsumeJOSEdata">Consume JOSE data</a> +<ul class="toc-indentation"><li><a shape="rect" href="#JAX-RSJOSE-Step1.UseJoseConsumerorJoseJwtConsumer">Step1. Use JoseConsumer or JoseJwtConsumer</a></li><li><a shape="rect" href="#JAX-RSJOSE-Step2.Setthekeystorelocation.1">Step2. Set the key store location</a></li></ul> +</li><li><a shape="rect" href="#JAX-RSJOSE-ProduceandConsumeJOSEdata">Produce and Consume JOSE data</a> +<ul class="toc-indentation"><li><a shape="rect" href="#JAX-RSJOSE-Step1.UseJoseProducerConsumerorJoseJwtProducerConsumer">Step1. Use JoseProducerConsumer or JoseJwtProducerConsumer</a></li><li><a shape="rect" href="#JAX-RSJOSE-Step2.Setthekeystorelocation.2">Step2. Set the key store location</a></li></ul> +</li></ul> +</li></ul> </li><li><a shape="rect" href="#JAX-RSJOSE-Configuration">Configuration</a> <ul class="toc-indentation"><li><a shape="rect" href="#JAX-RSJOSE-ConfigurationPropertyContainers">Configuration Property Containers</a> <ul class="toc-indentation"><li><a shape="rect" href="#JAX-RSJOSE-Signature">Signature</a></li><li><a shape="rect" href="#JAX-RSJOSE-Encryption">Encryption</a></li></ul> @@ -675,7 +685,7 @@ Payload: "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><h2 id="JAX-RSJOSE-OptionalprotectionofHTTPheaders">Optional protection of HTTP headers</h2><p>Starting from CXF 3.1.12 it is possible to use JWS, JWS JSON, JWE and JWE JSON filters to protect the selected set of HTTP headers. The JOSE payloads produced b y these filters guarantee that the JOSE headers are integrity protected. Given this, if one enables a 'protectHttpHeaders' boolean property on the request filters, then, by default, HTTP Content-Type and Accept header values will be registered as JOSE header properties prefixed with "http.", example, "http.Accept":"text/plain". The list of the headers to be protected can be customized using a 'protectedHttpHeaders' set property.</p><p>These properties will be compared against the current HTTP headers on the receiving end.</p><p>This approach does not prevent the streaming of the outgoing data (which will also be protected by the filters) and offers a way to secure the HTTP headers which are really important for the correct processing of the incoming payloads</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 process ors 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/ser ver.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/maste r/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 al so 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>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><h2 id="JAX-RSJOSE-OptionalprotectionofHTTPheaders">Optional protection of HTTP headers</h2><p>Starting from CXF 3.1.12 it is possible to use JWS, JWS JSON, JWE and JWE JSON filters to protect the selected set of HTTP headers. The JOSE payloads produced b y these filters guarantee that the JOSE headers are integrity protected. Given this, if one enables a 'protectHttpHeaders' boolean property on the request filters, then, by default, HTTP Content-Type and Accept header values will be registered as JOSE header properties prefixed with "http.", example, "http.Accept":"text/plain". The list of the headers to be protected can be customized using a 'protectedHttpHeaders' set property.</p><p>These properties will be compared against the current HTTP headers on the receiving end.</p><p>This approach does not prevent the streaming of the outgoing data (which will also be protected by the filters) and offers a way to secure the HTTP headers which are really important for the correct processing of the incoming payloads</p><h1 id="JAX-RSJOSE-JOSEinJAX-RSapplicationcode">JOSE in JAX-RS application code</h1><p>In some cases you may need to create or process the JOSE data directly in the service or client application code. For example, one of the properties in the request or response payload needs to be JWS signed/verified and/or JWE encrypted/decrypted. The following 2 options can be tried.</p><h2 id="JAX-RSJOSE-Option1:ProcessJOSEdirectly">Option 1:  Process JOSE directly</h2><p>This option is about using the CXF JOSE library to sign, encrypt, or/and decrypt and verify the data as <a shape="rect" href="jax-rs-jose.html">documented above</a>. This option should be preferred if one needs to keep a closer control, for example, set the custom JWS or JWE headers, etc.</p><h2 id="JAX-RSJOSE-Option2:UseJOSElibraryhelpersandEndpointConfiguration">Option 2:  Use JOSE library helpers and Endpoint Configuration</h2><p>This option makes it straighforward to do JOSE in the application code. One has to extend or delegate to a specific JOSE helper instance and configure the endpoint with the locatiion of the key store.</p><h3 id="JAX-RSJOSE-ProduceJOSEdata">Produce JOSE data</h3><h4 id="JAX-RSJOSE-Step1.UseJoseProducerorJoseJwt Producer">Step1. Use JoseProducer or JoseJwtProducer</h4><h4 id="JAX-RSJOSE-Step2.Setthekeystorelocation">Step2. Set the key store location</h4><h3 id="JAX-RSJOSE-ConsumeJOSEdata">Consume JOSE data</h3><h4 id="JAX-RSJOSE-Step1.UseJoseConsumerorJoseJwtConsumer">Step1. Use JoseConsumer or JoseJwtConsumer</h4><h4 id="JAX-RSJOSE-Step2.Setthekeystorelocation.1">Step2. Set the key store location</h4><h3 id="JAX-RSJOSE-ProduceandConsumeJOSEdata">Produce and Consume JOSE data</h3><h4 id="JAX-RSJOSE-Step1.UseJoseProducerConsumerorJoseJwtProducerConsumer">Step1. Use JoseProducerConsumer or JoseJwtProducerConsumer</h4><h4 id="JAX-RSJOSE-Step2.Setthekeystorelocation.2">Step2. Set the key store location</h4><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>Typic ally 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/a pache/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/se curity/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 i ndirectly 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);