You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cxf.apache.org by bu...@apache.org on 2016/05/26 09:47:37 UTC
svn commit: r989174 - in /websites/production/cxf/content:
cache/docs.pageCache docs/jax-rs-jose.html
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",