| # Licensed to the Apache Software Foundation (ASF) under one | |
| # or more contributor license agreements. See the NOTICE file | |
| # distributed with this work for additional information | |
| # regarding copyright ownership. The ASF licenses this file | |
| # to you under the Apache License, Version 2.0 (the | |
| # "License"); you may not use this file except in compliance | |
| # with the License. You may obtain a copy of the License at | |
| # | |
| # http://www.apache.org/licenses/LICENSE-2.0 | |
| # | |
| # Unless required by applicable law or agreed to in writing, | |
| # software distributed under the License is distributed on an | |
| # "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY | |
| # KIND, either express or implied. See the License for the | |
| # specific language governing permissions and limitations | |
| # under the License. | |
| This is not an official release notes document. It exists for Shiro developers | |
| to jot down their notes while working in the source code. These notes will be | |
| combined with Jira's auto-generated release notes during a release for the | |
| total set. | |
| ########################################################### | |
| # 2.0 alpha 0 | |
| ########################################################### | |
| The 2.0 alpha 0 release's design goal is to introduce a much cleaner, more intuitive, more configurable API that is | |
| even easier to understand and use than previous Shiro versions. | |
| The design changes however introduce enough change such that there will be a decent amount of deprecation of old | |
| concepts and implementations; the releases before 2.0.0 final will retain all of these 'legacy' concepts and | |
| implementations to provide a smoother upgrade path for those trying alpha and beta releases. | |
| 2.0.0 final however will completely remove all deprecated interfaces, classes and methods to ensure a clean | |
| codebase for the many years to come. | |
| Design Changes | |
| -------------------------------- | |
| - All of Shiro's SecurityManager implementations now require a CacheManager - it cannot be null. Caching is still | |
| disabled by default however; the SecurityManager implementations just default to an | |
| org.apache.shiro.cache.DisabledCacheManager instance. This reflects the Null Object design pattern, helping | |
| reducing cyclomatic complexity (and therefore the potential for bugs) in Shiro. | |
| - org.apache.shiro.subject.PrincipalCollection has been deprecated and will be removed in 2.0 final. This represents | |
| a big change, but for an extremely strong reason: | |
| Almost all Shiro end-users expect to be able to query a Subject's PrincipalCollection for identifying attributes, | |
| like a username, or first name, etc. This is extraordinarily difficult with the PrincipalCollection API, which | |
| only allows users to acquire identity attributes _by type_. If you had more than one attribute of the same | |
| type (e.g. a String username and a String surname), the PrincipalCollection is effectively useless, and you had to | |
| come up with all sorts of workarounds (like creating 'wrapper' objects) to obtain the data you needed. Additionally | |
| these workarounds were not usable by any tools or frameworks that used reflection to lookup information. | |
| This was a huge problem, almost crippling in some cases, and so PrincipalCollection has been deprecated and | |
| replaced by a very simple 'attributes' map, of type Map<String,Object>. This allows much cleaner code, like: | |
| subject.getAttributes().get("username"); | |
| or, even simpler for Groovy or JSTL: | |
| subject.attributes['username'] | |
| This change affords a huge number of simplifications/conveniences for the Shriro user community, dev team, and | |
| bean-compatible tools and frameworks. | |
| - org.apache.shiro.authc.AuthenticationInfo (used widely by Realm implementations) has been deprecated and will be | |
| replaced by a brand new org.apache.shiro.account.Account interface. This was done for three reasons: | |
| 1. Account supports a getId() method, which allows explicit support for a data-store-unique account identifier. | |
| AuthenticationInfo did not have this, and id acquisition was implicit - not good for such a core Shiro concept. | |
| 2. 'Account' is an inherently more intuitive name. The < 2.0 'AuthenticationInfo' interface name actually always | |
| represented an Account, and the name 'AuthenticationInfo' is abstract and fairly unintuitive. Now it is more | |
| obvious/explicit. | |
| 3. Shiro's old PrincipalCollection concept is being removed. Account instead represents principals with a | |
| new name, called 'attributes' as a simple Map<String,Object> collections, as described above. | |
| org.apache.shiro.authc.AuthenticationInfo is currently deprecated, but will be removed entirely when 2.0 final is | |
| released. | |
| - The previously (very) complicated SecurityManager implementation hierarchy has been deprecated entirely: | |
| CachingSecurityManager < RealmSecurityManager < AuthenticatingSecurityManager < AuthorizingSecurityManager | |
| < SessionsSecurityManager < DefaultSecurityManager < DefaultWebSecurityManager | |
| An interim replacement, org.apache.shiro.mgt.ApplicationSecurityManager is the only SecurityManager implementation. | |
| All customization for this implementation can be done by customizing or plugging in its internal components. This is | |
| now possible because the implementation much more heavily favors a "delegation over inheritance" best practice. | |
| This approach will allow much greater resilience to change over time and help keep Shiro's core SecurityManager | |
| codebase highly stable. | |
| Right before the 2.0 final release, ApplicationSecurityManager might be renamed to DefaultSecurityManager to adhere | |
| to all other existing default implementation naming conventions. This just cannot be done prior to a 2.0 final | |
| release because it would be a backwards-incompatible change. | |
| - For multi-realm authentication, the org.apache.shiro.authc.pam package and all of its internal | |
| org.apache.shiro.authc.pam.AuthenticationStrategy implementations have been deprecated in favor of the new | |
| org.apache.shiro.authc.strategy package. | |
| The new org.apache.shiro.authc.strategy.AuthenticationStrategy interface is much simpler - it is a single method that | |
| can perform all multi-realm interaction logic without compromise. | |
| The legacy org.apache.shiro.authc.pam.AuthenticationStrategy API and implementations suffered from an overly complex | |
| pre/before/after/post implementation requirement, and in some cases, entirely prevented some Strategy behavior from | |
| being implemented successfully. | |
| For example the org.apache.shiro.authc.pam.FirstSuccessfulStrategy did not | |
| short-circuit realm iteration (desired by most Shiro users) and the existing Strategy API provided no way to 'tell' | |
| the calling Authorizer how to stop iteration when things were successful. The new Strategy API has no such problems, | |
| and is more holistic, allowing implementors exact control over the login attempt. | |
| Finally, the *Strategy implementations have been renamed to include the word 'Realm' in the name to more explicitly | |
| self-document what is occurring. | |
| For example, the class name 'FirstRealmSuccessfulStrategy' (in 2.0) is more intuitive than | |
| 'FirstSuccessfulStrategy' in pre 2.0 (first *what* is successful?). The 2.0 implementations naming scheme makes it | |
| very clear what is occurring. | |
| - org.apache.shiro.authc.AuthenticationInfo (used widely by Realms) has been deprecated in favor of a | |
| Deprecations (will be removed immediately before 2.0 final) | |
| ----------------------------------------------------------- | |
| - org.apache.shiro.cache.Cache methods clear(), size() and keys() have been deprecated and will be removed before the | |
| 2.0 final release. These methods were never called by Shiro's components and caused an unnecessary implementation | |
| burden. | |
| - org.apache.shiro.authc.credential.CredentialsMatcher doCredentialsMatch(AuthenticationToken, AuthenticationInfo) | |
| has been deprecated in favor of the new method (in the same interface): | |
| credentialsMatch(AuthenticationToken, Account) to reflect the new Account concept (discussed in 'Design Changes' | |
| above). | |
| - org.apache.shiro.authc.credential.HashedCredentialsMatcher and all of its children implementations | |
| (Md5CredentialsMatcher, Sha256CredentialsMatcher, etc) have been deprecated and will be removed in 2.0 final. The | |
| org.apache.shiro.authc.credential.PasswordMatcher and org.apache.shiro.authc.credential.PasswordService | |
| introduced in 1.2 perform all of these operations and more. | |
| New Features / Implementations | |
| -------------------------------- | |
| - org.apache.shiro.cache.DisabledCacheManager returns no-op implementations for all caching operations. Mostly usable | |
| for the Null Object design pattern. | |
| ########################################################### | |
| # 1.2.0 | |
| ########################################################### | |
| Backwards Incompatible Changes | |
| -------------------------------- | |
| - The following org.apache.shiro.mgt.DefaultSecurityManager methods have been removed: | |
| bindPrincipalsToSession(principals, context) | |
| This logic has been moved into a SubjectDAO concept to allow end-users to control | |
| exactly how the Session may be used for subject state persistence. This allows a | |
| single point of control rather than needing to configure Shiro in multiple places. | |
| If you overrode this method in Shiro 1.0 or 1.1, please look at the new | |
| org.apache.shiro.mgt.DefaultSubjectDAO implementation, which performs compatible logic. | |
| Documentation for this is covered here: | |
| http://shiro.apache.org/session-management.html#SessionManagement-SessionsandSubjectState | |
| - The org.apache.shiro.web.session.mgt.ServletContainerSessionManager implementation | |
| (enabled by default for all web applications) no longer subclasses | |
| org.apache.shiro.session.mgt.AbstractSessionManager. AbstractSessionManager existed | |
| originally to consolidate a 'globalSessionTimeout' configuration property for | |
| subclasses. However, the ServletContainerSessionManager has been changed to always | |
| reflect the session configuration from web.xml (per its namesake). Because web.xml | |
| is the definitive source for session timeout configuration, the 'extends' clause | |
| was removed to avoid configuration confusion: if someone attempted to configure | |
| 'globalSessionTimeout' on a ServletContainerSessionManager instance, it would never | |
| be honored. It was better to remove the extends clause to ensure that any | |
| such configuration would fail fast when Shiro starts up to reflect the invalid config. | |
| Potential Breaking Changes | |
| -------------------------------- | |
| - The org.apache.shiro.web.filter.mgt.FilterChainManager class's | |
| addFilter(String name, Filter filter) semantics have changed. It now no longer | |
| attempts to initialize a filter by default before adding the filter to the chain. | |
| If you ever called this method, you can call the | |
| addFilter(name, filter, true) method to achieve the <= 1.1 behavior. | |
| - The org.apache.shiro.crypto.SecureRandomNumberGenerator previously defaulted to generating | |
| 128 random _bytes_ each time the nextBytes() method was called. This is too large for most purposes, so the | |
| default has been changed to 16 _bytes_ (which equals 128 bits - what was originally intended). If for some reason | |
| you need more than 16 bytes (128 bits) of randomly generated bits, you will need to configure the | |
| 'defaultNextByteSize' property to match your desired size (in bytes, NOT bits). | |
| - Shiro's Block Cipher Services (AesCipherService, BlowfishCipherService) have had the following changes: | |
| 1) The internal Cipher Mode and Streaming Cipher Mode have been changed from CFB to the new default of CBC. | |
| CBC is more commonly used for block ciphers today (e.g. SSL). | |
| If you were using an AES or Blowfish CipherService you will want to revert to the previous defaults in your config | |
| to ensure you can still decrypt previously encrypted data. For example, in code: | |
| blockCipherService.setMode(OperationMode.CFB); | |
| blockCipherService.setStreamingMode(OperationMode.CFB); | |
| or, in shiro.ini: | |
| blockCipherService.modeName = CFB | |
| blockCipherService.streamingModeName = CFB | |
| 2) The internal Streaming Padding Scheme has been changed from NONE to PKCS5 as PKCS5 is more commonly used. | |
| If you were using an AES or Blowfish CipherService for streaming operations, you will want to revert to the | |
| previous padding scheme default to ensure you can still decrypt previously encrypted data. For example, in code: | |
| blockCipherService.setStreamingPaddingScheme(PaddingScheme.NONE); | |
| or, in shiro.ini: | |
| blockCipherService.streamingPaddingSchemeName = NoPadding | |
| Note the difference in code vs shiro.ini in this last example: 'NoPadding' is the correct text value, 'NONE' is | |
| the correct Enum value. | |
| ########################################################### | |
| # 1.1.0 | |
| ########################################################### | |
| Backwards Incompatible Changes | |
| -------------------------------- | |
| - The org.apache.shiro.web.util.RedirectView class's | |
| appendQueryProperties(StringBuffer targetUrl, Map model, String encodingScheme) | |
| method has been changed to accept a StringBuilder argument instead of a | |
| StringBuffer per SHIRO-191. RedirectView is considered an internal | |
| implementation support class and Shiro end-users should not be affected by this. |