cxf-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r989174 - in /websites/production/cxf/content: cache/docs.pageCache docs/jax-rs-jose.html
Date Thu, 26 May 2016 09:47:37 GMT
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>&#160;</p><p>&#160;</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&#160;</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>&#160;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>&#160;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>&#160;</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>&#160;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>&#160;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>&#160;</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;">&lt;dependency&gt;
   &lt;groupId&gt;org.apache.cxf&lt;/groupId&gt;
   &lt;artifactId&gt;cxf-rt-rs-security-jose&lt;/artifactId&gt;
@@ -151,7 +151,7 @@ div.rbtoc1464194817685 li {margin-left:
   &lt;version&gt;3.1.7&lt;/version&gt;
 &lt;/dependency&gt;
 </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;">&lt;dependency&gt;
      &lt;groupId&gt;org.bouncycastle&lt;/groupId&gt;
      &lt;artifactId&gt;bcprov-ext-jdk15on&lt;/artifactId&gt;
@@ -169,7 +169,7 @@ private static void registerBouncyCastle
 private static void unregisterBouncyCastle() throws Exception {
     Security.removeProvider(BouncyCastleProvider.PROVIDER_NAME);    
 }</pre>
-</div></div><p>&#160;</p><h1 id="JAX-RSJOSE-JavaandJCEPolicy">Java
and JCE Policy&#160;</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&#160;&#160;</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.&#160;</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,&#160;
SignatureAlgorithm.HS256 for JWS,&#160;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>&#160;</p><h1 id="JAX-RSJOSE-JavaandJCEPolicy">Java
and JCE Policy&#160;</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&#160;&#160;</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.&#160;</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,&#160;
SignatureAlgorithm.HS256 for JWS,&#160;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",



Mime
View raw message