Update for EDR1 release

wmhopkins · wmhopkins · commit 218937242b46 · 2017-03-05T15:52:19.000-05:00
diff --git a/LICENSE-template.txt b/LICENSE-template.txt
@@ -10,9 +10,9 @@
 // Specification: JSR-375 Java EE Security API ("Specification")
 // Version: 1.0
 // Status: Early Draft Review
-// Release: November 2016
+// Release: March 2017
 // 
-// Copyright 2016 Oracle America, Inc.
+// Copyright 2017 Oracle America, Inc.
 // 500 Oracle Parkway, Redwood City, California 94065, U.S.A.
 // 
 // All rights reserved.
diff --git a/LICENSE.html b/LICENSE.html
@@ -19,9 +19,9 @@
 <br>
 Status: Early Draft Review
 <br>
-Release: November 2016
+Release: March 2017
 <p>
-Copyright 2016 Oracle America, Inc.
+Copyright 2017 Oracle America, Inc.
 <br>
 500 Oracle Parkway, Redwood City, California 94065, U.S.A.
 <p>
diff --git a/LICENSE.pdf b/LICENSE.pdf
diff --git a/LICENSE.txt b/LICENSE.txt
@@ -8,9 +8,9 @@ THIS PAGE AND THE DOWNLOADING PROCESS WILL NOT CONTINUE.
 Specification: JSR-375 Java EE Security API ("Specification")
 Version: 1.0
 Status: Early Draft Review
-Release: November 2016
+Release: March 2017
 
-Copyright 2016 Oracle America, Inc.
+Copyright 2017 Oracle America, Inc.
 500 Oracle Parkway, Redwood City, California 94065, U.S.A.
 
 All rights reserved.
diff --git a/src/main/doc/authenticationMechanism.asciidoc b/src/main/doc/authenticationMechanism.asciidoc
diff --git a/src/main/doc/concepts.asciidoc b/src/main/doc/concepts.asciidoc
@@ -10,9 +10,9 @@
 // Specification: JSR-375 Java EE Security API ("Specification")
 // Version: 1.0
 // Status: Early Draft Review
-// Release: November 2016
+// Release: March 2017
 // 
-// Copyright 2016 Oracle America, Inc.
+// Copyright 2017 Oracle America, Inc.
 // 500 Oracle Parkway, Redwood City, California 94065, U.S.A.
 // 
 // All rights reserved.
@@ -143,4 +143,9 @@
 
 == Concepts
 
-To do, add terminology here
+* authentication
+* authorization
+* credential
+* jaspic
+* java servlet specification
+* token
diff --git a/src/main/doc/identityStore.asciidoc b/src/main/doc/identityStore.asciidoc
diff --git a/src/main/doc/jsr375-spec.asciidoc b/src/main/doc/jsr375-spec.asciidoc
@@ -10,9 +10,9 @@
 // Specification: JSR-375 Java EE Security API ("Specification")
 // Version: 1.0
 // Status: Early Draft Review
-// Release: November 2016
+// Release: March 2017
 // 
-// Copyright 2016 Oracle America, Inc.
+// Copyright 2017 Oracle America, Inc.
 // 500 Oracle Parkway, Redwood City, California 94065, U.S.A.
 // 
 // All rights reserved.
@@ -142,14 +142,16 @@
 :sectanchors:
 :doctype: book
 :compat-mode:
-= Security API for the Java EE
+= Java EE Security API 1.0 (EDR 1)
+
+include::license.asciidoc[]
 
 include::preface.asciidoc[]
 
 include::concepts.asciidoc[]
 
-include::identityStore.asciidoc[]
-
 include::authenticationMechanism.asciidoc[]
 
+include::identityStore.asciidoc[]
+
 include::securityContext.asciidoc[]
diff --git a/src/main/doc/license.asciidoc b/src/main/doc/license.asciidoc
@@ -10,9 +10,9 @@
 // Specification: JSR-375 Java EE Security API ("Specification")
 // Version: 1.0
 // Status: Early Draft Review
-// Release: November 2016
+// Release: March 2017
 // 
