cxf-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r988755 - in /websites/production/cxf/content: cache/docs.pageCache docs/jax-rs-jose.html
Date Fri, 20 May 2016 16:47:53 GMT
Author: buildbot
Date: Fri May 20 16:47:48 2016
New Revision: 988755

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 Fri May 20 16:47:48 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.rbtoc1463755621138 {padding: 0px;}
-div.rbtoc1463755621138 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1463755621138 li {margin-left: 0px;padding-left: 0px;}
+div.rbtoc1463762820975 {padding: 0px;}
+div.rbtoc1463762820975 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1463762820975 li {margin-left: 0px;padding-left: 0px;}
 
-/*]]>*/</style></p><div class="toc-macro rbtoc1463755621138">
+/*]]>*/</style></p><div class="toc-macro rbtoc1463762820975">
 <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>
@@ -156,7 +156,18 @@ div.rbtoc1463755621138 li {margin-left:
      &lt;version&gt;1.54&lt;/version&gt;
 &lt;/dependency&gt;
 </pre>
-</div></div><h1 id="JAX-RSJOSE-JavaandJCEPolicy">Java and JCE Policy&#160;</h1><p>Java7
or higher is recommended for 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 the size of the encrypting 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 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 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 either 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, etc).</p><div>The specification lists all the algorithms that can be used
either for signing or encrypting and also describes how some of these algorithms work in cases</div><div>where
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 the algorithm properties 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 algorith
 ms 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 se
 cret 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>BouncyCastle provider can be registered 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: Default" style="font-size:12px;">import
java.security.Security;
+import org.bouncycastle.jce.provider.BouncyCastleProvider;
+
+private static void registerBouncyCastle() throws Exception {
+    Security.addProvider(new BouncyCastleProvider());    
+}
+
+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 for 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 encrypting 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 desc
 ribing 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 effective
 ly 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 either
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, etc).</p><div>The
specification lists all the algorithms that can be used either for signing or encrypting and
also describes how some of these algorithms work in cases</div><div>where JCA
(or BouncyCastle) does not support them directly, example, A
 ES-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 the algorithm properties 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 J
 WA 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 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: Default" style="font-size:12px;">{
    "kty":"oct",
    "k":"AyM1SysPpbyDfgZld3umj1qzKObwVMkoqQ-EstJQLr_T-1qS0gZH75aKtMN3Yj0iPS4hcgUuTwjAzZr1Z9CAow",
