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 Wed Sep 13 15:05:52
2017
@@ -32,10 +32,10 @@
<link type="text/css" rel="stylesheet"
href="/resources/highlighter/styles/shThemeCXF.css">
<script src='/resources/highlighter/scripts/shCore.js'></script>
-<script src='/resources/highlighter/scripts/shBrushJava.js'></script>
+<script src='/resources/highlighter/scripts/shBrushBash.js'></script>
<script src='/resources/highlighter/scripts/shBrushXml.js'></script>
+<script src='/resources/highlighter/scripts/shBrushJava.js'></script>
<script src='/resources/highlighter/scripts/shBrushJScript.js'></script>
-<script src='/resources/highlighter/scripts/shBrushBash.js'></script>
<script>
SyntaxHighlighter.defaults['toolbar'] = false;
SyntaxHighlighter.all();
@@ -120,11 +120,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.rbtoc1505311237409 {padding: 0px;}
-div.rbtoc1505311237409 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1505311237409 li {margin-left: 0px;padding-left: 0px;}
+div.rbtoc1505314920830 {padding: 0px;}
+div.rbtoc1505314920830 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1505314920830 li {margin-left: 0px;padding-left: 0px;}
-/*]]>*/</style></p><div class="toc-macro rbtoc1505311237409">
+/*]]>*/</style></p><div class="toc-macro rbtoc1505314920830">
<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>
@@ -147,28 +147,28 @@ div.rbtoc1505311237409 li {margin-left:
</li><li><a shape="rect"
href="#JAX-RSJOSE-Configurationthatappliestobothencryptionandsignature">Configuration
that applies to both encryption and signature</a></li><li><a shape="rect"
href="#JAX-RSJOSE-Configurationthatappliestosignatureonly">Configuration that
applies to signature only</a></li><li><a shape="rect"
href="#JAX-RSJOSE-Configurationthatappliestoencryptiononly">Configuration that
applies to encryption only</a></li><li><a shape="rect"
href="#JAX-RSJOSE-ConfigurationthatappliestoJWTtokensonly">Configuration that
applies to JWT tokens only</a></li></ul>
</li><li><a shape="rect"
href="#JAX-RSJOSE-Interoperability">Interoperability</a></li><li><a
shape="rect" href="#JAX-RSJOSE-Third-PartyLibraries">Third-Party
Libraries</a></li></ul>
</div><h1 id="JAX-RSJOSE-Introduction">Introduction</h1><p><a shape="rect"
class="external-link" href="https://datatracker.ietf.org/wg/jose/documents/";
rel="nofollow">JOSE</a> 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 formats (plain text, XML, binary
data).</p><p><a shape="rect" class="external-link"
href="https://datatracker.ietf.org/wg/jose/documents/";
rel="nofollow">JOSE</a> is a key piece of advanced OAuth2 and OpenId
Connect applications but can also be successfully used for securing the regular
HTTP web service communications.</p><p>CXF 3.0.x, 3.1.x and 3.2.0 provide a
complete implementation of <a shape="rect" class="external-link"
href="https://datatracker.ietf.org/wg/jose/documents/"; rel="nofollow">JOSE</a>
and offer a comprehensive utility and filter support f
or protecting JAX-RS services and clients with the help of <a shape="rect"
class="external-link" href="https://datatracker.ietf.org/wg/jose/documents/";
rel="nofollow">JOSE</a>.</p><p>CXF <a shape="rect"
href="http://cxf.apache.org/docs/jax-rs-oauth2.html";>OAuth2</a> and <a
shape="rect" href="http://cxf.apache.org/docs/jax-rs-oidc.html";>OIDC</a>
modules are also depending on it.</p><p><strong>New</strong>: Signature and
Verification support for multiparts using JWS Detached Content
mode.</p><p><strong>New</strong>: Optional HTTP Header protection.</p><h1
id="JAX-RSJOSE-MavenDependencies">Maven Dependencies</h1><p> </p><p>Having
the following dependency will let developers write JOSE JWS or JWE
code:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;"><dependency>
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><dependency>
<groupId>org.apache.cxf</groupId>
<artifactId>cxf-rt-rs-security-jose</artifactId>
<version>3.1.7</version>
</dependency>
</pre>
</div></div><p> </p><p>Having the following dependency will let
developers use JAX-RS JOSE filters which will 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.</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;"><dependency>
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><dependency>
<groupId>org.apache.cxf</groupId>
<artifactId>cxf-rt-rs-security-jose-jaxrs</artifactId>
<version>3.1.7</version>
</dependency>
</pre>
</div></div><p>You may also need to include BouncyCastle for some of JWE
encryption algorithms to be supported:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;"><dependency>
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><dependency>
<groupId>org.bouncycastle</groupId>
<artifactId>bcprov-ext-jdk15on</artifactId>
<version>1.54</version>
</dependency>
</pre>
</div></div><p>BouncyCastle provider can be registered and unregistered as
follows:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeHeader panelHeader pdl" style="border-bottom-width:
1px;"><b>BouncyCastle Provider</b></div><div class="codeContent panelContent
pdl">
-<pre class="brush: java; gutter: false; theme: Confluence"
style="font-size:12px;">import java.security.Security;
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">import java.security.Security;
import org.bouncycastle.jce.provider.BouncyCastleProvider;
private static void registerBouncyCastle() throws Exception {
@@ -179,13 +179,13 @@ private static void unregisterBouncyCast
Security.removeProvider(BouncyCastleProvider.PROVIDER_NAME);
}</pre>
</div></div><p> </p><h1 id="JAX-RSJOSE-JavaandJCEPolicy">Java and JCE
Policy </h1><p>Java7 or higher is recommended in most
cases.</p><p><strong>JWE</strong></p><p>Java6 does not support JWE AES GCM key
wrap and content encryption algorithms (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), however with Java 6 one can use
AesCbcHmac content encryption if BouncyCastle is installed.</p><p>Unlimited JCE
Policy for Java 7/8/9 needs to be installed if a size of the encryption key is
256 bits (example, JWE A256GCM).</p><p><strong>JWS</strong></p><p>Java 6 should
also be fine but note only CXF 3.0.x can be run with Java 6.</p><h1
id="JAX-RSJOSE-JOSEOverviewandImplementation">JOSE Overview and
Implementation</h1><p>JOSE consists of the following key parts:</p><ul><li><a
shape="rect" class="external-link" href="https://tools.ietf.org/html/rfc7518";
rel="nofollow">JWA</a> - JSON We
b Algorithms where all supported signature and encryption algorithms are
listed</li><li><a shape="rect" class="external-link"
href="https://tools.ietf.org/html/rfc7517"; rel="nofollow">JWK</a> - JSON Web
Keys - introduces a JSON format for describing the public and private keys used
by JWA algorithms</li><li><a shape="rect" class="external-link"
href="https://tools.ietf.org/html/rfc7515"; rel="nofollow">JWS</a> - JSON Web
Signature - describes how the data can be signed or validated and introduces
compact and JSON JWS formats for representing the signed data</li><li><a
shape="rect" class="external-link" href="https://tools.ietf.org/html/rfc7516";
rel="nofollow">JWE</a> - JSON Web Encryption - describes how the data can be
encrypted or decrypted and introduces compact and JSON JWE formats for
representing the encrypted data  </li></ul><p>Additionally, <a
shape="rect" class="external-link" href="https://tools.ietf.org/html/rfc7519";
rel="nofollow">JWT</a> (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). <a shape="rect" class="external-link"
href="https://tools.ietf.org/html/rfc7519"; rel="nofollow">JWT</a> describes how
a set of claims in JSON format can be JWS-signed and/or
JWE-enctypted. </p><h2 id="JAX-RSJOSE-JWAAlgorithms">JWA
Algorithms</h2><p>All JOSE signature and encryption algorithms are grouped and
described in the <a shape="rect" class="external-link"
href="https://tools.ietf.org/html/rfc7518"; rel="nofollow">JWA</a> (JSON Web
Algorithms) specification.</p><p>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 or AES CBC HMA
C).</p><div>The specification lists all the algorithms that can be used for
signing or encrypting the data and also describes how some of these algorithms
work in cases</div><div>where Java JCA (or BouncyCastle) does not support them
directly, example, AES-CBC-HMAC-SHA2.</div><div>Algorithm name is a type +
hint, example: HS256 (HMAC with SHA-256), RSA-OAEP-256 (RSA OAEP key encryption
with SHA-256), etc.</div><p>All JWS and JWE algorithms process not only the
actual data but also the meta-data (the algorithm properties) thus ensuring
they are integrity-protected, additionally JWE algorithms produce
authentication tags which ensure the already encrypted content won't be
manipulated.</p><p>Please refer to <a shape="rect" class="external-link"
href="https://tools.ietf.org/html/rfc7518"; rel="nofollow">the specification</a>
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 prope
rties, 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.</p><p>CXF offers the utility support for working with
JWA algorithms in <a shape="rect" class="external-link"
href="https://github.com/apache/cxf/tree/master/rt/rs/security/jose-parent/jose/src/main/java/org/apache/cxf/rs/security/jose/jwa";
rel="nofollow">this package</a>.</p><p>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.</p><h2 id="JAX-RSJOSE-JWKKeys">JWK
Keys</h2><p><a shape="rect" class="external-link"
href="https://tools.ietf.org/html/rfc7517"; rel="nofollow">JWK</a> (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.</p><p>For example:</p><div class="code
panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl"
style="border-bottom-width: 1px;"><b>Secret HMAC Key</b></div><div
class="codeContent panelContent pdl">
-<pre class="brush: js; gutter: false; theme: Confluence"
style="font-size:12px;">{
+<pre class="brush: js; gutter: false; theme: Default" style="font-size:12px;">{
"kty":"oct",
"k":"AyM1SysPpbyDfgZld3umj1qzKObwVMkoqQ-EstJQLr_T-1qS0gZH75aKtMN3Yj0iPS4hcgUuTwjAzZr1Z9CAow",
"kid":"Secret HMAC key"
}</pre>
</div></div><p>or</p><div class="code panel pdl" style="border-width:
1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width:
1px;"><b>Public RSA Key</b></div><div class="codeContent panelContent pdl">
-<pre class="brush: js; gutter: false; theme: Confluence"
style="font-size:12px;">{
+<pre class="brush: js; gutter: false; theme: Default" style="font-size:12px;">{
"kty":"RSA",
"n": "0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2aiAFbWhM78LhWx
4cbbfAAtVT86zwu1RK7aPFFxuhDR1L6tSoc_BJECPebWKRXjBZCiFV4n3oknjhMs
@@ -197,7 +197,7 @@ private static void unregisterBouncyCast
"alg":"RS256",
"kid":"Public RSA Key"}</pre>
</div></div><p>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, <a shape="rect" class="external-link"
href="http://openid.net/specs/openid-connect-core-1_0.html#RotateSigKeys";
rel="nofollow">OIDC Asymmetric Key Rotation</a>).</p><p>A collection of JWK
keys is called a JWK Key Set which is represented as JSON array of
JWKs.</p><p>JWK can contain X509 certificates or their thumbprints if
preferred.</p><p>CXF offers a utility support for reading and writing JWK keys
and key sets and working with the encrypted inlined and standalone JWK stores
in <a shape="rect" class="external-link"
href="https://github.com/apache/cxf/tree/master/rt/rs/security/jose-parent/jose/src/main/java/org/apache/cxf/rs/security/jose/jwk";
rel="nofollow">this package</a>.</p><p>For example, a key set containing
public JWK keys can be seen <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/certs/jwkPublicSet.txt"
rel="nofollow">here</a> and referred to from the <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/jws.ec.public.properties#L19";
rel="nofollow">configuration properties</a>. The private (test) key set can be
represented in 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/certs/jwkPrivateSet.txt";
rel="nofollow">clear form</a>, though most likely you'd want a private key set
<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/certs/encryptedJwkPrivateSet.txt";
rel="nofollow">encrypted</a> and referred to <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/secret.aescbchmac.properties#L19";
rel="nofollow">like this</a>. </p><p>One can inline the encrypted key or
the key set directly in the configuration properties. For example, here is how
an encrypted <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/secret.aescbchmac.inlinejwk.properties#L18";
rel="nofollow">single JWK key is inlined</a>. Similarly, here is how an
encrypted <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/secret.aescbchmac.inlineset.properties#L18";
rel="nofollow">collection of keys is inlined</a>.</p><p>CXF assumes that JWK
keys have been encrypted if a <a shape="rect" class="external-link"
href="https://github.com/apach
e/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> is available in a request context, it is
typically registered with JAX-RS endpoints. The encryption is done with a
password based <a shape="rect" class="external-link"
href="https://tools.ietf.org/html/rfc7518#section-4.8"; rel="nofollow">PBES2
algorithm</a>. </p><p>Support for the pluggable strategies for loading
JWKs is on the map.</p><p>For example, here is how you can load a JWK key using
its 'kid':</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>JWK
examples</b></div><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Confluence"
style="font-size:12px;">InputStream is =
JsonWebKeyTest.class.getResourceAsStream(fileName);
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">InputStream is =
JsonWebKeyTest.class.getResourceAsStream(fileName);
JsonWebKeys keySet = JwkUtils.readJwkSet(is);
JsonWebKey key = keySet.getKey("Public RSA Key");
String thumbprint = JwkUtils.getThumbprint(key);
@@ -205,7 +205,7 @@ assertEquals("NzbLsXh8uDCcd-6MNwXF4W_7no
KeyType keyType = key.getKeyType();
assertEquals(KeyType.RSA, keyType);</pre>
</div></div><p>JsonWebKeys also supports the retrieval of keys by their type
(RSA, EC, Octet) and operation (ENCRYPT, SIGN, etc). <br clear="none">Once you
have JWK loaded it is typically submitted to JWS or JWE providers.</p><h2
id="JAX-RSJOSE-JWSSignature">JWS Signature</h2><p><a shape="rect"
class="external-link" href="https://tools.ietf.org/html/rfc7515";
rel="nofollow">JWS</a> (JSON Web Signature) document describes how a document
content can be signed. For example, <a shape="rect" class="external-link"
href="https://tools.ietf.org/html/rfc7515#appendix-A.1"; rel="nofollow">Appendix
A1</a> shows how the content can be signed with an HMAC key</p><p>CXF ships JWS
related classes in <a shape="rect" class="external-link"
href="https://github.com/apache/cxf/tree/master/rt/rs/security/jose-parent/jose/src/main/java/org/apache/cxf/rs/security/jose/jws";
rel="nofollow">this package</a> and offers a support for all of JWA <a
shape="rect" class="external-link" href="https://tools.ietf.org/h
tml/rfc7518#section-3" rel="nofollow">signature algorithms</a>.</p><h3
id="JAX-RSJOSE-SignatureandVerificationProviders">Signature and Verification
Providers</h3><p><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/jws/JwsSignatureProvider.java";
rel="nofollow">JwsSignatureProvider</a> supports signing the content, <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/jws/JwsSignatureVerifier.java";
rel="nofollow">JwsSignatureVerifier</a> - validating the
signatures.</p><p>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.</p><p>The following
table shows the
algorithms and the corresponding providers (<span
class="pl-smi">org.apache.cxf.rs.security.jose.jws</span> package):</p><div
class="table-wrap"><table class="confluenceTable"><tbody><tr><td colspan="1"
rowspan="1" class="confluenceTd"><strong>Algorithm</strong></td><td colspan="1"
rowspan="1" class="confluenceTd"><strong>JWS Header 'alg'</strong></td><td
colspan="1" rowspan="1"
class="confluenceTd"><strong>JwsSignatureProvider</strong></td><td colspan="1"
rowspan="1"
class="confluenceTd"><strong>JwsSignatureVerifier</strong></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><a shape="rect"
class="external-link" href="https://tools.ietf.org/html/rfc7518#section-3.2";
rel="nofollow">HMAC</a></td><td colspan="1" rowspan="1"
class="confluenceTd">HS256, HS384, HS512</td><td colspan="1" rowspan="1"
class="confluenceTd"><p>HmacJwsSignatureProvider</p></td><td colspan="1"
rowspan="1"
class="confluenceTd"><p>HmacJwsSignatureVerifier</p></td></tr><tr><td
colspan="1" rowspan="1" cl
ass="confluenceTd"><a shape="rect" class="external-link"
href="https://tools.ietf.org/html/rfc7518#section-3.3";
rel="nofollow">RSASSA-PKCS1-v1_5</a></td><td colspan="1" rowspan="1"
class="confluenceTd">RS256, RS384, RS512</td><td colspan="1" rowspan="1"
class="confluenceTd">PrivateKeyJwsSignatureProvider</td><td colspan="1"
rowspan="1" class="confluenceTd">PublicKeyJwsSignatureVerifier</td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><a shape="rect"
class="external-link" href="https://tools.ietf.org/html/rfc7518#section-3.4";
rel="nofollow">ECDSA</a></td><td colspan="1" rowspan="1"
class="confluenceTd">ES256, ES384, ES512</td><td colspan="1" rowspan="1"
class="confluenceTd">EcDsaJwsSignatureProvider</td><td colspan="1" rowspan="1"
class="confluenceTd">EcDsaJwsSignatureVerifier</td></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><a shape="rect" class="external-link"
href="https://tools.ietf.org/html/rfc7518#section-3.5";
rel="nofollow">RSASSA-PSS</a></td><td cols
pan="1" rowspan="1" class="confluenceTd">PS256, PS384, PS512</td><td
colspan="1" rowspan="1"
class="confluenceTd">PrivateKeyJwsSignatureProvider</td><td colspan="1"
rowspan="1" class="confluenceTd">PublicKeyJwsSignatureVerifier</td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><a shape="rect"
class="external-link" href="https://tools.ietf.org/html/rfc7518#section-3.6";
rel="nofollow">None</a></td><td colspan="1" rowspan="1"
class="confluenceTd">none</td><td colspan="1" rowspan="1"
class="confluenceTd">NoneJwsSignatureProvider</td><td colspan="1" rowspan="1"
class="confluenceTd">NoneJwsSignatureVerifier</td></tr></tbody></table></div><p>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.</p><p>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 k
eys 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.</p><p>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 to JWS Compact or JWS JSON producers or consumers.</p><p><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/jws/JwsUtils.java";
rel="nofollow">JwsUtils</a> utility class has a lot of helper methods to load
JwsSignatureProvider or JwsSignatureVerifier and to get JWS sequences created
and validated.</p><h3 id="JAX-RSJOSE-JWSCompact">JWS Compact</h3><p><a sh
ape="rect" class="external-link"
href="https://tools.ietf.org/html/rfc7515#section-3.3"; rel="nofollow">JWS
Compact representation</a> is the most often used JWS sequence format. It is
the concatenation of Base64URL-encoded sequence of 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.</p><p><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/jws/JwsCompactProducer.java";
rel="nofollow">JwsCompactProducer</a> and <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/jws/JwsCompactConsumer.java";
rel="nofollow">JwsCompactConsumer</a> offer a support for producing and
consuming compact JWS sequences, protecting the data in JSON or non-JS
ON formats.</p><p><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/jws/JwsJwtCompactProducer.java";
rel="nofollow">JwsJwtCompactProducer</a> and <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/jws/JwsJwtCompactConsumer.java";
rel="nofollow">JwsJwtCompactConsumer</a> are their simple extensions which
help with processing typed JWT Tokens.</p><p> For example, here is how an
<a shape="rect" class="external-link"
href="https://tools.ietf.org/html/rfc7515#appendix-A.1"; rel="nofollow">Appendix
A1</a> example can be done in CXF:</p><p> </p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeHeader panelHeader pdl"
style="border-bottom-width: 1px;"><b>CXF JWS Compact HMac</b></div><div
class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Confluence"
style="font-size:12px;">JwtClaims claims = new JwtClaims();
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">JwtClaims claims = new JwtClaims();
claims.setIssuer("joe");
claims.setExpiryTime(1300819380L);
claims.setClaim("http://example.com/is_root";, Boolean.TRUE);
@@ -226,7 +226,7 @@ jwsConsumer.verifySignatureWith(new Hmac
JwtClaims protectedClaims = jws.getJwtClaims();
</pre>
</div></div><p>In the above example, the data (JwtToken) is submitted to an
instance of JwsCompactProducer (JwsJwtCompactProducer) and signed with an HMac
key.</p><p>Here is another example:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeHeader panelHeader pdl"
style="border-bottom-width: 1px;"><b>CXF JWS Compact RSA</b></div><div
class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Confluence"
style="font-size:12px;">JwsCompactProducer jwsProducer = new
JwsCompactProducer("Hello World");
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">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);
@@ -248,7 +248,7 @@ jws.verifySignatureWith(publicRsaKey);
String helloWorldString = jwsConsumer.getDecodedJwsPayload();
</pre>
</div></div><p>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.</p><h3 id="JAX-RSJOSE-JWSJSON">JWS
JSON</h3><p>While JWS Compact is optimized and represents a concatenation of 3
Base64URL values, JWS JSON is an open JSON container, see <a shape="rect"
class="external-link" href="https://tools.ietf.org/html/rfc7515#appendix-A.6";
rel="nofollow">Appendix 6</a>.</p><p>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.  </p><p><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/jws/JwsJsonProducer.java";
rel="nofol
low">JwsJsonProducer</a> and <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/jws/JwsJsonConsumer.java";
rel="nofollow">JwsJsonConsumer</a> support producing and consuming JWS JSON
sequences.</p><p> </p><div class="code panel pdl" style="border-width:
1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width:
1px;"><b>CXF JWS JSON</b></div><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Confluence"
style="font-size:12px;">JwsJsonProducer producer = new
JwsJsonProducer(UNSIGNED_PLAIN_JSON_DOCUMENT);
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">JwsJsonProducer producer = new
JwsJsonProducer(UNSIGNED_PLAIN_JSON_DOCUMENT);
JwsHeaders headerEntries = new JwsHeaders(SignatureAlgorithm.HS256);
producer.signWith(new HmacJwsSignatureProvider(ENCODED_MAC_KEY_1,
SignatureAlgorithm.HS256),
@@ -281,13 +281,13 @@ String nextJwsJson = consumer.validateAn
// double-signed JWS JSON signature, minus the signature which was already
validated, in this case nextJwsJson will
// only have a single signature </pre>
</div></div><p>The above code produces a JWS JSON sequence containing two
signatures, similarly to <a shape="rect" class="external-link"
href="https://tools.ietf.org/html/rfc7515#appendix-A.6.4"; rel="nofollow">this
example</a>. 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 <a shape="rect" class="external-link"
href="https://tools.ietf.org/html/rfc7515#appendix-A.6.4";
rel="nofollow">flattened</a> instead 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. </p><p>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 Co
mpact is a good alternative, likely to be used most often.</p><p>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.</p><h3
id="JAX-RSJOSE-JWSwithDetachedContent">JWS with Detached Content</h3><p><a
shape="rect" class="external-link"
href="https://tools.ietf.org/html/rfc7515#appendix-F"; rel="nofollow">JWS with
Detached Content</a> provides a way to integrity-protect some data without
actually having these data included in the resulting JWS sequence.</p><p>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.      </p><p>Note
the detached content mode is used to support the signing and verification of
CXF multipart attachment parts, see below for more information.</p><h3
id="JAX-RSJOSE-JWSwithUnencodedPayload">JWS with Unencoded Payload</h3><p>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. </p><p>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.</p><p>Thus a <a s
hape="rect" class="external-link" href="https://tools.ietf.org/html/rfc7797";
rel="nofollow">JWS with Unencoded Payload</a> 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, see <a shape="rect"
class="external-link" href="https://tools.ietf.org/html/rfc7797#page-7";
rel="nofollow">this example</a>.</p><p>Both JWS JSON and JWS Compact support
'b64' property for the detached and embedded payloads.</p><p>In CXF you can
apply this option to both JWS Compact (embedded payloads - from CXF 3.1.7) and
JWS JSON sequences, here is a JWS JSON code fragment:</p><p> </p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeHeader
panelHeader pdl" style="border-bottom-width: 1px;"><b>JWS JSON
Unencoded</b></div><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Confluence"
style="font-size:12px;">JwsJsonProducer producer = new
JwsJsonProducer(UNSIGNED_PLAIN_JSON_DOCUMENT, true);
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">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);</pre>
</div></div><p>Note that JWS Compact uses a '.' as a separator between its 3
parts. <a shape="rect" class="external-link"
href="https://tools.ietf.org/html/rfc7797#section-5"; rel="nofollow">JWS with
Unencoded Payload</a> recommends that it is the application's responsibility to
deal with the unencoded payloads which may have '.' characters. Similarly, JWS
JSON unencoded payloads with double quotes will need to be taken care of by the
application. </p><p>Note the the signing and verification of CXF multipart
attachment parts does depend on this unencoded payload feature, see below for
more information.</p><h2 id="JAX-RSJOSE-JWEEncryption">JWE Encryption</h2><p><a
shape="rect" class="external-link" href="https://tools.ietf.org/html/rfc7516";
rel="nofollow">JWE</a> (JSON Web Encryption) document describes how a document
content, and, when applicable, a content encryption key, can be encrypted. For
example, <a shape="rect" class="external-link"
href="https://tools.ietf.org/html/rfc7
516#appendix-A.1" rel="nofollow">Appendix A1</a> shows how the content can be
encrypted with a secret key using AesGcm with the actual content encryption key
being encrypted using RSA-OAEP.</p><p>CXF ships JWE related classes in <a
shape="rect" class="external-link"
href="https://github.com/apache/cxf/tree/master/rt/rs/security/jose-parent/jose/src/main/java/org/apache/cxf/rs/security/jose/jwe";
rel="nofollow">this package</a> and offers a support for all of JWA <a
shape="rect" class="external-link"
href="https://tools.ietf.org/html/rfc7518#section-4"; rel="nofollow">key
encryption</a> and <a shape="rect" class="external-link"
href="https://tools.ietf.org/html/rfc7518#section-5"; rel="nofollow">content
encryption</a> algorithms.</p><h3
id="JAX-RSJOSE-KeyandContentEncryptionProviders">Key and Content Encryption
Providers</h3><p>JWE Encryption process typically involves a content-encryption
key being generated with this key being subsequently encrypted/wrapped with a
key known to the con
sumer. 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.</p><p><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/jwe/KeyEncryptionProvider.java";
rel="nofollow">KeyEncryptionProvider</a> supports encrypting a
content-encryption key, <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/jwe/KeyDecryptionProvider.java";
rel="nofollow">KeyDecryptionProvider</a> - decrypting it.</p><p>The following
table shows the key encryption algorithms and the corresponding providers
(<span class="pl-smi">org.apache.cxf.rs.security.jose.jwe</span>
package):</p><div class="table-wrap"><table cl
ass="confluenceTable"><tbody><tr><td colspan="1" rowspan="1"
class="confluenceTd"><strong>Algorithm</strong></td><td colspan="1" rowspan="1"
class="confluenceTd"><strong>JWE Header 'alg'</strong></td><td colspan="1"
rowspan="1" class="confluenceTd"><strong>KeyEncryptionProvider</strong></td><td
colspan="1" rowspan="1"
class="confluenceTd"><strong>KeyDecryptionProvider</strong></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><a shape="rect"
class="external-link" href="https://tools.ietf.org/html/rfc7518#section-4.2";
rel="nofollow">RSAES-PKCS1-v1_5</a></td><td colspan="1" rowspan="1"
class="confluenceTd"><p class="newpage">RSA1_5</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>RSAKeyEncryptionAlgorithm</p></td><td
colspan="1" rowspan="1"
class="confluenceTd"><p>RSAKeyDecryptionAlgorithm</p></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><a shape="rect"
class="external-link" href="https://tools.ietf.org/html/rfc7518#section-4.3";
rel="nofollow">R
SAES OAEP</a></td><td colspan="1" rowspan="1" class="confluenceTd"><p
class="newpage">RSA-OAEP, RSA-OAEP-256</p></td><td colspan="1" rowspan="1"
class="confluenceTd">RSAKeyEncryptionAlgorithm</td><td colspan="1" rowspan="1"
class="confluenceTd">RSAKeyDecryptionAlgorithm</td></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><a shape="rect" class="external-link"
href="https://tools.ietf.org/html/rfc7518#section-4.4"; rel="nofollow">AES Key
Wrap</a></td><td colspan="1" rowspan="1" class="confluenceTd"><p
class="newpage">A128KW, A192KW, A256KW</p></td><td colspan="1" rowspan="1"
class="confluenceTd">AesKeyWrapEncryptionAlgorithm</td><td colspan="1"
rowspan="1" class="confluenceTd">AesKeyWrapDecryptionAlgorithm</td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><a shape="rect"
class="external-link" href="https://tools.ietf.org/html/rfc7518#section-4.5";
rel="nofollow">Direct</a></td><td colspan="1" rowspan="1"
class="confluenceTd">dir</td><td colspan="1" rowspan="1" clas
s="confluenceTd">DirectKeyEncryptionAlgorithm</td><td colspan="1" rowspan="1"
class="confluenceTd">DirectKeyDecryptionAlgorithm</td></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><a shape="rect" class="external-link"
href="https://tools.ietf.org/html/rfc7518#page-15"; rel="nofollow">ECDH-ES Key
Wrap</a></td><td colspan="1" rowspan="1" class="confluenceTd"><p
class="newpage">ECDH-ES+A128KW (+A192KW, +256KW)</p></td><td colspan="1"
rowspan="1" class="confluenceTd">EcdhAesWrapKeyEncryptionAlgorithm</td><td
colspan="1" rowspan="1"
class="confluenceTd">EcdhAesWrapKeyDecryptionAlgorithm</td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><a shape="rect"
class="external-link" href="https://tools.ietf.org/html/rfc7518#page-15";
rel="nofollow">ECDH-ES Direct</a></td><td colspan="1" rowspan="1"
class="confluenceTd"><p class="newpage">ECDH-ES</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><span
class="pl-en">EcdhDirectKeyJweEncryption</span></td><td colspan="1" row
span="1" class="confluenceTd"><span
class="pl-en">EcdhDirectKeyJweDecryption</span></td></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><a shape="rect" class="external-link"
href="https://tools.ietf.org/html/rfc7518#section-4.7"; rel="nofollow">AES-GCM
Key Wrap</a></td><td colspan="1" rowspan="1" class="confluenceTd"><p
class="newpage">A128GCMKW, A192GCMKW, A256GCMKW</p></td><td colspan="1"
rowspan="1" class="confluenceTd">AesGcmWrapKeyEncryptionAlgorithm</td><td
colspan="1" rowspan="1"
class="confluenceTd">AesGcmWrapKeyDecryptionAlgorithm</td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><a shape="rect"
class="external-link" href="https://tools.ietf.org/html/rfc7518#section-4.8";
rel="nofollow">PBES2</a></td><td colspan="1" rowspan="1"
class="confluenceTd"><p class="newpage">PBES2-HS256+A128KW</p><p
class="newpage">PBES2-HS384+A192KW</p><p
class="newpage">PBES2-HS512+A256KW</p></td><td colspan="1" rowspan="1"
class="confluenceTd">PbesHmacAesWrapKeyEncryptionAlgo
rithm</td><td colspan="1" rowspan="1"
class="confluenceTd">PbesHmacAesWrapKeyDecryptionAlgorithm</td></tr></tbody></table></div><p> </p><p>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.</p><p>BouncyCastle is required if you use AES
Key or AES-GCM Key Wrap or PBES2 key encryption.</p><p><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/jwe/ContentEncryptionProvider.java";
rel="nofollow">ContentEncryptionProvider</a> supports encrypting a generated
content-encryption key, <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/jwe/ContentDecryptionProvider.java";
rel="nofollow">ContentDecryptionProvider</a> - decryptin
g it.</p><p>The following table shows the content encryption algorithms and
the corresponding providers:</p><div class="table-wrap"><table
class="confluenceTable"><tbody><tr><td colspan="1" rowspan="1"
class="confluenceTd"><strong>Algorithm</strong></td><td colspan="1" rowspan="1"
class="confluenceTd"><strong>JWE Header 'enc'</strong></td><td colspan="1"
rowspan="1"
class="confluenceTd"><strong>ContentEncryptionProvider</strong></td><td
colspan="1" rowspan="1"
class="confluenceTd"><strong>ContentDecryptionProvider</strong></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><a shape="rect"
class="external-link" href="https://tools.ietf.org/html/rfc7518#section-5.2";
rel="nofollow">AES_CBC_HMAC_SHA2</a></td><td colspan="1" rowspan="1"
class="confluenceTd"><p class="newpage">A128CBC-HS256(-HS384,
-HS512)</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>AesCbcHmacJweEncryption,</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>AesCbcHmacJweDecryption</p></
td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><a shape="rect"
class="external-link" href="https://tools.ietf.org/html/rfc7518#section-5.3";
rel="nofollow">AES-GCM</a></td><td colspan="1" rowspan="1"
class="confluenceTd"><p class="newpage">A128GCM, A92GCM, A256GCM</p></td><td
colspan="1" rowspan="1"
class="confluenceTd">AesGcmContentEncryptionAlgorithm</td><td colspan="1"
rowspan="1"
class="confluenceTd">AesGcmContentDecryptionAlgorithm</td></tr></tbody></table></div><p>All
of the above providers can be initialized with the keys loaded from JWK or
Java JKS stores or from the in-memory representations.</p><p>BouncyCastle is
required if you use AES_CBC_HMAC content encryption.</p><p>Once you have
decided which key and content encryption algorithms need to be supported you
can initialize <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/jwe/JweEncryptionProvide
r.java" rel="nofollow">JwsEncryptionProvider</a> and <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/jwe/JweDecryptionProvider.java";
rel="nofollow">JwsDecryptionProvider</a> which do the actual JWE
encryption/decryption work by coordinating with the key and content encryption
providers. CXF ships <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/jwe/JweEncryption.java";
rel="nofollow">JweEncryption</a> (JwsEncryptionProvider) and <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/jwe/JweDecryption.java";
rel="nofollow">JweDecryption</a> (JweDecryptionProvider) helpers, simply pass
them the preferred key and content encryption providers and have the
content encrypted or decrypted.</p><p>JweEncryption and JweDecryption help
with creating and processing JWE Compact sequences (see the next
section).  JweEncryption can also help with streaming JWE JSON sequences
(see JAX-RS JWE filters section).</p><p>Note that <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/jwe/AesCbcHmacJweEncryption.java";
rel="nofollow">AesCbcHmacJweEncryption</a> and <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/jwe/AesCbcHmacJweDecryption.java";
rel="nofollow">AesCbcHmacJweDecryption</a> providers supporting <a
shape="rect" class="external-link"
href="https://tools.ietf.org/html/rfc7518#section-5.2";
rel="nofollow">AES_CBC_HMAC_SHA2</a> contet encryption are extending
JweEncryption and JweDecryption respectively. They implemen
t <a shape="rect" class="external-link"
href="https://tools.ietf.org/html/rfc7518#section-5.2.2"; rel="nofollow">the
content encryption</a> internally but do accept preferred key
encryption/decryption providers.</p><p>Similarly, <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/jwe/DirectKeyJweEncryption.java";
rel="nofollow">DirectKeyJweEncryption</a> and <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/jwe/DirectKeyJweDecryption.java";
rel="nofollow">DirectKeyJweDecryption</a> are simple JweEncryption and
JweDecryption extensions making it straighforward to do the direct key content
encryption/decryption.</p><p><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/cx
f/rs/security/jose/jwe/JweUtils.java" rel="nofollow">JweUtils</a> utility
class has a lot of helper methods to load key and and content encryption
providers and get the data encrypted and decrypted.</p><h3
id="JAX-RSJOSE-JWECompact">JWE Compact</h3><p><a shape="rect"
class="external-link" href="https://tools.ietf.org/html/rfc7516#section-3.3";
rel="nofollow">JWE Compact representation</a> is the most often used JWE
sequence format. It is the concatenation of 5 parts: Base64URL-encoded sequence
of JWE headers (algorithm and other properties),  Base64URL-encoded
sequence of JWE encryption key (empty in case of the direct encryption),
Base64URL-encoded sequence of JWE Initialization vector, Base64URL-encoded
sequence of the produced ciphertext (encrypted data) and
finally Base64URL-encoded sequence of the authentication tag (integrity
protection for the headers and the ciphertext itself).</p><p><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/jwe/JweCompactProducer.java"
rel="nofollow">JweCompactProducer</a> and <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/jwe/JweCompactConsumer.java";
rel="nofollow">JweCompactConsumer</a> offer a basic support for creating and
consuming compact JWE sequences. In most cases you will likely prefer to use <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/jwe/JweEncryption.java";
rel="nofollow">JweEncryption</a> and <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/jwe/JweDecryption.java";
rel="nofollow">JweDecryption</a> instead: <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/jwe/JweEncryption.java";
rel="nofollow">JweEncryption</a> uses JweCompactProducer internally when its
<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/jwe/JweEncryptionProvider.java#L27";
rel="nofollow">encrypt</a> method is called (<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/jwe/JweEncryptionProvider.java#L32";
rel="nofollow">getEncryptedOutput</a> will be discussed in the JAX-RS JWE
filters section), and <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/jwe/JweDecryption.java";
rel="nofollow">JweDecryption</a> accepts
only JWE Compact and uses JweCompactConsumer internally.</p><p><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/jwe/JweJwtCompactProducer.java";
rel="nofollow">JweJwtCompactProducer</a> and <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/jws/JwsJwtCompactConsumer.java";
rel="nofollow">JwsJwtCompactConsumer</a> help with directly encrypting typed
JWT Tokens.</p><p>Here is the example of doing AES Key Wrap and AES CBC
HMAC in CXF:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>CXF Jwe
AesWrapAesCbcHMac</b></div><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Confluence"
style="font-size:12px;">final String specPlainText = "Live long and prosper.";
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">final String specPlainText = "Live long and prosper.";
AesWrapKeyEncryptionAlgorithm keyEncryption = new
AesWrapKeyEncryptionAlgorithm(KEY_ENCRYPTION_KEY_A3, KeyAlgorithm.A128KW);
JweEncryptionProvider encryption = new
AesCbcHmacJweEncryption(ContentAlgorithm.A128CBC_HS256,
@@ -299,7 +299,7 @@ JweDecryptionProvider decryption = new A
String decryptedText = decryption.decrypt(jweContent).getContentText();
assertEquals(specPlainText, decryptedText);</pre>
</div></div><p> </p><p>Here is another example using RSA-OAEP key
encryption and AES-GCM content encryption:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeHeader panelHeader pdl"
style="border-bottom-width: 1px;"><b>CXF Jwe RsaOaepAesGcm</b></div><div
class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Confluence"
style="font-size:12px;">final String content = "Live long and prosper.";
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">final String content = "Live long and prosper.";
// Load public RSA key from the JWK Key set stored on the disk
InputStream is = JsonWebKeyTest.class.getResourceAsStream(fileName);
JsonWebKeys keySet = JwkUtils.readJwkSet(is);
@@ -321,7 +321,7 @@ JweDecryptionProvider decryptor = JweUti
String decryptedText = decryption.decrypt(jweContent).getContentText();
assertEquals(content, decryptedText);</pre>
</div></div><h3 id="JAX-RSJOSE-JWEJSON">JWE JSON</h3><p>While JWE Compact is
optimized and represents a concatenation of 5 Base64URL values, JWE JSON is an
open JSON container, see <a shape="rect" class="external-link"
href="https://tools.ietf.org/html/rfc7516#appendix-A.4"; rel="nofollow">Appendix
A4</a>.</p><p>The most interesting feature of JWE JSON is that allows a content
be encrypted by multiple key encryption keys, with te resulting sequence
targeted at multiple recipients. For example,  the immediate consumer will
decrypt the content with its own key decryption key, forward the payload to the
next consumer, etc.  </p><p><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/jwe/JweJsonProducer.java";
rel="nofollow">JweJsonProducer</a> and <a shape="rect" class="external-link"
href="https://github.com/apache/cxf/blob/master/rt/rs/security/jose-parent/jose/src/m
ain/java/org/apache/cxf/rs/security/jose/jwe/JweJsonConsumer.java"
rel="nofollow">JweJsonConsumer</a> support producing and consuming JWS JSON
sequences.</p><p>Here is the code example:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeHeader panelHeader pdl"
style="border-bottom-width: 1px;"><b>CXF JweJson</b></div><div
class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Confluence"
style="font-size:12px;">final String text = "The true sign of intelligence is
not knowledge but imagination.";
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">final String text = "The true sign of intelligence is
not knowledge but imagination.";
// Create the secret keys for encrypting the content encryption key:
SecretKey wrapperKey1 = CryptoUtils.createSecretKeySpec(WRAPPER_BYTES1, "AES");
SecretKey wrapperKey2 = CryptoUtils.createSecretKeySpec(WRAPPER_BYTES2, "AES");
@@ -402,7 +402,7 @@ content = consumer.decryptWith(jwe2, Col
 </pre>
</div></div><p>If the sequence contains a single recipient entry only then the
JWE JSON 'recipients' array will contain a single entry, or the whole sequence
can be <a shape="rect" class="external-link"
href="https://tools.ietf.org/html/rfc7516#appendix-A.5";
rel="nofollow">flattened</a> instead with the actual 'recipients' array
dropped. JweJsonProducer  does not produce the flattened sequence when
only a single encryption is done by default because 3rd party JWE JSON
consumers may only be able to process the sequences with the 'recipients'
array, so pass a 'canBeFlat' flag to JwEJsonProducer if needed</p><p>Does it
make sense to use JWE JSON if you do not plan to do multiple encryptions ? Most
likely you will prefer JWE Compact if only a single recipient is
targeted.</p><h2 id="JAX-RSJOSE-JSONWebToken">JSON Web Token</h2><p><a
shape="rect" class="external-link" href="https://tools.ietf.org/html/rfc7519";
rel="nofollow">JWT</a> (JSON Web Token) is a collection of claims in JSON
format. It is simply a regular JSON document where each top elevel property is
called a 'claim'.</p><p>JWT can be JWS signed and/or JWE encrypted like any
other data structure.</p><p>JWT is mainly used in OAuth2 and OIDC applications
to represent self-contained OAuth2 access tokens, OIDC IdToken, UserInfo, but
can also be used in other contexts. For example, see the section below on
linking JWT authentication tokens to JWS or JWE secured payloads.</p><p>CXF
offers a JWT support in <a shape="rect" class="external-link"
href="https://github.com/apache/cxf/tree/master/rt/rs/security/jose-parent/jose/src/main/java/org/apache/cxf/rs/security/jose/jwt";
rel="nofollow">this package</a>. Typically one would create a set of claims
and submit them to JWS/JWE JWT processors, for example, see a JWS section
above.</p><h2 id="JAX-RSJOSE-JWSandJWECombined">JWS and JWE Combined</h2><p>If
you have a requirement to sign the data and then encrypt the signed payload
then it can be easily achieved by sel
ecting 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</p><h1 id="JAX-RSJOSE-JOSEJAX-RSFilters">JOSE JAX-RS
Filters</h1><p> </p><p>While working directly with JWS and JWE providers
may be needed in the application code, JAX-RS users writing the code like
this:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>Typical
JAX-RS code</b></div><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Confluence"
style="font-size:12px;">@Path("/bookstore")
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">@Path("/bookstore")
public class BookStore {
public BookStore() {
@@ -438,7 +438,7 @@ 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.</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: Confluence"
style="font-size:12px;"> public void testJwsJwkBookHMac() throws
Exception {
+<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);
Book book = bs.echoBook(new Book("book", 123L));
@@ -504,7 +504,7 @@ Payload:
]
}</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-SigningandVerificationofHTTPAttachments">Signing and
Verification of HTTP Attachments</h2><p>The signing and verification of HTTP
request and response attachments is supported starting from CXF
3.1.12.</p><p>This feature does not buffer the request and response attachment
data and is completely streaming-'friendly'.</p><p>Note that in some cases the
data may need to be buffered on the receiver end.</p><p>It depends on <a
shape="rect" class="external-link"
href="https://tools.ietf.org/html/rfc7515#appendix-F"; rel="nofollow">JWS with
Detached Content</
a> and  <a shape="rect" class="external-link"
href="https://tools.ietf.org/html/rfc7797"; rel="nofollow">JWS with Unencoded
Payload</a> options as well as on the newly introduced CXF <a shape="rect"
href="http://cxf.apache.org/docs/jax-rs-multiparts.html#JAX-RSMultiparts-MultipartFilters";>multipart
filters</a> and works as follows.</p><p>When request or response attachment
parts are about to be submitted to the Multipart serialization provider, JWS
Multipart Output Filter (<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/multipart/JwsMultipartClientRequestFilter.java";
rel="nofollow">JwsMultipartClientRequestFilter</a> and/or <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/multipart/JwsMultipartContainerResponseFilter.java";
rel="
nofollow">JwsMultipartContainerResponseFilter</a>) initializes 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/jws/JwsSignature.java";
rel="nofollow">JWSSignature</a> object. Next every parts's output stream is
replaced with the filtering output stream which updates the signature object on
every write operation. Finally this multipart filter adds one more attachment
part to the list of the attachments to be written - this part holds a reference
to JWS Signature. When this last part is written, JWSSignature produces the
signature bytes which are encoded using either JWS Compact or JWS JSON format,
with the detached and unencoded content already being pushed to the output
stream.</p><p>When the attachment parts are about to be read by the Multipart
deserialization provider, their signature carried over in the last part will
need to be verified. Just before the parts are
about to be read in order to be made available to the application code, JWS
Multipart Input Filter (<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/multipart/JwsMultipartContainerRequestFilter.java";
rel="nofollow">JwsMultipartContainerRequestFilter</a> and/or <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/multipart/JwsMultipartClientResponseFilter.java";
rel="nofollow">JwsMultipartClientResponseFilter</a>) checks the last part and
initializes 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/jws/JwsVerificationSignature.java";
rel="nofollow">JWSVerificationSignature</a> object. Next for every attachment
but the last o
ne it replaces the input stream with the filtering input stream which updates
the signature verification object on every read operation. Once all the data
have been read it compares the calculated signature with the received
signature.</p><p>Note when the attachments are accessed by the receiving
application code, the read process will fail to complete if the validation
fails. For example, if the application code copies a given part's InputStream
to the disk then this copy operation will fail. For
example:</p><p> </p><div class="code panel pdl" style="border-width:
1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Confluence"
style="font-size:12px;">@POST
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">@POST
@Path("/books")
@Consumes("multipart/related")
public void uploadBookMultipart(@Multipart(type = "application/xml") Book
book) {
@@ -524,7 +524,7 @@ public void uploadStreamMultipart(@Multi
</pre>
</div></div><p> </p><p>Note that besides the signature verification
process, CXF offers some other indirect support for ensuring the attachment
data have not been affected. For example, <a shape="rect"
href="http://cxf.apache.org/docs/jax-rs-multiparts.html#JAX-RSMultiparts-Readinglargeattachments";>the
size of the attachments can be restricted</a>, and if the data stream is
converted from XML then the conversion process will be controlled by the secure
XML parser. </p><p>However, if the receiver starts acting immediately on
the attachment's InputStream, for example, the attachment data returned from
the service to the client are streamed to a UI display which can activate a
script then it is important that a '<strong>bufferPayload</strong>' property is
enabled on either <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/multipart/JwsMultipartContaine
rRequestFilter.java" rel="nofollow">JwsMultipartContainerRequestFilter</a> or
<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/multipart/JwsMultipartClientResponseFilter.java";
rel="nofollow">JwsMultipartClientResponseFilter</a>. It will ensure that the
data streams are validated first before the application gets an access to
them.</p><p>The '<strong>bufferPayload</strong>' property may also need be
enabled if the multipart payload contains many attachment parts. In this case,
if the receiving code is written to consume all the parts in the order
different to the one the parts have been ordered in the multipart payload or if
the receiver code may optionally skip reading some of the parts, then the
'<strong>bufferPayload</strong>' property must be enabled.</p><p>Here is an
example showing how a Book object (represented as an XML attachment on the
wire) can be
secured.</p><p>Given this client code:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Confluence"
style="font-size:12px;">@Test
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">@Test
public void testJwsJwkBookHMacMultipart() throws Exception {
String address = "https://localhost:"; + PORT + "/jwsjwkhmacSinglePart";
BookStore bs = createJwsBookStoreHMac(address, true, false);
@@ -555,7 +555,7 @@ private BookStore createJwsBookStoreHMac
return bean.create(BookStore.class);
}</pre>
</div></div><p>and the relevant server code:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;">@Path("/bookstore")
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">@Path("/bookstore")
public class BookStore {
@POST
@@ -569,7 +569,7 @@ public class BookStore {
}
}</pre>
</div></div><p>and server configuration:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: xml; gutter: false; theme: Confluence"
style="font-size:12px;"><beans
xmlns="http://www.springframework.org/schema/beans";
xmlns:jaxrs="http://cxf.apache.org/jaxrs">
+<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"><beans
xmlns="http://www.springframework.org/schema/beans";
xmlns:jaxrs="http://cxf.apache.org/jaxrs">
<bean id="serviceBean"
class="org.apache.cxf.systest.jaxrs.security.jose.BookStore"/>
<bean id="jwsInMultipartFilter"
class="org.apache.cxf.rs.security.jose.jaxrs.multipart.JwsMultipartContainerRequestFilter"/>
<bean id="jwsOutMultipartFilter"
class="org.apache.cxf.rs.security.jose.jaxrs.multipart.JwsMultipartContainerResponseFilter"/>
@@ -645,7 +645,7 @@ INFO: JWE Headers:
"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: Confluence"
style="font-size:12px;"> public void testJweJwkAesWrap() throws Exception {
+<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);
@@ -681,7 +681,7 @@ Payload:
"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-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 location of the JOSE properties file where the JWS or JWE algorithm and key
store properties are set.</p><h3 id="JAX-RSJOSE-ProduceJOSEdat
a">Produce JOSE data</h3><p>If you need to protect some non JWT property -
extend or delegate to <strong>JoseProducer</strong>:</p><div class="code panel
pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Confluence"
style="font-size:12px;">import
org.apache.cxf.rs.security.jose.common.JoseProducer;
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">import
org.apache.cxf.rs.security.jose.common.JoseProducer;
@Path("service")
public class SecureService extends JoseProducer {
@GET
@@ -704,7 +704,7 @@ public class SecureService extends Abstr
}
}</pre>
</div></div><p>If you need to protect some JWT property then extend or
delegate to <strong>JoseJwtProducer</strong>:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Confluence"
style="font-size:12px;">import
org.apache.cxf.rs.security.jose.jwt.JoseJwtProducer;
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">import
org.apache.cxf.rs.security.jose.jwt.JoseJwtProducer;
@Path("service")
public class SecureService extends JoseJwtProducer {
@GET
@@ -730,7 +730,7 @@ public class SecureService extends Abstr
}
}</pre>
</div></div><p> In both cases the producer helpers will detect the
endpoint specific configuration thus they do not need to be preconfigured -
however if needed they have the 'encryptionProvider' and 'signatureProvider'
setters which can be used to inject JwsSignatureProvider and/or
JweEncryptionProvider instances instead.</p><p>The producer helpers require a
signature creation only by default. Use their 'setJwsRequired' or
'setJwsRequired' properties to customize it - example, disable JWS but require
JWE, or enable JWE to get JWS-protected data encrypted as well.</p><h3
id="JAX-RSJOSE-ConsumeJOSEdata">Consume JOSE data</h3><p>If you need to decrypt
and/or verify some non-JWT JOSE property - extend or delegate to
<strong>JoseConsumer</strong>:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Confluence"
style="font-size:12px;">import
org.apache.cxf.rs.security.jose.common.JoseConsumer;
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">import
org.apache.cxf.rs.security.jose.common.JoseConsumer;
@Path("service")
public class SecureService extends JoseConsumer {
@POST
@@ -753,7 +753,7 @@ public class SecureService extends Abstr
}
}</pre>
</div></div><p>If you need to decrypt and/or verify some JWT property
then extend or delegate to <strong>JoseJwtConsumer</strong>:</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Confluence"
style="font-size:12px;">import
org.apache.cxf.rs.security.jose.jwt.JoseJwtConsumer;
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">import
org.apache.cxf.rs.security.jose.jwt.JoseJwtConsumer;
@Path("service")
public class SecureService extends JoseJwtConsumer {
@POST
@@ -776,7 +776,7 @@ public class SecureService extends Abstr
}
}</pre>
</div></div><p> In both cases the producer helpers will detect the
endpoint specific configuration thus they do not need to be preconfigured -
however if needed they have the 'jweDecryptor' and 'jwsVerifier' setters which
can be used to inject JwsSignatureVerifier and/or JweDecryptionProvider
instances instead.</p><p>The producer helpers require a signature creation only
by default. Use their 'setJwsRequired' or 'setJwsRequired' properties to
customize it - example, disable JWS but require JWE, or enable JWE to get
JWS-protected data encrypted as well.</p><h3
id="JAX-RSJOSE-ProduceandConsumeJOSEdata">Produce and Consume JOSE
data</h3><p>If you need to produce and consumer some non-JWT JOSE properties-
extend or delegate to <strong>JoseProducerConsumer</strong>:</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Confluence"
style="font-size:12px;">import
org.apache.cxf.rs.security.jose.common.JoseProducerConsumer;
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">import
org.apache.cxf.rs.security.jose.common.JoseProducerConsumer;
@Path("service")
public class SecureService extends JoseProducerConsumer {
@POST
@@ -803,7 +803,7 @@ public class SecureService extends Abstr
}
}</pre>
</div></div><p>If you need to decrypt and/or verify some JWT property
then extend or delegate to <strong>JoseJwtProducerConsumer</strong>:</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Confluence"
style="font-size:12px;">import
org.apache.cxf.rs.security.jose.jwt.JoseJwtProducerConsumer;
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">import
org.apache.cxf.rs.security.jose.jwt.JoseJwtProducerConsumer;
@Path("service")
public class SecureService extends JoseJwtProducerConsumer {
@POST
@@ -830,7 +830,7 @@ public class SecureService extends Abstr
}
}</pre>
</div></div><p>In both cases this composite producer-consumer will use the
internal producer and/or consumer helpers which will detect the endpoint
specific configuration but which can also be injected with some specific JWE
and/or JWS handlers.</p><h3 id="JAX-RSJOSE-Configuretheendpoint">Configure the
endpoint</h3><p>These properties will contain a location of the key store,
signature and/or encryption algorithm properties, etc. See the <a shape="rect"
href="jax-rs-jose.html">Configuration section</a> for all the available
configuration options.</p><div class="code panel pdl" style="border-width:
1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: xml; gutter: false; theme: Confluence"
style="font-size:12px;"><beans
xmlns="http://www.springframework.org/schema/beans";
xmlns:jaxrs="http://cxf.apache.org/jaxrs">
+<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"><beans
xmlns="http://www.springframework.org/schema/beans";
xmlns:jaxrs="http://cxf.apache.org/jaxrs">
<bean id="serviceBean"
class="org.apache.cxf.systest.jaxrs.security.jose.SecureService"/>
<jaxrs:server address="/secure">
<jaxrs:serviceBeans>
@@ -843,13 +843,13 @@ public class SecureService extends Abstr
</jaxrs:server>
</beans</pre>
</div></div><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 operatio
ns. <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 prop
erties 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/ou
t 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">
-<pre class="brush: java; gutter: false; theme: Confluence"
style="font-size:12px;">JwsSignatureProvider jwsOut =
JwsUtils.loadSignatureProvider(true);
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">JwsSignatureProvider jwsOut =
JwsUtils.loadSignatureProvider(true);
JwsSignatureVerifier jwsIn = JwsUtils.loadSignatureVerifier(true);
JweEncryptionProvider jweOut = JweUtils.loadEncryptionProvider(true);
JweDecryptionProvider jweIn = JweUtils.loadDecryptionProvider(true);</pre>
</div></div><p>The providers may be initialized from a single properties file
or each of them may have specific properties allocated to it.</p><p>Sometimes
it can be useful to load the properties only and check the signature or
encryption algorithm and load a JWS or JWE provider directly as shown in JWS
and JWE sections above.</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 properties</b></div><div class="codeContent
panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Confluence"
style="font-size:12px;">Properties jwsProps =
JweUtils.loadEncryptionProperties("jws.properties", true);
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">Properties jwsProps =
JweUtils.loadEncryptionProperties("jws.properties", true);
Properties jweProps = JweUtils.loadEncryptionProperties("jwe.properties",
true);</pre>
[... 3 lines stripped ...]
Modified: websites/production/cxf/content/docs/jax-rs-maven-plugins.html
==============================================================================
--- websites/production/cxf/content/docs/jax-rs-maven-plugins.html (original)
+++ websites/production/cxf/content/docs/jax-rs-maven-plugins.html Wed Sep 13
15:05:52 2017
@@ -123,11 +123,11 @@ Apache CXF -- JAX-RS Maven Plugins
<style type="text/css">/*<![CDATA[*/
-div.rbtoc1505311188440 {padding: 0px;}
-div.rbtoc1505311188440 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1505311188440 li {margin-left: 0px;padding-left: 0px;}
+div.rbtoc1505314942987 {padding: 0px;}
+div.rbtoc1505314942987 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1505314942987 li {margin-left: 0px;padding-left: 0px;}
-/*]]>*/</style><div class="toc-macro rbtoc1505311188440">
+/*]]>*/</style><div class="toc-macro rbtoc1505314942987">
<ul class="toc-indentation"><li><a shape="rect"
href="#JAX-RSMavenPlugins-Introduction">Introduction</a></li><li><a
shape="rect" href="#JAX-RSMavenPlugins-Archetypes">Archetypes</a></li></ul>
</div>
@@ -144,7 +144,7 @@ div.rbtoc1505311188440 li {margin-left:
<p>Here is how you can use it from the command line.</p>
<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">
~/work/archetypes$
mvn archetype:generate -Dfilter=org.apache.cxf.archetype:
