[appendix]
== Revision History

=== Early Draft 1 (06/06/2005)

=== Significant Changes in Public Draft (08/15/2006)

==== Changes to API

. The classes and interfaces of the API were divided into four packages, `message`, `config`, `callback`, and `module`.
. The `MessageLayer` Interface was removed. Message layers are represented as a `String`.
. The use of the `URI` type to identify applications (and other things) was replaced by `String`.
. The `AuthParam` interface was replaced by the `MessageInfo` interface, and concrete message-specific implementations of the `AuthParam` interface were removed from the SPI.
. The `disposeSubject` methods were renamed `cleanSubject`.
. The `sharedMap` arguments were removed. `MessageInfo` is now used to convey such context.
. The parameter names corresponding to subjects were modified to correspond to the service role of the corresponding party (i.e., client or server) as opposed to the message sending role.
. The `ModuleProperties` interface was removed, and the responsibility for implementing transactional semantics was
transferred to the authentication context (if it supports multiple sufficient alternatives).
. The `PendingException` and `FailureException` classes were removed and a new return value type, `AuthStatus`, was
defined to convey the related semantics. A general return value model was provided by the `AuthStatus` class.
. The `AuthConfigProvider` interface was created to facilitate the integration of alternative module conversation systems,
and facilities were added to the `AuthConfigFactory` to support the registration of `AuthConfigProviders`. The `RegistrationListener` interface
we defined to support live replacement of configuration systems.
. The authentication context configuration layer was formalized and methods to acquire authentication contexts (i.e, `getAuthContext`) were moved to the authentication context configuration layer. `Subject` arguments were added to the `getAuthContext` methods to support both the acquisition of credentials by the config system, and to allow the `Subject` and its content to factor in the context acquisition.
. new callbacks were defined (i.e. `CallerPrincipalCallback` and `GroupPrincipalCallback`).

==== Changes to Processing Model

. The `AuthStatus` return model was described and the message processing model of the `Overview` and 
`Message Authentication` chapters was evolved to describe the processing by runtimes of the
returned `AuthStatus` values, especially in the case of a multi-message authentication dialog.

==== Changes to Profiles

. The Jakarta Servlet, SOAP, and Jakarta Messages profiles were added.

=== Changes in Proposed Final Draft 1

==== Changes to Preface

. Changed Status and Audience to reflect transition to PFD.
. Added paragraphs to describe relationship to JAAS

==== Changes to "Overview" Chapter

. Changed <<a166>> and <<a172>> to reflect change in `AuthConfig` interface from `getOperation` to `getAuthContextID`.
. Added definition of “message processing runtime” to <<a194>>

==== Changes to "Message Authentication" Chapter

. Changed sections <<a265>>, <<a285>>, <<a290>>, <<a297>> to reflect change in `AuthConfig` interface from `getOperation` to `getAuthContextID`.
. To <<a274>>, added a requirement that runtimes support the granting to applications and administration utilities of the permissions required to employ the configuration interfaces of the SPI.
. In subsection “at point (1) in the message processing model:” of <<a317>>, clarified `clientSubject` requirements, and indicated that a non-null `clientSubject` must not be read-only.
. In subsection “at point (4) in the message processing model:” of <<a317>>, clarified `serviceSubject` requirements, and indicated that a non-null serviceSubject must not be read-only.
. Added “Fig 2.1: State Diagram of Client Message Processing Runtime”
. In subsection “at point (2) in the message processing model:” of <<a317>>, clarified `serviceSubject` requirements, and indicated that a non-null serviceSubject must not be read-only.
. In subsection “at point (3) in the message processing model:” of <<a317>>, clarified that the call to `secureResponse` should be made independent of the outcome of the application request processing.
. Added “Fig 2.2: State Diagram of Server Message Processing Runtime”.

==== Changes to “Servlet Container Profile” Chapter 

. Added last sentence to introductory paragraph to clarify what is required to be a compatible implementation of the profile.
. In <<a371>>, extended identifier format to include the logical hostname along with he context path.
. In <<a381>>, added requirement that the handler argument (passed by the runtime) must not be null.
. Changed section <<a396>> to reflect change in `AuthConfig` interface from `getOperation` to `getAuthContextID`.
. Changed <<a400>>, to remove requirements for a specific identifier format.
. Changed <<a404>>,to require that the runtime set the `PolicyContext` in the module initialization properties passed to `getAuthContext` call.
. In <<a412>>, removed requirements relating to `responsePolicy`. Also moved responsibility for determining when (client) authentication is required from the `AuthConfig` subsystem to the message processing runtime.
. In <<a418>>, clarified the points within the servlet processing model that corresponding to points 2 and 3 of the message module. Added explicit statement to ensure that `validateRequest` is called on all requests including requests to a login form. Moved the comment regarding “delegation of session management” to a footnote. Changed the processing when there is an authorization failure to require
that secureResponse be called. Changed the prohibition on calling `secureResponse` when the application throws an exception to a recommendation. Added last sentence to require the use of the principal established using the `CallerPrincipalCallback` where identity propagation is configured.
. Changed <<a425>>, to conditionally require the inclusion of a property within the `MessageInfo` map when client authentication is
required. Also placed new requirement on the authentication context configuration system that is use this value to establish the requestPolicy.
. Added initial sentence to <<a440>>, to reiterate that `validateRequest` be called on every request that satisfies the applicable connection requirements.
. In <<a442>>, moved responsibility for coordinating disparate uses of the `CallerPrincipalCallback` to the context. Relaxed prohibition on returning `SEND_CONTINUE` from modules initialized with an optional `requestPolicy` by allowing modules to continue a multi-message authentication dialog as long as it was initiated by the client. Added requirement that modules initialized with an optional `requestPolicy`, use the `CallerPrincipalCallback` to established an unauthenticated caller identity (if they return `AuthStatus.SUCCESS` without having satisfied the `TargetPolicy`).
. In <<a449>>, removed requirement that the module set the HTTP 200 (OK) status code.
. In <<a455>>, removed requirements dependent on responsePolicy.
. Replaced section “Dealing with Servlet Commit Semantics” with a new <<a459>>.

==== Changes to “SOAP Profile” Chapter 

. Added last sentence to introductory paragraph to clarify what is required to be a compatible implementation of the profile.
. Changed <<a507>>, to refer to subsections within the sub-profiles where the corresponding identifiers are defined.
. In <<a514>>, added requirement that the handler argument (passed by the runtime) must not be null.
. In <<a526>>, added clarification of what it means when `getAuthContext` returns a null value, and how the value returned by `getAuthContext` impacts support for a session oriented authentication mechanism.
. Changed <<a531>>, to remove requirements for a specific identifier format.
. Added new <<a537>>, to describe the identifier format as the concatenation of a client scope identifier and a client reference to the service. For client scope identifiers, recommended the use of application identifiers where they are available and suggested the use of the archive URI where application identifiers are not available. Required that the service-ref name be used (if available) for the client reference to the service. Otherwise the service URL is to be used. Included examples, and added a last paragraph indicating that
registration would require an ability to predict the client scope identifier and client service reference associated by the runtime with a
client invocation.
. Removed requirements from <<a556>>, that were already stated in <<a526>>.
. In <<a564>>, to account for one-way application message exchange patterns, limited the circumstances under which a runtime may proceed to point (4) in the message processing model.
. In <<a568>>, changed the description of the value of the `javax.xml.ws.wsdl.service` property such that it must be a `QName` containing the service name. Removed statement of relationship of value to client authentication context identifier.
. In <<a580>>, corrected cut an paste errors (i.e., s/response/request/). Relaxed prohibition on returning `SEND_CONTINUE` from `secureRequest` on modules initialized with an optional requestPolicy. Added requirement that a module must return `AuthStatus.SEND_SUCCESS` (from `secureRequest`) if it was initialized with a null requestPolicy.
. In <<a590>>, on modules initialized with and optional `responsePolicy`, relaxed prohibition on returning `SEND_CONTINUE` from `validateResponse` and clarified the handling of `AuthException` and the various `AuthStatus` return values.
. Added new <<a603>>, to describe the identifier format as the concatenation of the logical hostname of the virtual server, and the service endpoint URI. Also included an example.
. Removed requirements from <<a616>> that were already stated in <<a526>>.
. Changed <<a618>> to require that `PolicyContext` be set in the module initialization properties (passed to `getAuthContext` call) if the server runtime is a Jakarta Authorization compatible container.
. In <<a626>> removed paragraphs defining when message protection is required by an Jakarta Enterprise Beans web service container. Added
requirement for a specific `TargetPolicy` within `requestPolicy` when the `CallerPrincipalCallback` is to be used by the authentication module(s) of the context. Added a requirement that the `requestPolicy` must be mandatory and must include a specific `TargetPolicy` when all the operations of an endpoint require client authentication. Added recommended return values for `isMandatory`, when not all of the operations of an endpoint require client authentication.
. In <<a632>>, to account for one-way application message exchange patterns, limited the circumstances under which a runtime may proceed to point (3) in the message processing model. Moved the comment regarding “delegation of session management” to a footnote. Changed the processing to require that `secureResponse` be called when there is an authorization failure. Changed the prohibition on calling `secureResponse` when the application throws an exception to a requirement that `secureResponse` be called. Added last sentence to require the use of the principal established using the `CallerPrincipalCallback` where identity propagation is configured.
. In <<a642>> removed the requirement that the service name property be set in the `MessageInfo` Map.
. In <<a648>>, moved responsibility for coordinating disparate uses of the `CallerPrincipalCallback` to the context. Relaxed prohibition on returning `SEND_CONTINUE` from modules initialized with an optional `requestPolicy` by allowing modules to continue a multi-message authentication dialog as long as it was initiated by the client. Added requirement that modules initialized with an optional requestPolicy, containing a prescribed `TargetPolicy`, use the `CallerPrincipalCallback` to established an unauthenticated caller identity (if they return `AuthStatus.SUCCESS` without having satisfied the `TargetPolicy`).