@@ -339,7 +350,16 @@ JweJsonConsumer c = new JweJsonConsumer(
 String content = consumer.decryptWith(jweDecrypt).getContent();
 
 </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 &#160;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 offers a standard JSON container for representing various properties or claims.</p><p>JWT
can be signed and or encrypted, i.e, serve as a JOSE signature or encryption input like any
other data structure.</p><p>JWT has been primarily used in OAuth2 applications
to represent self-contained access tokens but can also be used in other contexts.</p><p>CXF
offers an initial 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>.</p><h1 id="JAX-RSJOSE-JOSEJAX-RSFilters">JOSE
JAX-RS Filters</h1><h2 id="JAX-RSJOSE-JWS">JWS</h2><h2 id="JAX-RSJOSE-JWE">JWE</h2><h2
id="JAX-RSJOSE-LinkingJWTauthenticationstoJWSorJWEcontent">Linking JWT authentications
to JWS or JWE content</h2><p>&#160;</p><h1 id="JAX-RSJOSE-Configuration">Configuration</h1><h4
id="JAX-RSJOSE-Configurationthatappliestobothencryptionandsignature">Configuration 
 that applies to both encryption and signature</h4><div class="table-wrap"><table
class="confluenceTable"><tbody><tr><td colspan="1" rowspan="1" class="confluenceTd">rs.security.keystore</td><td
colspan="1" rowspan="1" class="confluenceTd">The Java KeyStore Object to use. This configuration
tag is used if you want to pass the KeyStore Object through dynamically.</td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p>rs.security.keystore.type</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>The keystore type. Suitable values
are "jks" or "jwk".</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd">rs.security.keystore.password</td><td colspan="1" rowspan="1"
class="confluenceTd">The password required to access the keystore.</td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd">rs.security.keystore.alias</td><td
colspan="1" rowspan="1" class="confluenceTd">&#160;The keystore alias corresponding
to the key to use. You can append one of the follow
 ing to this tag to get the alias for more specific operations:<br clear="none">&#160;&#160;&#160;&#160;
- jwe.out<br clear="none">&#160;&#160;&#160;&#160; - jwe.in<br clear="none">&#160;&#160;&#160;&#160;
- jws.out<br clear="none">&#160;&#160;&#160;&#160; - jws.in</td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd">rs.security.keystore.aliases</td><td
colspan="1" rowspan="1" class="confluenceTd">The keystore aliases corresponding to the
keys to use, when using the JSON serialization form. You can append one of the following to
this tag to get the alias for more specific operations:<br clear="none">&#160;&#160;&#160;&#160;
- jws.out<br clear="none">&#160;&#160;&#160;&#160; - jws.in</td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd">rs.security.keystore.file</td><td
colspan="1" rowspan="1" class="confluenceTd">The path to the keystore file.</td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd">rs.security.key.password</td><td
colspan="1" rowspan="1" class=
 "confluenceTd">The password required to access the private key (in the keystore).</td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd">rs.security.key.password.provider</td><td
colspan="1" rowspan="1" class="confluenceTd">A reference to a PrivateKeyPasswordProvider
instance used to retrieve passwords to access keys.</td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd">rs.security.accept.public.key</td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Whether to allow using a JWK received
in the header for signature validation. The default is "false".</p></td></tr></tbody></table></div><h4
id="JAX-RSJOSE-Configurationthatappliestosignatureonly">Configuration that applies to signature
only</h4><div class="table-wrap"><table class="confluenceTable"><tbody><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p>rs.security.signature.key.password.provider</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>A reference to a PrivateKeyPasswordProvider
instance u
 sed to retrieve passwords to access keys for signature. If this is not specified it falls
back to use "rs.security.key.password.provider".</p></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd">rs.security.signature.algorithm</td><td
colspan="1" rowspan="1" class="confluenceTd">The signature algorithm to use. The default
algorithm if not specified is 'RS256'.</td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd">rs.security.signature.out.properties</td><td colspan="1"
rowspan="1" class="confluenceTd"><p>The signature properties file for compact signature
creation. If not specified then it falls back to "rs.security.signature.properties".</p></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd">rs.security.signature.in.properties</td><td
colspan="1" rowspan="1" class="confluenceTd"><p>The signature properties file for
compact signature verification. If not specified then it falls back to "rs.security.signature.properties".</p></td></tr><tr><td
colspan="1" 
 rowspan="1" class="confluenceTd">rs.security.signature.properties</td><td colspan="1"
rowspan="1" class="confluenceTd">The signature properties file for compact signature creation/verification.</td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd">rs.security.signature.include.public.key</td><td
colspan="1" rowspan="1" class="confluenceTd">Include the JWK public key for signature in
the "jwk" header.</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">rs.security.signature.include.cert</td><td
colspan="1" rowspan="1" class="confluenceTd">Include the X.509 certificate for signature
in the "x5c" header.</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">rs.security.signature.include.key.id</td><td
colspan="1" rowspan="1" class="confluenceTd">Include the JWK key id for signature in the
"kid" header.</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">rs.security.signature.include.cert.sha1</td><td
colspan="1" rowspan="1" class="confluenceTd">Inclu
 de the X.509 certificate SHA-1 digest for signature in the "x5t" header.</td></tr></tbody></table></div><h4
id="JAX-RSJOSE-Configurationthatappliestoencryptiononly">Configuration that applies to
encryption only</h4><div class="table-wrap"><table class="confluenceTable"><tbody><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p>rs.security.decryption.key.password.provider</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>A reference to a PrivateKeyPasswordProvider
instance used to retrieve passwords to access keys for decryption. If this is not specified
it falls back to use "rs.security.key.password.provider".</p></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd">rs.security.encryption.content.algorithm</td><td
colspan="1" rowspan="1" class="confluenceTd">The encryption content algorithm to use. The
default algorithm if not specified is 'A128GCM'.</td></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd">rs.security.encryption.key.algorithm</td><td
cols
 pan="1" rowspan="1" class="confluenceTd"><p>The encryption key algorithm to use.
The default algorithm if not specified is 'RSA-OAEP' if the key is an RSA key, and 'A128GCMKW'
if it is an octet sequence.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd">rs.security.encryption.zip.algorithm</td><td colspan="1"
rowspan="1" class="confluenceTd">The encryption zip algorithm to use.</td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd">rs.security.encryption.out.properties</td><td
colspan="1" rowspan="1" class="confluenceTd"><p>The signature properties file for
encryption creation. If not specified then it falls back to "rs.security.encryption.properties".</p></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd">rs.security.encryption.in.properties</td><td
colspan="1" rowspan="1" class="confluenceTd"><p>The signature properties file for
decryption. If not specified then it falls back to "rs.security.encryption.properties".</p></td></tr><tr><td
colspan="1"
  rowspan="1" class="confluenceTd">rs.security.encryption.properties</td><td colspan="1"
rowspan="1" class="confluenceTd">The signature properties file for encryption/decryption.</td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd">rs.security.encryption.include.public.key</td><td
colspan="1" rowspan="1" class="confluenceTd">Include the JWK public key for&#160;encryption
in the "jwk" header.</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">rs.security.encryption.include.cert</td><td
colspan="1" rowspan="1" class="confluenceTd">Include the X.509 certificate for&#160;encryption
in the "x5c" header.</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">rs.security.encryption.include.key.id</td><td
colspan="1" rowspan="1" class="confluenceTd">Include the JWK key id for&#160;encryption
in the "kid" header.</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">rs.security.encryption.include.cert.sha1</td><td
colspan="1" rowspan="1" class="confluenceTd"
 >Include the X.509 certificate SHA-1 digest for&#160;encryption in the "x5t" header.</td></tr></tbody></table></div><h4
id="JAX-RSJOSE-ConfigurationthatappliestoJWTtokensonly">Configuration that applies to JWT
tokens only</h4><div class="table-wrap"><table class="confluenceTable"><tbody><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p>rs.security.enable.unsigned-jwt.principal</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Whether to allow unsigned JWT tokens
as SecurityContext Principals. The default is false.</p></td></tr></tbody></table></div><p>&#160;</p><h1
id="JAX-RSJOSE-Interoperability">Interoperability</h1><h1 id="JAX-RSJOSE-Third-PartyLibraries">Third-Party
Libraries</h1><p><a shape="rect" class="external-link" href="https://bitbucket.org/b_c/jose4j/wiki/Home"
rel="nofollow">Jose4J</a></p><p><a shape="rect" class="external-link"
href="http://connect2id.com/products/nimbus-jose-jwt" rel="nofollow">Nimbus JOSE</a></p><p>&#160;</p><p>&#160;</p><p>&#160;</p>
 </div>
+</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 &#160;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 offers a standard JSON container for representing various properties or claims.</p><p>JWT
can be signed and or encrypted, i.e, serve as a JOSE signature or encryption input like any
other data structure.</p><p>JWT has been primarily used in OAuth2 applications
to represent self-contained access tokens but can also be used in other contexts.</p><p>CXF
offers an initial 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>.</p><h1 id="JAX-RSJOSE-JOSEJAX-RSFilters">JOSE
JAX-RS Filters</h1><h2 id="JAX-RSJOSE-JWS">JWS</h2><h2 id="JAX-RSJOSE-JWE">JWE</h2><h2
id="JAX-RSJOSE-LinkingJWTauthenticationstoJWSorJWEcontent">Linking JWT authentications
to JWS or JWE content</h2><p>&#160;</p><h1 id="JAX-RSJOSE-Configuration">Configuration</h1><p>CXF
JOSE configuration provides for loading JWS and JWE keys and supporting various 
 processing options. Configuration properties can be shared between JWS and JWE 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 operations. <a shape="rect" class="external-link"
href="https://github.com/apache/cxf/blob/master/systests/rs-security/src/test/resources/org/apache/cxf/systes
 t/jaxrs/security/jose/jwejws/server.xml#L210" rel="nofollow">This endpoint</a> depends
on <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/systests/rs-security/src/test/resources/org/apache/cxf/systest/jaxrs/security/jose/jwejws/server.xml#L218"
rel="nofollow">two JWS properties files</a>, one - for input JWS, another one - for
output JWS. Similarly, <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/systests/rs-security/src/test/resources/org/apache/cxf/systest/jaxrs/security/jose/jwejws/server.xml#L153"
rel="nofollow">this endpoint</a> uses a <a shape="rect" class="external-link"
href="https://github.com/apache/cxf/blob/master/systests/rs-security/src/test/resources/org/apache/cxf/systest/jaxrs/security/jose/jwejws/server.xml#L162"
rel="nofollow">single JWE properties file</a> for encrypting/decrypting the data,
while <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/systest
 s/rs-security/src/test/resources/org/apache/cxf/systest/jaxrs/security/jose/jwejws/server.xml#L139"
rel="nofollow">this endpoint</a> uses <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/systests/rs-security/src/test/resources/org/apache/cxf/systest/jaxrs/security/jose/jwejws/server.xml#L139"
rel="nofollow">two JWE properties files</a>. <a shape="rect" class="external-link"
href="https://github.com/apache/cxf/blob/master/systests/rs-security/src/test/resources/org/apache/cxf/systest/jaxrs/security/jose/jwejws/server.xml#L178"
rel="nofollow">This endpoint</a> support both JWS and JSON with <a shape="rect"
class="external-link" href="https://github.com/apache/cxf/blob/master/systests/rs-security/src/test/resources/org/apache/cxf/systest/jaxrs/security/jose/jwejws/server.xml#L189"
rel="nofollow">in/out specific properties</a>. If either JWS or JWE private key needs
to be loaded from the password-protected storage (JKS, encryped JWK)&#160; then a&#16
 0;<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.&#160;</p><p>If
you need to do JWS or JWE pro
 cessing 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: 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: Default" style="font-size:12px;">Properties
jwsProps = JweUtils.loadEncryptionProperties("jws.properties", true);
+Properties jweProps = JweUtils.loadEncryptionProperties("jwe.properties", true);</pre>
+</div></div><p>After loading the properties one can check various property
values (signature algorithm, etc) and use it to create a required provider.</p><p>The
above code needs to be executed in the context of the current request (in server or client
in/out interceptors or server service code) as it expects the current CXF Message be available
in order to deduce where to load the configuration properties from. However&#160;<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> and&#160;<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/JweUtils.java"
rel="nofollow">JweUtils</a> provide a number of utility methods for loading the providers
without loading the properties first which can be used when setting up the c
 lient code or when no properties are available in the current request context.</p><p>&#160;</p><h3
id="JAX-RSJOSE-Configurationthatappliestobothencryptionandsignature">Configuration that
applies to both encryption and signature</h3><div class="table-wrap"><table
class="confluenceTable"><tbody><tr><td colspan="1" rowspan="1" class="confluenceTd">rs.security.keystore</td><td
colspan="1" rowspan="1" class="confluenceTd">The Java KeyStore Object to use. This configuration
tag is used if you want to pass the KeyStore Object through dynamically.</td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p>rs.security.keystore.type</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>The keystore type. Suitable values
are "jks" or "jwk".</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd">rs.security.keystore.password</td><td colspan="1" rowspan="1"
class="confluenceTd">The password required to access the keystore.</td></tr><tr><td
colspan="1" rowspan="1" class="co
 nfluenceTd">rs.security.keystore.alias</td><td colspan="1" rowspan="1" class="confluenceTd">&#160;The
keystore alias corresponding to the key to use. You can append one of the following to this
tag to get the alias for more specific operations:<br clear="none">&#160;&#160;&#160;&#160;
- jwe.out<br clear="none">&#160;&#160;&#160;&#160; - jwe.in<br clear="none">&#160;&#160;&#160;&#160;
- jws.out<br clear="none">&#160;&#160;&#160;&#160; - jws.in</td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd">rs.security.keystore.aliases</td><td
colspan="1" rowspan="1" class="confluenceTd">The keystore aliases corresponding to the
keys to use, when using the JSON serialization form. You can append one of the following to
this tag to get the alias for more specific operations:<br clear="none">&#160;&#160;&#160;&#160;
- jws.out<br clear="none">&#160;&#160;&#160;&#160; - jws.in</td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd">rs.security.keystore.file</td><td
colspan="1" rowspan
 ="1" class="confluenceTd">The path to the keystore file.</td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd">rs.security.key.password</td><td
colspan="1" rowspan="1" class="confluenceTd">The password required to access the private
key (in the keystore).</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">rs.security.key.password.provider</td><td
colspan="1" rowspan="1" class="confluenceTd">A reference to a PrivateKeyPasswordProvider
instance used to retrieve passwords to access keys.</td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd">rs.security.accept.public.key</td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Whether to allow using a JWK received
in the header for signature validation. The default is "false".</p></td></tr></tbody></table></div><h3
id="JAX-RSJOSE-Configurationthatappliestosignatureonly">Configuration that applies to signature
only</h3><div class="table-wrap"><table class="confluenceTable"><tbody><tr><td
colspan="1" rowspan="1" 
 class="confluenceTd"><p>rs.security.signature.key.password.provider</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>A reference to a PrivateKeyPasswordProvider
instance used to retrieve passwords to access keys for signature. If this is not specified
it falls back to use "rs.security.key.password.provider".</p></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd">rs.security.signature.algorithm</td><td
colspan="1" rowspan="1" class="confluenceTd">The signature algorithm to use. The default
algorithm if not specified is 'RS256'.</td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd">rs.security.signature.out.properties</td><td colspan="1"
rowspan="1" class="confluenceTd"><p>The signature properties file for compact signature
creation. If not specified then it falls back to "rs.security.signature.properties".</p></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd">rs.security.signature.in.properties</td><td
colspan="1" rowspan="1" class="confluenc
 eTd"><p>The signature properties file for compact signature verification. If not
specified then it falls back to "rs.security.signature.properties".</p></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd">rs.security.signature.properties</td><td
colspan="1" rowspan="1" class="confluenceTd">The signature properties file for compact
signature creation/verification.</td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd">rs.security.signature.include.public.key</td><td colspan="1"
rowspan="1" class="confluenceTd">Include the JWK public key for signature in the "jwk"
header.</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">rs.security.signature.include.cert</td><td
colspan="1" rowspan="1" class="confluenceTd">Include the X.509 certificate for signature
in the "x5c" header.</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">rs.security.signature.include.key.id</td><td
colspan="1" rowspan="1" class="confluenceTd">Include the JWK key id for signature
  in the "kid" header.</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">rs.security.signature.include.cert.sha1</td><td
colspan="1" rowspan="1" class="confluenceTd">Include the X.509 certificate SHA-1 digest
for signature in the "x5t" header.</td></tr></tbody></table></div><h3
id="JAX-RSJOSE-Configurationthatappliestoencryptiononly">Configuration that applies to
encryption only</h3><div class="table-wrap"><table class="confluenceTable"><tbody><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p>rs.security.decryption.key.password.provider</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>A reference to a PrivateKeyPasswordProvider
instance used to retrieve passwords to access keys for decryption. If this is not specified
it falls back to use "rs.security.key.password.provider".</p></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd">rs.security.encryption.content.algorithm</td><td
colspan="1" rowspan="1" class="confluenceTd">The encryption content 
 algorithm to use. The default algorithm if not specified is 'A128GCM'.</td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd">rs.security.encryption.key.algorithm</td><td
colspan="1" rowspan="1" class="confluenceTd"><p>The encryption key algorithm to use.
The default algorithm if not specified is 'RSA-OAEP' if the key is an RSA key, and 'A128GCMKW'
if it is an octet sequence.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd">rs.security.encryption.zip.algorithm</td><td colspan="1"
rowspan="1" class="confluenceTd">The encryption zip algorithm to use.</td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd">rs.security.encryption.out.properties</td><td
colspan="1" rowspan="1" class="confluenceTd"><p>The signature properties file for
encryption creation. If not specified then it falls back to "rs.security.encryption.properties".</p></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd">rs.security.encryption.in.properties</td><td
colspan="1" rowspan=
 "1" class="confluenceTd"><p>The signature properties file for decryption. If not
specified then it falls back to "rs.security.encryption.properties".</p></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd">rs.security.encryption.properties</td><td
colspan="1" rowspan="1" class="confluenceTd">The signature properties file for encryption/decryption.</td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd">rs.security.encryption.include.public.key</td><td
colspan="1" rowspan="1" class="confluenceTd">Include the JWK public key for&#160;encryption
in the "jwk" header.</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">rs.security.encryption.include.cert</td><td
colspan="1" rowspan="1" class="confluenceTd">Include the X.509 certificate for&#160;encryption
in the "x5c" header.</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">rs.security.encryption.include.key.id</td><td
colspan="1" rowspan="1" class="confluenceTd">Include the JWK key id for&#160;encry
 ption in the "kid" header.</td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd">rs.security.encryption.include.cert.sha1</td><td colspan="1"
rowspan="1" class="confluenceTd">Include the X.509 certificate SHA-1 digest for&#160;encryption
in the "x5t" header.</td></tr></tbody></table></div><h3 id="JAX-RSJOSE-ConfigurationthatappliestoJWTtokensonly">Configuration
that applies to JWT tokens only</h3><div class="table-wrap"><table class="confluenceTable"><tbody><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p>rs.security.enable.unsigned-jwt.principal</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Whether to allow unsigned JWT tokens
as SecurityContext Principals. The default is false.</p></td></tr></tbody></table></div><p>&#160;</p><h1
id="JAX-RSJOSE-Interoperability">Interoperability</h1><h1 id="JAX-RSJOSE-Third-PartyLibraries">Third-Party
Libraries</h1><p><a shape="rect" class="external-link" href="https://bitbucket.org/b_c/jose4j/wiki/Home"
rel="nofollow">
 Jose4J</a></p><p><a shape="rect" class="external-link" href="http://connect2id.com/products/nimbus-jose-jwt"
rel="nofollow">Nimbus JOSE</a></p><p>&#160;</p><p>&#160;</p><p>&#160;</p></div>
            </div>
            <!-- Content -->
          </td>




Mime
View raw message