Author: buildbot
Date: Thu May 26 09:47:37 2016
New Revision: 989174
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 May 26 09:47:37
2016
@@ -119,11 +119,11 @@ Apache CXF -- JAX-RS JOSE
<!-- Content -->
<div class="wiki-content">
<div id="ConfluenceContent"><p> </p><p> </p><p><style
type="text/css">/*<![CDATA[*/
-div.rbtoc1464194817685 {padding: 0px;}
-div.rbtoc1464194817685 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1464194817685 li {margin-left: 0px;padding-left: 0px;}
+div.rbtoc1464256020773 {padding: 0px;}
+div.rbtoc1464256020773 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1464256020773 li {margin-left: 0px;padding-left: 0px;}
-/*]]>*/</style></p><div class="toc-macro rbtoc1464194817685">
+/*]]>*/</style></p><div class="toc-macro rbtoc1464256020773">
<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>
@@ -137,7 +137,7 @@ div.rbtoc1464194817685 li {margin-left:
<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>
</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.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 for prot
ecting 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 OAuth2 and OIDC modules are also depending
on it.</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">
+</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 OAuth2 and OIDC modules are also depending
on it.</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: xml; gutter: false; theme: Default"
style="font-size:12px;"><dependency>
<groupId>org.apache.cxf</groupId>
<artifactId>cxf-rt-rs-security-jose</artifactId>
@@ -151,7 +151,7 @@ div.rbtoc1464194817685 li {margin-left:
<version>3.1.7</version>
</dependency>
</pre>
-</div></div><p>You may also need to include Bouncy Castle:</p><div class="code
panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</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: xml; gutter: false; theme: Default"
style="font-size:12px;"><dependency>
<groupId>org.bouncycastle</groupId>
<artifactId>bcprov-ext-jdk15on</artifactId>
@@ -169,7 +169,7 @@ private static void registerBouncyCastle
private static void unregisterBouncyCastle() throws Exception {
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: Java6 does
not support JWE AES-GCM at all while with BouncyCastle it is not possible to
submit JWE Header properties as an extra input to the encryption process to get
them integrity protected which is not JWE compliant.</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><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 Web 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 descr
ibing 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 effectivel
y 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
HMAC).</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 properties, recommended key sizes, other security considerations
related to all of or some specific algorithms. CXF JOSE code already enforces a
number of the recommended constraints.</p><p>CXF offers the utility support for
working with JWA algorit
hms 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 s
ecret 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">
+</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>JWE:</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>JWS:</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 Web 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 J
OSE, 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
HMAC).</p><div>The specification li
sts 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 properties, recommended key sizes, ot
her 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 ex
pect 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: Default" style="font-size:12px;">{
"kty":"oct",
"k":"AyM1SysPpbyDfgZld3umj1qzKObwVMkoqQ-EstJQLr_T-1qS0gZH75aKtMN3Yj0iPS4hcgUuTwjAzZr1Z9CAow",