in <<a662>>, corrected the required return value when `responsePolicy == null` to be `AuthStatus.SEND_SUCCESS`.

==== Changes to JMS Profile Chapter

. Renamed chapter to "Future Profiles”.
. Changed chapter to be strictly informative; serving to capture suggestions for additional profiles.
. Added <<a677>>.

==== Changes to Appendix B, Issues

. Added new issue, <<a746>>, with resolution which was factored into the Servlet Profile (see <<a459>>).

==== Changes to API

. In javax.security.auth.message.MessagePolicy, changed name of method “isManadatory” to “isMandatory”.
. In javax.security.auth.message.config.AuthConfig, changed the name of method “getOperation” to “getAuthContextID” and changed the method
definition to indicate that it returns the authentication context identifier corresponding to the request and response objects in the
messageInfo argument.
. In javax.security.auth.message.config.AuthConfigFactory, changed description of the typical sequence of calls to reflect change of
“getOperation” to “getAuthContextID”. Also changed description to differentiate registration and self-registration. Added comment to
definition of the setFactory method to make it clear that listeners are NOT notified of the change to the registered factory. Added a second
form of registerConfigProvider that takes an AuthConfigProvider object (in lieu of an implementation class and properties Map) and that
performs an in-memory registration as apposed to a persisted registration. Added support for null registrations. Added the isPersistent method to the AuthConfigFactory.RegistrationContext interface.
. In javax.security.auth.message.config.AuthConfigProvider, changed description of the typical sequence of calls to reflect change of “getOperation” to “getAuthContextID”. Changed requirement for a “public one argument constructor” to a “public two argument constructor”, where the 2nd argument may be used to pass an AuthConfigFactory to the AuthConfigProvider to allow the provider to self-register with the
factory.
. In javax.security.auth.message.config.ClientAuthConfig, changed method and parameter descriptions to reflect change of “getOperation” to
“getAuthContextID”.
. In javax.security.auth.message.config.ServerAuthConfig, changed method and parameter descriptions to reflect change of “getOperation” to
“getAuthContextID”.
. In javax.security.auth.message.callback.PasswordValidationCallback, added a Subject parameter to the constructor, and a getSubject method to make the Subject available to the CallbackHandler. Also added a sentence describing the expected use of the PasswordValidationCallback.
. In javax.security.auth.message.callback.PrivateKeyCallback, added PrivateKeyCallback.DigestRequest so that private keys may be requested
by certificate digest (or thumbprint). Added a sentence describing the expected use of the PrivateKeyCallback.
. In javax.security.auth.message.callback.SecretKeyCallback, improved description of the expected use of the SecretKeyCallback.

=== Changes in Proposed Final Draft 2

==== Changes to License

. Revised date to May 5, 2007

==== Changes to Servlet Container Profile

. In <<a418>>, added reference to new section, <<a464>> to describe requirements for setting the authentication results.
. Added <<a464>> to capture requirements for setting the user principal, remote user, and authentication type on the `HttpServletRequest`.

==== Changes to SOAP Profile

. Corrected reference (chapter number) to “Message Authentication” chapter appearing in the chapter introduction.
. Corrected ambiguity in <<a510>>, to make it clear that the profile does not require that `MessageInfo` contain only non-null request and response objects.

==== Changes to LoginModule Bridge Profile

. In <<a685>>, revised the method by which a `ServerAuthModule` chooses the entry name passed to the `LoginContext` constructor. This change allows a single module implementation to be configured to use different entry names, and thus different login modules.
. In <<a692>>, added requirement that `GroupPrincipalCallback` be supported when `LoginContext` is constructed with `Subject`.
. In <<a694>>, added requirement that `ServerAuthModule` employ `CallerPrincipalCallback` using same value as that available to `LoginModule` via `NameCallback`.

