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 021C92009F4 for ; Thu, 26 May 2016 11:47:45 +0200 (CEST) Received: by cust-asf.ponee.io (Postfix) id 00540160A2B; Thu, 26 May 2016 09:47:45 +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 CCAC6160939 for ; Thu, 26 May 2016 11:47:43 +0200 (CEST) Received: (qmail 77373 invoked by uid 500); 26 May 2016 09:47:43 -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 77361 invoked by uid 99); 26 May 2016 09:47:43 -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; Thu, 26 May 2016 09:47:43 +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 96809180501 for ; Thu, 26 May 2016 09:47:42 +0000 (UTC) X-Virus-Scanned: Debian amavisd-new at spamd3-us-west.apache.org X-Spam-Flag: NO X-Spam-Score: 1.799 X-Spam-Level: * X-Spam-Status: No, score=1.799 tagged_above=-999 required=6.31 tests=[KAM_ASCII_DIVIDERS=0.8, KAM_LAZY_DOMAIN_SECURITY=1, 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 WdNVik8SqZpZ for ; Thu, 26 May 2016 09:47:40 +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 D5FD05F46F for ; Thu, 26 May 2016 09:47:39 +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 BCEEFE009C for ; Thu, 26 May 2016 09:47:38 +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 CE8433A023D for ; Thu, 26 May 2016 09:47:37 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit 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 -0000 To: commits@cxf.apache.org From: buildbot@apache.org X-Mailer: svnmailer-1.0.9 Message-Id: <20160526094737.CE8433A023D@svn01-us-west.apache.org> archived-at: Thu, 26 May 2016 09:47:45 -0000 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

 

 

+/*]]>*/

-

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

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

CXF 3.1.x and 3.2.0 provide a complete implementation of JOSE and offer a comprehensive utility and filter support for prot ecting JAX-RS services and clients with the help of JOSE.

CXF OAuth2 and OIDC modules are also depending on it.

Maven Dependencies

 

Having the following dependency will let developers write JOSE JWS or JWE code:

+

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

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

CXF 3.0.x, 3.1.x and 3.2.0 provide a complete implementation of JOSE and offer a comprehensive utility and filter support f or protecting JAX-RS services and clients with the help of JOSE.

CXF OAuth2 and OIDC modules are also depending on it.

Maven Dependencies

 

Having the following dependency will let developers write JOSE JWS or JWE code:

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

You may also need to include Bouncy Castle:

+

You may also need to include BouncyCastle for some of JWE encryption algorithms to be supported:

<dependency>
      <groupId>org.bouncycastle</groupId>
      <artifactId>bcprov-ext-jdk15on</artifactId>
@@ -169,7 +169,7 @@ private static void registerBouncyCastle
 private static void unregisterBouncyCastle() throws Exception {
     Security.removeProvider(BouncyCastleProvider.PROVIDER_NAME);    
 }
-

 

Java and JCE Policy 

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.

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

JOSE Overview and Implementation

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 descr ibing 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 decrypted 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 effectivel y JWTs). JWT describes how a set of claims in JSON format can be 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 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).

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
where Java 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 they 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 algorit hms 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 for JWS, KeyAlgorithm.A256KW plus ContentAlgorithm.A256GCM for JWE, etc. Each enum has methods for checking a key size, JWA and Java JCA algorithm names.

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 s ecret and asymmetric keys instead, JWK is a preferred representation of signature or encryption keys in JOSE.

For example:

Secret HMAC Key
+

 

Java and JCE Policy 

Java7 or higher is recommended in most cases.

JWE:

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.

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

JWS:

Java 6 should also be fine but note only CXF 3.0.x can be run with Java 6.

JOSE Overview and Implementation

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 decrypted and introduces compact and JSON JWE formats for representing the encrypted data  

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

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
where Java 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 they 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, ot her 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 for JWS, KeyAlgorithm.A256KW plus ContentAlgorithm.A256GCM for JWE, etc. Each enum has methods for checking a key size, JWA and Java JCA algorithm names.

JWK Keys

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

For example:

Secret HMAC Key
{
    "kty":"oct",
    "k":"AyM1SysPpbyDfgZld3umj1qzKObwVMkoqQ-EstJQLr_T-1qS0gZH75aKtMN3Yj0iPS4hcgUuTwjAzZr1Z9CAow",