Return-Path: X-Original-To: archive-asf-public-internal@cust-asf2.ponee.io Delivered-To: archive-asf-public-internal@cust-asf2.ponee.io Received: from cust-asf.ponee.io (cust-asf.ponee.io [163.172.22.183]) by cust-asf2.ponee.io (Postfix) with ESMTP id 52CDB2009EE for ; Wed, 18 May 2016 12:47:54 +0200 (CEST) Received: by cust-asf.ponee.io (Postfix) id 5120B160A00; Wed, 18 May 2016 10:47:54 +0000 (UTC) Delivered-To: archive-asf-public@cust-asf.ponee.io Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by cust-asf.ponee.io (Postfix) with SMTP id 7E8F11609B1 for ; Wed, 18 May 2016 12:47:52 +0200 (CEST) Received: (qmail 31101 invoked by uid 500); 18 May 2016 10:47:51 -0000 Mailing-List: contact commits-help@cxf.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@cxf.apache.org Delivered-To: mailing list commits@cxf.apache.org Received: (qmail 31092 invoked by uid 99); 18 May 2016 10:47:51 -0000 Received: from pnap-us-west-generic-nat.apache.org (HELO spamd3-us-west.apache.org) (209.188.14.142) by apache.org (qpsmtpd/0.29) with ESMTP; Wed, 18 May 2016 10:47:51 +0000 Received: from localhost (localhost [127.0.0.1]) by spamd3-us-west.apache.org (ASF Mail Server at spamd3-us-west.apache.org) with ESMTP id 252911805E8 for ; Wed, 18 May 2016 10:47:51 +0000 (UTC) X-Virus-Scanned: Debian amavisd-new at spamd3-us-west.apache.org X-Spam-Flag: NO X-Spam-Score: 2.049 X-Spam-Level: ** X-Spam-Status: No, score=2.049 tagged_above=-999 required=6.31 tests=[KAM_ASCII_DIVIDERS=0.8, KAM_LAZY_DOMAIN_SECURITY=1, KAM_LOTSOFHASH=0.25, RP_MATCHES_RCVD=-0.001] autolearn=disabled Received: from mx2-lw-us.apache.org ([10.40.0.8]) by localhost (spamd3-us-west.apache.org [10.40.0.10]) (amavisd-new, port 10024) with ESMTP id qm4eAvAKAZ-0 for ; Wed, 18 May 2016 10:47:42 +0000 (UTC) Received: from mailrelay1-us-west.apache.org (mailrelay1-us-west.apache.org [209.188.14.139]) by mx2-lw-us.apache.org (ASF Mail Server at mx2-lw-us.apache.org) with ESMTP id 5FA925F484 for ; Wed, 18 May 2016 10:47:42 +0000 (UTC) Received: from svn01-us-west.apache.org (svn.apache.org [10.41.0.6]) by mailrelay1-us-west.apache.org (ASF Mail Server at mailrelay1-us-west.apache.org) with ESMTP id 87710E0099 for ; Wed, 18 May 2016 10:47:41 +0000 (UTC) Received: from svn01-us-west.apache.org (localhost [127.0.0.1]) by svn01-us-west.apache.org (ASF Mail Server at svn01-us-west.apache.org) with ESMTP id A754C3A0239 for ; Wed, 18 May 2016 10:47:40 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r988524 - in /websites/production/cxf/content: cache/docs.pageCache docs/jax-rs-jose.html Date: Wed, 18 May 2016 10:47:40 -0000 To: commits@cxf.apache.org From: buildbot@apache.org X-Mailer: svnmailer-1.0.9 Message-Id: <20160518104740.A754C3A0239@svn01-us-west.apache.org> archived-at: Wed, 18 May 2016 10:47:54 -0000 Author: buildbot Date: Wed May 18 10:47:40 2016 New Revision: 988524 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 Wed May 18 10:47:40 2016 @@ -119,19 +119,19 @@ Apache CXF -- JAX-RS JOSE

 

 

+/*]]>*/

-

Introduction

JOSE 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 some other format (plain text, XML, binary data).

JOSE is a key piece of the advanced OAuth2-based applications such as OpenIdConnect but can also be successfully used for securing the regular HTTP web service communications.

CXF 3.1.x and 3.2.0 provides a complete implementation of JOSE.

M aven Dependencies

 

Having the following dependency will let the developers write JOSE code: creating and securing JSON Web Tokens (JWT), and securing the arbitrary data (not only JSON)