-// Copyright 2016 Oracle America, Inc.
+// Copyright 2017 Oracle America, Inc.
 // 500 Oracle Parkway, Redwood City, California 94065, U.S.A.
 // 
 // All rights reserved.
@@ -139,7 +139,7 @@
 //
 ////
 
-....
+["colophon",sectnum="0"]
 
 ORACLE AMERICA, INC. IS WILLING TO LICENSE THIS SPECIFICATION TO YOU ONLY UPON THE
 CONDITION THAT YOU ACCEPT ALL OF THE TERMS CONTAINED IN THIS LICENSE AGREEMENT
@@ -149,16 +149,21 @@ IF YOU ARE NOT WILLING TO BE BOUND BY THEM, SELECT THE "DECLINE" BUTTON AT THE B
 THIS PAGE AND THE DOWNLOADING PROCESS WILL NOT CONTINUE.
 
 Specification: JSR-375 Java EE Security API ("Specification")
+
 Version: 1.0
+
 Status: Early Draft Review
-Release: November 2016
 
-Copyright 2016 Oracle America, Inc.
+Release: March 2017
+
+Copyright 2017 Oracle America, Inc.
+
 500 Oracle Parkway, Redwood City, California 94065, U.S.A.
 
 All rights reserved.
 
 NOTICE
+
 The Specification is protected by copyright and the information described therein may be protected by
 one or more U.S. patents, foreign patents, or pending applications. Except as provided under the
 following license, no part of the Specification may be reproduced in any form by any means without the
@@ -211,11 +216,13 @@ Specification.
 through the Java Community Process, or any recognized successors or replacements thereof
 
 TRADEMARKS
+
 No right, title, or interest in or to any trademarks, service marks, or trade names of Oracle or Oracle's
 licensors is granted hereunder. Oracle, the Oracle logo, and Java are trademarks or registered
 trademarks of Oracle America, Inc. in the U.S. and other countries.
 
 DISCLAIMER OF WARRANTIES
+
 THE SPECIFICATION IS PROVIDED "AS IS" AND IS EXPERIMENTAL AND MAY CONTAIN DEFECTS OR
 DEFICIENCIES WHICH CANNOT OR WILL NOT BE CORRECTED BY ORACLE. ORACLE MAKES NO
 REPRESENTATIONS OR WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO,
@@ -233,6 +240,7 @@ TIME. Any use of such changes in the Specification will be governed by the then-
 applicable version of the Specification.
 
 LIMITATION OF LIABILITY
+
 TO THE EXTENT NOT PROHIBITED BY LAW, IN NO EVENT WILL ORACLE OR ITS LICENSORS BE LIABLE FOR
 ANY DAMAGES, INCLUDING WITHOUT LIMITATION, LOST REVENUE, PROFITS OR DATA, OR FOR SPECIAL,
 INDIRECT, CONSEQUENTIAL, INCIDENTAL OR PUNITIVE DAMAGES, HOWEVER CAUSED AND REGARDLESS
@@ -246,13 +254,15 @@ later versions or releases of any Specification furnished to you are incompatibl
 provided to you under this license.
 
 RESTRICTED RIGHTS LEGEND
+
 If this Software is being acquired by or on behalf of the U.S. Government or by a U.S. Government prime
 contractor or subcontractor (at any tier), then the Government's rights in the Software and
 accompanying documentation shall be only as set forth in this license; this is in accordance with 48
 C.F.R. 227.7201 through 227.7202-4 (for Department of Defense (DoD) acquisitions) and with 48 C.F.R.
 2.101 and 12.212 (for non-DoD acquisitions).
 
 REPORT
+
 You may wish to report any ambiguities, inconsistencies or inaccuracies you may find in connection with
 your evaluation of the Specification ("Feedback"). To the extent that you provide Oracle with any
 Feedback, you hereby: (i) agree that such Feedback is provided on a non-proprietary and non-
@@ -262,6 +272,7 @@ use without limitation the Feedback for any purpose related to the Specification
 implementations, and test suites thereof.
 
 GENERAL TERMS
+
 Any action related to this Agreement will be governed by California law and controlling U.S. federal law.
 The U.N. Convention for the International Sale of Goods and the choice of law rules of any jurisdiction
 will not apply.
@@ -277,5 +288,3 @@ warranties and prevails over any conflicting or additional terms of any quote, o
 or other communication between the parties relating to its subject matter during the term of this
 Agreement. No modification to this Agreement will be binding, unless in writing and signed by an
 authorized representative of each party.
-
-....
diff --git a/src/main/doc/preface.asciidoc b/src/main/doc/preface.asciidoc
@@ -10,9 +10,9 @@
 // Specification: JSR-375 Java EE Security API ("Specification")
 // Version: 1.0
 // Status: Early Draft Review
-// Release: November 2016
+// Release: March 2017
 // 
-// Copyright 2016 Oracle America, Inc.
+// Copyright 2017 Oracle America, Inc.
 // 500 Oracle Parkway, Redwood City, California 94065, U.S.A.
 // 
 // All rights reserved.
@@ -144,12 +144,6 @@
 
 == Preface
 
-=== Evaluation license
-
-include::license.asciidoc[]
-
-=== Foreword
-
-Security API 1.0 is the initial release of (link:https://jcp.org/en/jsr/detail?id=375[JSR-375^]).
+This document is Early Draft Review 1 (EDR 1) of the Java EE Security API 1.0 Specification (link:https://jcp.org/en/jsr/detail?id=375[JSR-375^]).
 
 :numbered:
diff --git a/src/main/doc/securityContext.asciidoc b/src/main/doc/securityContext.asciidoc
@@ -10,9 +10,9 @@
 // Specification: JSR-375 Java EE Security API ("Specification")
 // Version: 1.0
 // Status: Early Draft Review
-// Release: November 2016
+// Release: March 2017
 // 
-// Copyright 2016 Oracle America, Inc.
+// Copyright 2017 Oracle America, Inc.
 // 500 Oracle Parkway, Redwood City, California 94065, U.S.A.
 // 
 // All rights reserved.
@@ -143,41 +143,66 @@
 
 == Security Context
 
-This chapter describes the contract that specifies how a security aware application can take advantage of programmatic security. 
-
+This chapter describes the _SecurityContext_ interface and contract.
 
 === Introduction
 
-The Java EE platform defines a declarative security model via which resources can be constrained. These constraints are then enforced by the container. In some cases the declarative model is not sufficient, for example when more complex combinations of constraints and tests are needed than the declarative model allows. Programmatic security allows an application to perform tests and grant or reject access to resources itself. 
+The Java EE platform defines a declarative security model via which resources can be constrained. These constraints are then enforced by the container. In some cases the declarative model is not sufficient, for example when more complex combinations of constraints and tests are needed than the declarative model allows. Programmatic security allows an application to perform tests and grant or deny access to resources itself. 
 
 This specification provides an access point for programmatic security; the security context, represented by the _SecurityContect_ interface.
 
-=== Relationship to other specifications
+=== Testing for Caller Data
 
-The _SecurityContect_ implementation is a CDI bean, as defined by the CDI (JSR 346) specification.
+The _SecurityContect_ interface defines two methods that allow the application to test aspects of the caller data:
 
-Various specifications in Java EE provide similar or even identical methods to those provided be the _SecurityContect_. It is the intention of this specification to supersede all of those and provide a cross-spec, platform alternative. The following gives an overview:
+[source,java]
+----
+Principal getCallerPrincipal();
 
-* Servlet spec - _HttpServletRequest#getUserPrincipal_, _HttpServletRequest#isUserInRole_
-* EJB spec - _EJBContect#getCallerPrincipal_, _EJBContext#isCallerInRole_
-* JAX-WS spec - _WebServiceContext#getUserPrincipal_, _WebServiceContext#isUserInRole_
-* JAX-RS spec - _SecurityContext#getUserPrincipal_, _SecurityContext#isUserInRole_
-* JSF spec - _ExternalContext#getUserPrincipal_, _ExternalContext#isUserInRole_
-* CDI - _@Inject Principal_
-* WebSockets - _Session#getUserPrincipal_
+boolean isCallerInRole(String role);
+----
 
-=== Testing for caller data
+The _getCallerPrincipal()_ method is provided to retrieve the _Principal_ that represents the caller's name. It MUST be possible for the application to downcast this _Principal_ to the exact _Principal_ type that was set by the _HttpAuthenticationMechanism_ (possibly via an _IdentityStore_) or a JASPIC _ServerAuthModule_.
 
-The _SecurityContect_ interface defines two methods that allow the application to test aspects of the caller data:
+The _isCallerInRole()_ method takes a String argument that represents the application role that is to be tested for. It is undefined by this specification how the role determinatino is made; however, the result of calling _isCallerInRole()_ MUST be the same as if the corresponding container-specific call had been made (e.g., _HttpServletRequest.isUserInRole()_), and MUST be consistent with the result implied by other specifications that prescribe role-mapping behavior.
+
+=== Triggering the Authentication Process
 
-The _getCallerPrincipal_ method is provided to retrieve the _Principal_ that represents the caller's name. It *must* be possible for the application to downcast this _Principal_ to the exact _Principal_ type that was set by the _HttpAuthenticationMechanism_ (possibly via an _IdentityStore_) or a JASPIC _ServerAuthModule_.
+The _SecurityContect_ interface defines two overloaded methods that allow the application to programmatically trigger the authentication process:
 
-The _isCallerInRole_ method takes a string argument that represents the application role that is to be tested for. The application role is defined as the group name as set by the _HttpAuthenticationMechanism_ (possibly via an _IdentityStore_) or a JASPIC _ServerAuthModule_ after group to role mapping has taken place.
+[source,java]
+----
+AuthStatus authenticate(HttpServletRequest request,
+                        HttpServletResponse response,
+                        AuthenticationParameters parameters);
 
-=== Triggering the authentication process
+AuthStatus authenticate(HttpServletResponse response,
+                        AuthenticationParameters parameters);
+----
 
-The _SecurityContect_ interface defines two overloaded methods that allow the application to programmatically trigger the authentication process. Programmatically triggering means that the container responds as-if the caller had attempted to access a constrained resource and responds with invoking a configured authentication mechanism (such as the _HttpAuthenticationMechanism_).
+Programmatically triggering means that the container responds as if the caller had attempted to access a constrained resource and responds with invoking a configured authentication mechanism (such as the _HttpAuthenticationMechanism_).
 
-The _authenticate_ method allows an application to signal to the container that it should start the authentication process with the caller. This method requires an _HttpServletResponse_ argument to be passed in, and can therefore only be used in a valid Servlet context.
+The _authenticate()_ method allows an application to signal to the container that it should start the authentication process with the caller. This method requires an _HttpServletResponse_ argument to be passed in, and can therefore only be used in a valid Servlet context.
 
+****
+*Review:*
 
+* Need further explaintion/rationale for the additional parameters and signatures relative to HttpServletRequest.authenticate().
+* Should state that implementation must behave consistent with JASPIC "Sub-profile for authenticate, login, and logout of HttpServletRequest".
+* Should state that, when JASPIC/_HttpAuthenticationMechanism_ not configured, behavior is as defined by Servlet Spec, and authenticate() is undefined/ignored if the user is already authenticated -- i.e., is defined only for unprotected resources that allow anonymous access.
+* Why no login()/logout() support?
+****
+
+=== Relationship to Other Specifications
+
+The _SecurityContect_ implementation is a CDI bean, as defined by the CDI (JSR 346) specification.
+
+Various specifications in Java EE provide similar or even identical methods to those provided be the _SecurityContect_. It is the intention of this specification to supersede all of those and provide a cross-spec, platform alternative. The following gives an overview:
+
+* Servlet spec - _HttpServletRequest#getUserPrincipal_, _HttpServletRequest#isUserInRole_
+* EJB spec - _EJBContect#getCallerPrincipal_, _EJBContext#isCallerInRole_
+* JAX-WS spec - _WebServiceContext#getUserPrincipal_, _WebServiceContext#isUserInRole_
+* JAX-RS spec - _SecurityContext#getUserPrincipal_, _SecurityContext#isUserInRole_
+* JSF spec - _ExternalContext#getUserPrincipal_, _ExternalContext#isUserInRole_
+* CDI - _@Inject Principal_
+* WebSockets - _Session#getUserPrincipal_