=== Changes in Final Release

==== Changes to title page

. Corrected JCP version to 2.6

==== Changes to Preface

. Changed Status and Audience to reflect transition to Final Release


=== Changes in Maintenance Release A

==== Changes Effecting Entire Document

Changed document Identifier to Maintenance Release A. Version identifier remains unchanged at 1.0.

==== Changes to “Message Authentication” Chapter


Clarified definition of baseline compatibility requirements to more explicitly convey that the API is intended to have more general applicability than the specific contexts of its use defined within the specification.

==== Changes to API

In `javax.security.auth.message.callback.CallerPrincipalCallback`, modified callback definition to allow for principal mapping to occur during the
handling of the callback by the `CallbackHandler`.

=== Changes in Maintenance Release B

==== Changes Effecting Entire Document

. Changed document Identifier to Maintenance Release B, and Version identifier changed to 1.1.
. Updated JCP version to 2.7
. Updated the license
. Replaced Sun logo with Oracle logo
. Removed paragraph tags from PDF bookmarks

==== Changes to Preface

. Changed Status to Maintenance Release B version 1.1
. Added Will Hopkins, Tim Quinn, Arjan Tijms, and Yi Wang to the list of contributors

==== Changes to Servlet Container Profile

. In <<a371>>, described use of `ServletContext.getVirtualServerName` in application context identifier.
. In <<a418>> and <<a440>>, clarified that `validateRequest` must be called on every request for which the Servlet security model applies. Also included footnote whose text describes that the security model does not apply to forwards and includes.
. In <<a442>>, added clarification to description of processing for `SEND_CONTINUE`, especially to allow for
forwards to a login page within an authentication module.
. In <<a442>>, clarified description of processing for `SEND_FAILURE` to indicate that this return status is returned when the validation failed and the client should not continue or retry the request.
. Added footnote on header of <<a449>> to clarify that “after the service invocation” effectively means after the call to secureResponse, so as to remain distinct from the case where a call to authenticate from within the application results in a call to validateRequest during the service invocation.
. Added <<a457>>, to make it clear that authentication modules must be able to use a `RequestDispatcher` to forward to a login page (for example).
. In <<a464>>, amended description to make this section suitable for describing both the case where `validateRequest` is called prior to a request, and the case where `validateRequest` is (presumably) being called during the processing of
the request
. In <<a464>>, added <<a473>> to define the name of the session registration callback property. Also added description of the processing of the property.
. Added <<a479>> to define the use of the Jakarta Authentication SPI under `HttpServletRequest.authenticate`, `login`, and `logout`.

==== Changes to Appendix B, Issues

. Added <<a749>> with links to java.net project and JIRA issue tracker.

==== Changes to API

. In abstract `AuthConfigFactory` class, made public the static permissions that are used to protect the static `getFactory` and `setFactory` methods, and improved documentation so users of the SPI can know which permissions are used. Also added an additional public `providerRegistrationSecurityPermission` and required that it be used by factory implementations to protect methods like `registerConfigProvider`. Removed incorrect assertion from javadoc of `getFactory`, both forms of `registerConfigProvider`, and `refresh`, that checked `AuthException` could be thrown (by these methods). Changed the javadoc of these four methods to indicate that the conditions for which they were expected to throw an `AuthException` should instead be handled within their existing declarations of throwing an (unchecked) `SecurityException`. Regenerated (mif) javadocs (embedded in spec) from html javadocs, which corrected definition for `layer` and `appContext`parameters of `getConfigProvider(java.lang.String layer, java.lang.String appContext, RegistrationListener listener)`.
. In `AuthConfig`, and `AuthConfigProvider` interfaces, removed incorrect assertion from javadoc of refresh method that checked `AuthException` could be thrown, and changed javadoc to indicate that the conditions for which `refresh` was expected to throw an `AuthException` should instead be handled within its existing declaration of throwing an (unchecked) `SecurityException`.

=== Changes in Jakarta Authentication 3.0

==== Changes to Servlet Container Profile

 . Added the `jakarta.servlet.http.isAuthenticationRequest` key, so modules can distinguish between being called at the very start of a request and in the middle of it following a call to `HttpServletRequest.authenticate`. This could be needed to determine if certain contexts are effectively active (such as the Faces context in Jakarta Faces).
 . Added requirements regarding the interaction of a `ServerAuthModule` with other specifications. This allows such `ServerAuthModule` to programmatically obtain references to data sources, EJB beans, CDI beans, etc.