+
  • OAuth2 and Jose
  • OIDC and Jose
  • Future Work
  • Third-Party Alternatives
    • +

    Introduction

    JOSE 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 format (plain text, XML, binary data).

    JOSE is a key piece of the advanced OAuth2-based applications such as OpenIdConnect but can also be successfully used for securing the regular HTTP web service communications.

    CXF 3.1.x and 3.2.0 provides a complete implementation of JOSE.

    Maven Dependencies

     

    Having the following dependency will let the developers write JOSE code: creating and securing JSON Web Tokens (JWT), and securing the arbitrary data (not only JSON)

    <dependency>
   <groupId>org.apache.cxf</groupId>
   <artifactId>cxf-rt-rs-security-jose</artifactId>
@@ -145,7 +145,7 @@ div.rbtoc1463503618227 li {margin-left:
   <version>3.1.7</version>
 </dependency>
    -
     

    JOSE Overview

    JOSE consists of the following key parts:

    • JWA - JSON Web Algorithms where all supported signature and encryption algorithms are listed
    • JWK - JSON Web Keys - introduces a JSON format for describing the public and private keys used by JWA algorithms
    • JWS - JSON Web Signature - describes how the data can be signed or validated and introduces compact and JSON JWS formats for representing the signed data
    • JWE - JSON Web Encryption - describes how the data can be encrypted or decryp ted and introduces compact and JSON JWE formats for representing the encrypted data  

    Additionally, JWT (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). JWT describes how a set of claims in a JSON format can be either JWS-signed or JWE-enctypted. 

    JWA Algorithms

    All JOSE signature and encryption algorithms are grouped and described in JSON Web Algorithms (JWA) specification.

    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).

    All JWS and JWE algorithms process the meta-data (the algorithm properties) and the actual data thus also ensuring the algorithm properties are integrity-protected, additionally JWE algorithms produce authentication tags which ensure the already encrypted content won't be manipulated.

    Please refer to the specification 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 rec ommended constraints.

    CXF offers the utility support for working with JWA algorithms in this package. Typically one would supply an algorithm property in a type-safe way either to JWS or JWE processor, for example,  SignatureAlgorithm.HS256 (HMAC signature) for JWS, KeyAlgorithm.A256KW (key encryption wrap) plus ContentAlgorithm.A256GCM for JWE.

    JWK Keys

    JSON Web Key (JWK) 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 use a JWK in o rder to sign or encrypt the document and rely on Java JCA secret and asymmetric key representations instead, JWK is a preferred representation of JWS/JWE keys.

    For example:

    Jwk Signature Key
    +
     

    JOSE Overview

    JOSE consists of the following key parts:

    • JWA - JSON Web Algorithms where all supported signature and encryption algorithms are listed
    • JWK - JSON Web Keys - introduces a JSON format for describing the public and private keys used by JWA algorithms
    • JWS - JSON Web Signature - describes how the data can be signed or validated and introduces compact and JSON JWS formats for representing the signed data
    • JWE - JSON Web Encryption - describes how the data can be encrypted or decryp ted and introduces compact and JSON JWE formats for representing the encrypted data  

    Additionally, JWT (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). JWT describes how a set of claims in JSON format can be either JWS-signed and/or JWE-enctypted. 

    JWA Algorithms

    All JOSE signature and encryption algorithms are grouped and described in the JWA (JSON Web Algorithms) specification.

    The algor ithms 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).

    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
    where JCA (or BouncyCastle) does not support them directly, example, AES-CBC-HMAC-SHA2.
    Algorithm name is a type + hint, example: HS256 (HMAC with SHA-256), RSA-OAEP-256 (RSA OAEP key encryption with SHA-256), etc.

    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.

    Please refer to the specification 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.

    CXF offers the utility support for working with JWA algorithms in this package.

    Typically one would supply an algorithm property in a type-safe way either to JWS or JWE processor, for example,  SignatureAlgorithm.HS256 (HMAC signature) for JWS, KeyAlgorithm.A256KW (key encryption wrap) plus ContentAlgorithm.A256GCM for JWE. Each enum has methods fo r checking a key size, JWA and Java JCA algorithm names.

    JWK Keys

    JWK (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.

    For example:

    Secret HMAC Key
    {
    "kty":"oct",
    "k":"AyM1SysPpbyDfgZld3umj1qzKObwVMkoqQ-EstJQLr_T-1qS0gZH75aKtMN3Yj0iPS4hcgUuTwjAzZr1Z9CAow",
@@ -163,7 +163,7 @@ div.rbtoc1463503618227 li {margin-left:
   "e":"AQAB",
   "alg":"RS256",
   "kid":"Public RSA Key"}
    -

     

    A collection of JWK keys is called a JWK Key Set.

    CXF offers a utility support for reading and writing JWK keys and key sets and for working with the encrypted inlined and standalone JWK stores in this package. For example, here is how an encrypted inlined JWK key is stored. Similarly, here is how a collection of keys is inlined. In other cases users can refer to a file containing the set of keys.

    Support for the pluggable strategies for loading JWKs is on the map.

    JWS Signature

    JSON Web Signature (JWS) document describes how a document content can be signed. For example, Appendix A1 shows how the content can be signed with a MAC key.

    Here is one of the ways you can do it in CXF, where a Json Web Token (JWT, see one of the next sections) is signed by a MAC ke y:
     

    CXF JWS HMac
    +

     

    A collection of JWK keys is called a JWK Key Set which is represented as JSON array of JWKs.

    CXF offers a utility support for reading and writing JWK keys and key sets and for working with the encrypted inlined and standalone JWK stores in this package.

    For example, a key set containing public JWK keys can be seen here and referred to from the configu ration properties. The private (test) key set can be represented in a clear form, though most likely you'd want a private key set encrypted and referred to like this. 

    One can inline the encrypted key or the key set directly in the configuration properties. For example, here is how an encrypted single JWK key is inlined. Similarly, here is how an encrypted collection of keys is inlined.

    CXF assumes that the JWK keys have been encrypted if a password provider is available in scope, it is typically registered with JAX-RS endpoints. The encryption is done with a password based PBES2 algorithm. 

    Support for the pluggable strategies for loading JWKs is on the map.

    JWS Signature

    JWS (JSON Web Signature) document describes how a document content can be signed. For example, Appendix A1 shows how the content can be signed with a MAC key.

    Here is one of the ways you can do it in CXF, where a Json Web Token (JWT, see one of the next sections) is signed by a MAC key:
     

    CXF JWS HMac
    // sign
 JoseHeaders headers = new JoseHeaders();
 headers.setAlgorithm(SignatureAlgorithm.HS256.getJwaName());
@@ -187,7 +187,7 @@ JwtToken token = jws.getJwtToken();
 JoseHeaders headers = token.getHeaders();
 assertEquals(SignatureAlgorithm.HS256.getJwaName(), headers.getAlgorithm());
 validateClaims(token.getClaims());
    -

     

    CXF ships JWS related classes in this package and offers a support for all of JWA signature algorithms.

    JwsSignatureProvider supports signing the content, JwsSignatureVerifier - validating the signatures. Providers and verif iers supporting RSA, HMac and Elliptic Curve signature algorithms are shipped.

    JwsCompactConsumer and JwsCompactProducer offer a utility support for creating and validating JWS compact serialization and accept keys in a variety of formats

    (as JWKs, JCA representations, created out of band and wrapped in either JwsSignatureProvider or JwsSignatureVerifier).

    JwsJwtCompactConsumer and JwsJwtCompactProducer are JwsCompactConsumer and JwsCompactProducer specializations that offer a utility support for signing Json Web Tokens in a compact format.

    JwsJsonConsumer and JwsJsonProducer support JWS JSON (full) serialization.

    JwsOutputStream and JwsJsonOutputStream are specialized output streams that can be used in conjunction with JWS JAX-RS filters (see one of the next sections)

    to support the best effort at streaming the content while signing it.  These classes will use JwsSignature  optionally returned from JwsSignatureProvider

    instead of working with the consumer utility classes which deal with the signature process completely in memory.

     

    Many more examples will be added here.

    JWE Encryption

    JSON Web Signature (JWE) document describes how a document content, and, when applicable, a content encryption key, can be encrypted. For example, Appendix A1 shows how the content can be encrypted

    with a secret key using Aes Gcm with the actual content encryption key encrypt ed/wrapped using RSA-OAEP.

    Here is the example for doing Aes Cbc HMac and Aes Key Wrap in CXF:

    CXF Jwe AesWrapAesCbcHMac
    +

     

    CXF ships JWS related classes in this package and offers a support for all of JWA signature algorithms.

    JwsSignatureProvider supports signing the content, JwsSignatureVerifier - validating the signatures. Providers and verifiers supporting RSA, HMac and Elliptic Cu rve signature algorithms are shipped.

    JwsCompactConsumer and JwsCompactProducer offer a utility support for creating and validating JWS compact serialization and accept keys in a variety of formats

    (as JWKs, JCA representations, created out of band and wrapped in either JwsSignatureProvider or JwsSignatureVerifier).

    JwsJwtCompactConsumer and JwsJwtCompactProducer are JwsCompactConsumer and JwsCompactProducer specializations that offer a utility support for signing Json Web Tokens in a compact format.

    JwsJsonConsumer and JwsJsonProducer support JWS JSON (full) serialization.

    JwsOutputStream and JwsJsonOutputStream are specialized output streams that can be used in conjunction with JWS JAX-RS filters (see one of the next sections)

    to support the best effort at streaming the content while signing it.  These classes will use JwsSignature  optionally returned from JwsSignatureProvider

    instead of working with the consumer utility classes which deal with the signature process completely in memory.

     

    Many more examples will be added here.

    JWE Encryption

    JWE (JSON Web Encryption) document describes how a document content, and, when applicable, a content encryption key, can be encrypted. For example, Appendix A1 shows how the content can be encrypted

    with a secret key using Aes Gcm with the actual content encryption key encrypted/wrapped using RSA-OAEP.

    Here is the example for doing Aes Cbc HMac and Aes Key Wrap in CXF:

    CXF Jwe AesWrapAesCbcHMac
    final String specPlainText = "Live long and prosper.";
         
 byte[] cekEncryptionKey = Base64UrlUtility.decode(KEY_ENCRYPTION_KEY_A3);
@@ -204,7 +204,7 @@ AesWrapKeyDecryptionAlgorithm keyDecrypt
 JweDecryptionProvider decryption = new AesCbcHmacJweDecryption(keyDecryption);
 String decryptedText = decryption.decrypt(jweContent).getContentText();
 assertEquals(specPlainText, decryptedText);
    -

     

    CXF ships JWE related classes in this package and offers a support for all of JWA encryption algorithms.

    JweEncryptionProvider supports encrypting the content, JweDecryptionProvider - decrypting the content. Encryptors and Decryptors for all of JWE algorithms are shipped.

    JweCompactConsumer and JweCompactProducer offer a utility support for creating and validating JWE compact serialization and accept keys in a variety of formats

    (as JWKs, JCA representations, created out of band and wrapped in either JweEncryptionProvider or JweDecryptionProvider).

    JweJwtCompactConsumer and JweJwtCompactProducer are JweCompactConsumer and JweCompactProducer specializations that offer a utility support for encrypting Json Web Tokens in a compact format.

    JweJsonConsumer and JweJsonProducer support JWE JSON (full) serialization.

    JweOutputStream is a specialized output stream that can be used in conjunction with JWE JAX-RS filters (see one of the next sections)

    to support the best effort at streaming the content while encrypting it.  These classes will use JweEncryptionOutput  optionally returned from JweEncryptionProvider

    instead of working with the consumer utility classes which deal with the encryption process completely in memory.

     

    Many more examples will be added here.

    JSON Web Tokens

     

    JSON Web Token (JWT) is a collection of claims in JSON format. It offers a standard JSON container for representing various properties or claims.

    JWT can be signed and or encrypted, i.e, serve as a JOSE signature or encryption input like any other data structure.

     

    JWT has been primarily used in OAuth2 applications to represent self-contained access tokens but can also be used in other contexts.

    CXF offers an ini tial JWT support in this package.

    Linking JWT authentications to JWS or JWE content

    Add more...

    JOSE JAX-RS Filters

    JWE

    JWS

    Configuration

    Configuration that applies to both encryption and signature

    rs.security.keystoreThe Java KeyStore Object to use. This configuration tag is used if you want to pass the KeyS tore Object through dynamically.

    rs.security.keystore.type

    The keystore type. Suitable values are "jks" or "jwk".

    rs.security.keystore.passwordThe password required to access the keystore.
    rs.security.keystore.alias 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:
         - jwe.out
         - jwe.in
         - jws.out
         - jws.in
    rs.s ecurity.keystore.aliasesThe 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:
         - jws.out
         - jws.in
    rs.security.keystore.fileThe path to the keystore file.
    rs.security.key.passwordThe password required to access the private key (in the keystore).
    rs.security.key.password.providerA reference to a PrivateKeyPasswordProvider instance used to retrieve passwords to access keys.
    rs.security.accept.public.key

    Whether to allow using a JWK received in the header for signature validation. The default is "false".

    Configuration that applies to signature only

    rs.security.signature.key.password.provider

    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".

    rs.security.signature.algorithmThe signature algorithm to use. The defau lt algorithm if not specified is 'RS256'.
    rs.security.signature.out.properties

    The signature properties file for compact signature creation. If not specified then it falls back to "rs.security.signature.properties".

    rs.security.signature.in.properties

    The signature properties file for compact signature verification. If not specified then it falls back to "rs.security.signature.properties".

    rs.security.signature.propertiesThe signature properties file for compact signature creation/verification.
    rs.security.signature.include.public.keyInclude the JWK public key for signature in the "jwk" header.
    rs.security.signature.include.certInclude the X.509 certificate for signature in the "x5c" header.
    rs.security.signature.include.key.idInclude the JWK key id for signature in the "kid" header.
    rs.security.signature.include.cert.sha1Include the X.509 certificate SHA-1 digest for signature in the "x5t" header.

    Configuration that applies to encryption only

    < p>rs.security.decryption.key.password.provider

    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".

    rs.security.encryption.content.algorithmThe encryption content algorithm to use. The default algorithm if not specified is 'A128GCM'.
    rs.security.encryption.key.algorithm

    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.

    rs.security.encryption.zip.algorithmThe encryption zip algorithm to use.
    rs.security.encryption.out.properties

    The signature properties file for encryption creation. If not specified then it falls back to "rs.security.encryption.properties".

    rs.security.encryption.in.properties

    The signature properties file for decryption. If not specified then it falls back to "rs.security.encryption.properties".

    rs.security.encryption.propertiesThe signature properties file for encryption/decryption.
    rs.security.encryption.include.public.keyInclude the JWK public key for encryption in the "jwk" header.
    rs.security.encryption.include.certInclude the X.509 certificate for encryption in the "x5c" header.
    rs.security.encryption.include.key.idInclude the JWK key id for encryption in the "kid" header.
    rs.security.encryption.include.cert.sha1Include the X.509 certificate SHA-1 digest for encryption in the "x5t" header.

    Configuration that applies to JWT tokens only

    rs.security.enable.unsigned-jwt.principal

    Whether to allow unsigned JWT tokens as SecurityContext Principals. The default is false.

    Encrypting JWK stores

    JAX-RS filters can read the keys from encrypted JWK stores. The stores are encrypted inline or in separate storages (files). By default the filters expect that the stores has been encrypted using

    a password based PBES2 algorithm. The filters will check a registered password provi der.

    OAuth2 and Jose

    CXF OAuth2 module depends on its JOSE module. This will be used to support OAuth2 POP tokens. Authorization code JOSE requests can already be processed. Utility support for validating JWT-based access tokens is provided.

    Add more...

    OIDC and Jose

    OIDC heavily depends on JOSE. CXF OIDC module utilizes a JOSE module to support OIDC RP and IDP code. Add more...

    Future Work

    OAuth2, WebCrypto, OIDC, etc

    Third-Party Alternatives

    Jose4J is a top project from Brian Campbell.  CXF users are encouraged to experiment with Jose4J (or indeed with other 3rd party implementations) if they prefer.

    TODO: describe how Jose4J can be integrated with CXF filters if preferred.

     

    +

     

    CXF ships JWE related classes in this package and offers a support for all of JWA encryption algorithms.

    JweEncryptionProvider supports encrypting the content, JweDecryptionProvider - decrypting the content. Encryptors and Decryptors for all of JWE algorithms are shipped.

    JweCompactConsumer and JweCompactProducer offer a utility support for creating and validating JWE compact serialization and accept keys in a variety of formats

    (as JWKs, JCA representations, created out of band and wrapped in either JweEncryptionProvider or JweDecryptionProvider).

    JweJwtCompactConsumer and JweJwtCompactProducer are JweCompactConsumer and JweCompactProducer specializations that offer a utility support for encrypting Json Web Tokens in a compact format.

    JweJsonConsumer and JweJsonProducer support JWE JSON (full) serialization.

    JweOutputStream is a specialized output stream that can be used in conjunction with JWE JAX-RS filters (see one of the next sections)

    to support the best effort at streaming the content while encrypting it.  These classes will use JweEncryptionOutput  optionally returned from JweEncryptionProvider

    instead of working with the consumer utility classes which deal with the encryption process completely in memory.

     

    Many more examples will be added here.

    JSON Web Token

    JWT (JSON Web Token) is a collection of claims in JSON format. It offers a standard JSON container for representing various properties or claims.

    JWT can be signed and or encrypted, i.e, serve as a JOSE signature or encryption input like any other data structure.

    JWT has been primarily used in OAuth2 applications to represent self-contained access tokens but can also be used in other contexts.

    CXF offers an initial JWT support in this package.

    JOSE JAX-RS Filters

    JWE

    JWS

    Linking JWT authentications to JWS or JWE content

     

    Configuration

    Configuration that applies to both encryption and signature

    rs.security.keystoreThe Java KeyStore Object to use. This configuration tag is used if you want to pass the KeyStore Object through dynamically.

    rs.security.keyst ore.type

    The keystore type. Suitable values are "jks" or "jwk".

    rs.security.keystore.passwordThe password required to access the keystore.
    rs.security.keystore.alias 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:
         - jwe.out
         - jwe.in
         - jws.out
         - jws.in
    rs.security.keystore.aliasesThe 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:
         - jws.out
         - jws.in
    rs.security.keystore.fileThe path to the keystore file.
    rs.security.key.passwordThe password required to access the private key (in the keystore).
    rs.security.key.password.providerA reference to a PrivateKeyPasswordProvider instance used to retrieve passwords to access keys.
    rs.security.accept.public.key

    Whether to allow using a JWK received in the header for signature validation. The default is "false".

    Configuration that applies to signature only

    rs.security.signature.key.password.provider

    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".

    rs.security.signature.algorithmThe signature algorithm to use. The default algorithm if not specified is 'RS256'.
    rs.security .signature.out.properties

    The signature properties file for compact signature creation. If not specified then it falls back to "rs.security.signature.properties".

    rs.security.signature.in.properties

    The signature properties file for compact signature verification. If not specified then it falls back to "rs.security.signature.properties".

    rs.security.signature.propertiesThe signature properties file for compact signature creation/verification.
    rs.security.signature.include.public.keyInclude the JWK public key for signature in the "jwk" header.
    rs.security.signature.include.certInclude the X.509 certificate for signature in the "x5c" header.
    rs.security.signature.include.key.idInclude the JWK key id for signature in the "kid" header.
    rs.security.signature.include.cert.sha1Include the X.509 certificate SHA-1 digest for signature in the "x5t" header.

    Configuration that applies to encryption only

    rs.security.decryption.key.password.provider

    A refere nce 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".

    rs.security.encryption.content.algorithmThe encryption content algorithm to use. The default algorithm if not specified is 'A128GCM'.
    rs.security.encryption.key.algorithm

    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.

    rs.security.encryption.zip.algorithmThe encryption zip algorithm to use.
    rs.security.encryption.out.properties

    The signature properties file for encryption creation. If not specified then it falls back to "rs.security.encryption.properties".

    rs.security.encryption.in.properties

    The signature properties file for decryption. If not specified then it falls back to "rs.security.encryption.properties".

    rs.security.encryption.propertiesThe signature properties file for encryption/decryption.
    rs.security.encryption.include.public.keyInclude the JWK public key for encryption in the "jwk" header.
    rs.security.encryption.include.certInclude the X.509 certificate for encryption in the "x5c" header.
    rs.security.encryption.include.key.idInclude the JWK key id for encryption in the "kid" header.
    rs.security.encryption.include.cert.sha1Include the X.509 certificate SHA-1 digest for encryption in the "x5t" header.

    Configuration that applies to JWT tokens only

    rs.security.enable.unsigned-jwt.principal

    Whether to allow unsigned JWT tokens as SecurityContext Principals. The default is false.

     

    OAuth2 and Jose

    CXF OAuth2 module depends on its JOSE module. This will be used to support OAuth2 POP tokens. Authorization code JOSE requests can already be processed. Utility support for validating JWT-based access tokens is provided.

    Add more...

    OIDC and Jose

    OIDC heavily depends on JOSE. CXF OIDC module utilizes a JOSE module to support OIDC RP and IDP code. Add more...

    Future Work

    OAuth2, WebCrypto, OIDC, etc

    Third-Party Alternatives

    Jose4J is a top project from Brian Campbell.  CXF users are encouraged to experiment with Jose4J (or indeed with other 3 rd party implementations) if they prefer.

    TODO: describe how Jose4J can be integrated with CXF filters if preferred.