From 4f3855d6f88f633a1755602cd07ded1296554e05 Mon Sep 17 00:00:00 2001 From: Brian Demers Date: Sat, 22 Oct 2016 21:22:04 -0500 Subject: [PATCH] even more html to markdown --- caching.html | 63 ---- caching.md | 70 ++++ command-line-hasher.html | 99 ------ command-line-hasher.md | 90 +++++ commercial-support.html | 21 -- commercial-support.md | 19 + cryptography-features.html | 58 ---- cryptography-features.md | 52 +++ cryptography.html | 7 - cryptography.md | 8 + developer-resources.html.vtl | 34 -- developer-resources.md.vtl | 38 ++ developers.html | 47 --- developers.md | 48 +++ documentation-help-block.html | 5 - documentation-help-block.md | 6 + events.html | 18 - events.md | 27 ++ getting-started-block.html | 2 - getting-started-block.md | 4 + ...esolution.html => graduation-resolution.md | 10 +- jsp-tag-library.html | 30 -- jsp-tag-library.md | 22 ++ mailing-lists.html => mailing-lists.md | 16 +- permissions.html | 326 ------------------ permissions.md | 306 ++++++++++++++++ 26 files changed, 708 insertions(+), 718 deletions(-) delete mode 100644 caching.html create mode 100644 caching.md delete mode 100644 command-line-hasher.html create mode 100644 command-line-hasher.md delete mode 100644 commercial-support.html create mode 100644 commercial-support.md delete mode 100644 cryptography-features.html create mode 100644 cryptography-features.md delete mode 100644 cryptography.html create mode 100644 cryptography.md delete mode 100644 developer-resources.html.vtl create mode 100644 developer-resources.md.vtl delete mode 100644 developers.html create mode 100644 developers.md delete mode 100644 documentation-help-block.html create mode 100644 documentation-help-block.md delete mode 100644 events.html create mode 100644 events.md delete mode 100644 getting-started-block.html create mode 100644 getting-started-block.md rename graduation-resolution.html => graduation-resolution.md (88%) delete mode 100644 jsp-tag-library.html create mode 100644 jsp-tag-library.md rename mailing-lists.html => mailing-lists.md (63%) delete mode 100644 permissions.html create mode 100644 permissions.md diff --git a/caching.html b/caching.html deleted file mode 100644 index 46080a5f7e..0000000000 --- a/caching.html +++ /dev/null @@ -1,63 +0,0 @@ -

Caching

- -

The Shiro development team understands performance is critical in many applications. Caching is a first class feature built into Shiro from day one to ensure that security operations remain as fast as possible.

- -

However, while Caching as a concept is a fundamental part of Shiro, implementing a full Cache mechanism would be outside the core competency of a security framework. To that end, Shiro's cache support is basically an abstraction (wrapper) API that will 'sit' on top of an underlying production Cache mechanism (e.g. Hazelcast, Ehcache, OSCache, Terracotta, Coherence, GigaSpaces, JBossCache, etc). This allows a Shiro end-user to configure any cache mechanism they prefer.

- -

Caching API

- -

Shiro has three important cache interfaces:

- - - - -

A CacheManager returns Cache instances and various Shiro components use those Cache instances to cache data as necessary. Any Shiro
-component that implements CacheManagerAware will automatically receive a configured CacheManager, where it can be used to acquire Cache instances.

- -

The Shiro SecurityManager implementations and all AuthenticatingRealm and AuthorizingRealm implementations implement CacheManagerAware. If you set the CacheManager on the SecurityManager, it will in turn set it on the various Realms that implement CacheManagerAware as well (OO delegation). For example, in shiro.ini:

- -
example shiro.ini CacheManger configuration
-
-securityManager.realms = $myRealm1, $myRealm2, ..., $myRealmN
-...
-cacheManager = my.implementation.of.CacheManager
-...
-securityManager.cacheManager = $cacheManager
-# at this point, the securityManager and all CacheManagerAware
-# realms have been set with the cacheManager instance
-
-
- -

CacheManager Implementations

- -

Shiro provides a number of out-of-the-box CacheManager implementations that you might find useful instead of implementing your own.

- -

MemoryConstrainedCacheManager

- -

The MemoryConstrainedCacheManager is a CacheManager implementation suitable for single-JVM production environments. It is not clustered/distributed, so if your application spans across more than one JVM (e.g. web app running on multiple web servers), and you want cache entries to be accessible across JVMs, you will need to use a distributed cache implementation instead.

- -

The MemoryConstrainedCacheManager manages MapCache instances, one MapCache instance per named cache. Each MapCache instance is backed by a Shiro SoftHashMap which can auto-resize itself based on an application's runtime memory constraints/needs (by leveraging JDK SoftReference instances).

- -

Because the MemoryConstrainedCacheManager can auto-resize itself based on an application's memory profile, it is safe to use in a single-JVM production application as well as for testing needs. However, it does not have more advanced features suche as cache entry Time-to-Live or Time-to-Expire settings. For these more advanced cache management features, you'll likely want to use one of the more advanced CacheManager offerings below.

- -
MemoryConstrainedCacheManger shiro.ini configuration example
-
-
-...
-cacheManager = org.apache.shiro.cache.MemoryConstrainedCacheManager
-...
-securityManager.cacheManager = $cacheManager
-
-
- -

HazelcastCacheManager

- -

TBD

- -

EhCacheManager

- -

TBD

- -

Authorization Cache Invalidation

- -

Finally note that AuthorizingRealm has a clearCachedAuthorizationInfo method that can be called by subclasses to evict the cached authzInfo for a particular account. It is usually called by custom logic if the corresponding account's authz data has changed (to ensure the next authz check will pick up the new data).

\ No newline at end of file diff --git a/caching.md b/caching.md new file mode 100644 index 0000000000..d9c024d096 --- /dev/null +++ b/caching.md @@ -0,0 +1,70 @@ + +#Caching + +The Shiro development team understands performance is critical in many applications. Caching is a first class feature built into Shiro from day one to ensure that security operations remain as fast as possible. + +However, while Caching as a concept is a fundamental part of Shiro, implementing a full Cache mechanism would be outside the core competency of a security framework. To that end, Shiro's cache support is basically an abstraction (wrapper) API that will 'sit' on top of an underlying production Cache mechanism (e.g. Hazelcast, Ehcache, OSCache, Terracotta, Coherence, GigaSpaces, JBossCache, etc). This allows a Shiro end-user to configure any cache mechanism they prefer. + + +##Caching API + +Shiro has three important cache interfaces: + +* [`CacheManager`](static/current/apidocs/org/apache/shiro/cache/CacheManager.html) - The primary Manager component for all caching, it returns `Cache` instances. +* [`Cache`](static/current/apidocs/org/apache/shiro/cache/Cache.html) - Maintains key/value pairs +* [`CacheManagerAware`](static/current/apidocs/org/apache/shiro/cache/CacheManagerAware.html) - Implemented by components wishing to receive and use a CacheManager instance + +A `CacheManager` returns `Cache` instances and various Shiro components use those `Cache` instances to cache data as necessary. Any Shiro +component that implements `CacheManagerAware` will automatically receive a configured `CacheManager`, where it can be used to acquire `Cache` instances. + +The Shiro [SecurityManager](securitymanager.html "SecurityManager") implementations and all [`AuthenticatingRealm`](static/current/apidocs/org/apache/shiro/realm/AuthenticatingRealm.html) and [`AuthorizingRealm`](static/current/apidocs/org/apache/shiro/realm/AuthorizingRealm.html) implementations implement CacheManagerAware. If you set the `CacheManager` on the `SecurityManager`, it will in turn set it on the various Realms that implement CacheManagerAware as well (OO delegation). For example, in shiro.ini: + +**example shiro.ini CacheManger configuration** + +``` ini +securityManager.realms = $myRealm1, $myRealm2, ..., $myRealmN +... +cacheManager = my.implementation.of.CacheManager +... +securityManager.cacheManager = $cacheManager +# at this point, the securityManager and all CacheManagerAware +# realms have been set with the cacheManager instance +``` + + +##CacheManager Implementations + +Shiro provides a number of out-of-the-box `CacheManager` implementations that you might find useful instead of implementing your own. + + +###`MemoryConstrainedCacheManager` + +The [`MemoryConstrainedCacheManager`](static/current/apidocs/org/apache/shiro/cache/MemoryConstrainedCacheManager.html) is a `CacheManager` implementation suitable for single-JVM production environments. It is not clustered/distributed, so if your application spans across more than one JVM (e.g. web app running on multiple web servers), and you want cache entries to be accessible across JVMs, you will need to use a distributed cache implementation instead. + +The `MemoryConstrainedCacheManager` manages [`MapCache`](static/current/apidocs/org/apache/shiro/cache/MapCache.html) instances, one `MapCache` instance per named cache. Each `MapCache` instance is backed by a Shiro [`SoftHashMap`](static/current/apidocs/org/apache/shiro/util/SoftHashMap.html) which can auto-resize itself based on an application's runtime memory constraints/needs (by leveraging JDK [`SoftReference`](https://docs.oracle.com/javase/7/docs/api/java/lang/ref/SoftReference.html) instances). + +Because the `MemoryConstrainedCacheManager` can auto-resize itself based on an application's memory profile, it is safe to use in a single-JVM production application as well as for testing needs. However, it does not have more advanced features suche as cache entry Time-to-Live or Time-to-Expire settings. For these more advanced cache management features, you'll likely want to use one of the more advanced `CacheManager` offerings below. + +**MemoryConstrainedCacheManger shiro.ini configuration example** + +``` ini +... +cacheManager = org.apache.shiro.cache.MemoryConstrainedCacheManager +... +securityManager.cacheManager = $cacheManager +``` + + +###`HazelcastCacheManager` + +TBD + + +###`EhCacheManager` + +TBD + + +##Authorization Cache Invalidation + +Finally note that [`AuthorizingRealm`](static/current/apidocs/org/apache/shiro/realm/AuthorizingRealm.html) has a [clearCachedAuthorizationInfo method](static/current/apidocs/org/apache/shiro/realm/AuthorizingRealm.html#clearCachedAuthorizationInfo-org.apache.shiro.subject.PrincipalCollection-) that can be called by subclasses to evict the cached authzInfo for a particular account. It is usually called by custom logic if the corresponding account's authz data has changed (to ensure the next authz check will pick up the new data). \ No newline at end of file diff --git a/command-line-hasher.html b/command-line-hasher.html deleted file mode 100644 index c4b74ae88e..0000000000 --- a/command-line-hasher.html +++ /dev/null @@ -1,99 +0,0 @@ -

Command Line Hasher

- -
-
- -

Shiro 1.2.0 and later provides a command line program that can hash strings and resources (files, URLs, classpath entries) of almost any type. To use it, you must have a Java Virtual Machine installed and the 'java' command must be accessible in your $PATH environment variable.

- -

Usage

- -

Ensure you have access to the shiro-tools-hasher-version-cli.jar file. You can either find this in a source build in the buildroot/tools/hasher/target directory or via download through Maven.

- -

Once you have access to the jar, you can run the following command:

- -
-
-> java -jar shiro-tools-hasher-X.X.X-cli.jar
-
-
- -

This will print all available options for both standard (MD5, SHA1) and more complex password hashing scenarios.

- -

Common Scenarios

- -

Please read the printed instructions for the above command. It will provide an exhaustive list of instructions which will help you use the hasher depending on your needs. However, we've provided some quick reference usages/scenarios below for convenience.

- -

shiro.ini User Passwords

- -

It is best to keep user passwords in the shiro.ini [users] section secure. To add a new user account line, use the above command with the -p (or --password) option:

- -
-
-> java -jar shiro-tools-hasher-X.X.X-cli.jar -p
-
-
- -

It will then ask you to enter the password and then confirm it:

- -
-
-Password to hash:
-Password to hash (confirm):
-
-
- -

When this command executes, it will print out the securely-salted-iterated-and-hashed password. For example:

- -
-
-$shiro1$SHA-256$500000$eWpVX2tGX7WCP2J+jMCNqw==$it/NRclMOHrfOvhAEFZ0mxIZRdbcfqIBdwdwdDXW2dM=
-
-
- -

Take this value and place it as the password in the user definition line (followed by any optional roles) as defined in the INI Users Configuration documentation. For example:

- -
-
-[users]
-...
-user1 = $shiro1$SHA-256$500000$eWpVX2tGX7WCP2J+jMCNqw==$it/NRclMOHrfOvhAEFZ0mxIZRdbcfqIBdwdwdDXW2dM=
-
-
- -

You will also need to ensure that the implicit iniRealm uses a CredentialsMatcher that knows how to perform secure hashed password comparisons. So configure this in the [main] section as well:

- -
-
-[main]
-...
-passwordMatcher = org.apache.shiro.authc.credential.PasswordMatcher
-iniRealm.credentialsMatcher = $passwordMatcher
-...
-
-
- - -

MD5 checksum

- -

Although you can perform any hash with any algorithm supported on the JVM, the default hashing algorithm is MD5, common for file checksums. Just use the -r (or --resource) option to indicate the following value is a resource location (and not text you wish hashed):

- -
-
-> java -jar shiro-tools-hasher-X.X.X-cli.jar -r RESOURCE_PATH
-
-
- -

By default RESOURCE_PATH is expected to be a file path, but you may specify classpath or URL resources by using the classpath: or url: prefix respectively.

- -

Some examples:

- -
-
-<command> -r fileInCurrentDirectory.txt
-<command> -r ../../relativePathFile.xml
-<command> -r ~/documents/myfile.pdf
-<command> -r /usr/local/logs/absolutePathFile.log
-<command> -r url:http://foo.com/page.html
-<command> -r classpath:/WEB-INF/lib/something.jar
-
-
\ No newline at end of file diff --git a/command-line-hasher.md b/command-line-hasher.md new file mode 100644 index 0000000000..d812a742f7 --- /dev/null +++ b/command-line-hasher.md @@ -0,0 +1,90 @@ + +#Command Line Hasher + +* [Usage](#CommandLineHasher-Usage) +* [Common Scenarios](#CommandLineHasher-CommonScenarios) + +* [`shiro.ini` User Passwords](#CommandLineHasher-%7B%7Bshiro.ini%7D%7DUserPasswords) +* [MD5 checksum](#CommandLineHasher-MD5checksum) + + +Shiro 1.2.0 and later provides a command line program that can hash strings and resources (files, URLs, classpath entries) of almost any type. To use it, you must have a Java Virtual Machine installed and the 'java' command must be accessible in your `$PATH` environment variable. + + +##Usage + +Ensure you have access to the `shiro-tools-hasher-`_version_`-cli.jar` file. You can either find this in a source build in the _buildroot_`/tools/hasher/target` directory or via download through Maven. + +Once you have access to the jar, you can run the following command: + +``` bash +$ java -jar shiro-tools-hasher-X.X.X-cli.jar +``` + +This will print all available options for both standard (MD5, SHA1) and more complex password hashing scenarios. + + +##Common Scenarios + +Please read the printed instructions for the above command. It will provide an exhaustive list of instructions which will help you use the hasher depending on your needs. However, we've provided some quick reference usages/scenarios below for convenience. + + +###`shiro.ini` User Passwords + +It is best to keep user passwords in the `shiro.ini` `[users]` section secure. To add a new user account line, use the above command with the `**-p**` (or `--password`) option: + +``` bash +$ java -jar shiro-tools-hasher-X.X.X-cli.jar -p +``` + +It will then ask you to enter the password and then confirm it: + +``` bash +Password to hash: +Password to hash (confirm): +``` + +When this command executes, it will print out the securely-salted-iterated-and-hashed password. For example: + +``` bash +$shiro1$SHA-256$500000$eWpVX2tGX7WCP2J+jMCNqw==$it/NRclMOHrfOvhAEFZ0mxIZRdbcfqIBdwdwdDXW2dM= +``` + +Take this value and place it as the password in the user definition line (followed by any optional roles) as defined in the [INI Users Configuration](configuration.html#Configuration-%5Cusers%5C) documentation. For example: + +``` ini +[users] +... +user1 = $shiro1$SHA-256$500000$eWpVX2tGX7WCP2J+jMCNqw==$it/NRclMOHrfOvhAEFZ0mxIZRdbcfqIBdwdwdDXW2dM= +``` + +You will also need to ensure that the implicit `iniRealm` uses a `CredentialsMatcher` that knows how to perform secure hashed password comparisons. So configure this in the `[main]` section as well: + +``` ini +[main] +... +passwordMatcher = org.apache.shiro.authc.credential.PasswordMatcher +iniRealm.credentialsMatcher = $passwordMatcher +... +``` + + +###MD5 checksum + +Although you can perform any hash with any algorithm supported on the JVM, the default hashing algorithm is MD5, common for file checksums. Just use the `**-r**` (or `--resource`) option to indicate the following value is a resource location (and not text you wish hashed): + +``` bash +$ java -jar shiro-tools-hasher-X.X.X-cli.jar -r RESOURCE_PATH +``` + +By default `RESOURCE_PATH` is expected to be a file path, but you may specify classpath or URL resources by using the `classpath:` or `url:` prefix respectively. + +Some examples: + +``` bash + -r fileInCurrentDirectory.txt + -r ../../relativePathFile.xml + -r ~/documents/myfile.pdf + -r /usr/local/logs/absolutePathFile.log + -r url:http://foo.com/page.html -r classpath:/WEB-INF/lib/something.jar +``` \ No newline at end of file diff --git a/commercial-support.html b/commercial-support.html deleted file mode 100644 index 960b457cd0..0000000000 --- a/commercial-support.html +++ /dev/null @@ -1,21 +0,0 @@ -

Service and Commercial Support for Apache Shiro

- -
-

- Apache Shiro Plugin for Stormpath User Management -

- -

The Apache Shiro plugin for Stormpath allows an Apache Shiro-enabled application to use the Stormpath User Management & Authentication service for all authentication and access control needs.

- -

Pairing Shiro with Stormpath give you a full application security system complete with immediate user account support, admin UI, authentication service, account registration and password reset workflows, password security, and more-- with little to no coding on your part.

- Learn More >>> -

- Stormpath Commercial Support for Apache Shiro -

- -

Shiro commercial support and consulting services are available from Stormpath, a company started by Shiro committer and Project Chair, Les Hazlewood: -

- Learn More >>> -
-
-

Providing Shiro services? Get listed on this page by posting to the Dev Mailing list

\ No newline at end of file diff --git a/commercial-support.md b/commercial-support.md new file mode 100644 index 0000000000..7c34fa73cc --- /dev/null +++ b/commercial-support.md @@ -0,0 +1,19 @@ + +#Service and Commercial Support for Apache Shiro + + +### [Apache Shiro Plugin for Stormpath User Management](https://www.stormpath.com "Stormpath User Management") + +The [Apache Shiro plugin for Stormpath](https://github.com/stormpath/stormpath-shiro/wiki) allows an Apache Shiro-enabled application to use the [Stormpath User Management & Authentication service](https://www.stormpath.com) for all authentication and access control needs. + +Pairing Shiro with Stormpath give you a full application security system complete with immediate user account support, admin UI, authentication service, account registration and password reset workflows, password security, and more-- with little to no coding on your part. + +[Learn More >>>](https://github.com/stormpath/stormpath-shiro/wiki "Apache Shiro plugin for Stormpath") + +### [Stormpath Commercial Support for Apache Shiro](https://www.stormpath.com/apache-shiro-support "Stormpath Support for Apache Shiro") + +Shiro commercial support and consulting services are available from Stormpath, a company started by Shiro committer and Project Chair, Les Hazlewood: + +[Learn More >>>](https://www.stormpath.com/apache-shiro-support "Stormpath Support for Apache Shiro") + +**Providing Shiro services? Get listed on this page by posting to the [Dev Mailing list](mailing-lists.html "Shiro Mailing Lists")** \ No newline at end of file diff --git a/cryptography-features.html b/cryptography-features.html deleted file mode 100644 index fa48535917..0000000000 --- a/cryptography-features.html +++ /dev/null @@ -1,58 +0,0 @@ -

Apache Shiro Cryptography Features

- - -
-Share -| - - - - -
- - - - -


-Cryptography is the practice of protecting information from undesired access by hiding it or converting it into nonsense so know one else can read it. Shiro focuses on two core elements of Cryptography: ciphers that encrypt data like email using a public or private key, and hashes (aka message digests) that irreversibly encrypt data like passwords.

- -

Shiro Cryptography's primary goal is take what has traditionally be an extremely complex field and make it easy for the rest of us while providing a robust set of cryptography features.

- -

Simplicity Features

- -
  • Interface-driven, POJO based - All of Shiro's APIs are interface-based and implemented as POJOs. This allows you to easily configure Shiro Cryptography components with JavaBeans-compatible formats like JSON, YAML, Spring XML and others. You can also override or customize Shiro as you see necessary, leveraging its API to save you time and effort.
- - -
  • Simplified wrapper over JCE - The Java Cryptography Extension (JCE) can be complicated and difficult to use unless you're a cryptography expert. Shiro's Cryptography APIs are much easier to understand and use, and they dramatically simplify JCE concepts. So now even Cryptography novices can find what they need in minutes rather than hours or days. And you won't sacrifice any functionality because you still have access to more complicated JCE options if you need them.
- - -
  • “Object Orientifies” cryptography concepts - The JDK/JCE's Cipher and Message Digest (Hash) classes are abstract classes and quite confusing, requiring you to use obtuse factory methods with type-unsafe string arguments to acquire instances you want to use. Shiro 'Object Orientifies' Ciphers and Hashes, basing them on a clean object hierarchy, and allows you to use them by simple instantiation.
- - -
  • Runtime Exceptions - Like everywhere else in Shiro, all cryptography exceptions are RuntimeExceptions. You can decide whether or not to catch an exception based on your needs.
- - -

Cipher Features

- -
  • OO Hierarchy - Unlike the JCE, Shiro Cipher representations follow an Object-Oriented class hierarchy that match their mathematical concepts: AbstractSymmetricCipherService, DefaultBlockCipherService, AesCipherService, etc. This allows you to easily override existing classes and extend functionality as needed.
- - -
  • Just instantiate a class - Unlike the JCE's confusing factory methods using String token arguments, using Shiro Ciphers are much easier - just instantiate a class, configure it with JavaBeans properties as necessary, and use it as desired. For example, new AesCipherService().
- - -
  • More secure default settings - The JCE Cipher instances assume a 'lowest common denominator' default and do not automatically enable more secure options. Shiro will automatically enable the more secure options to ensure your data is as safe as it can be by default, helping you prevent accidental security holes.
- - -

Hash Features

- -
  • Deault interface implementations - Shiro provides default Hash (aka Message Digests in the JDK) implementations out-of-the-box, such as MD5, SHA1, SHA-256, et al. This provides a type-safe construction method (e.g. new Md5Hash(data)) instead of being forced to use type-unsafe string factory methods in the JDK.
- - -
  • Built-in Hex and Base64 conversion - Shiro Hash instances can automatically provide Hex and Base-64 encoding of hashed data via their toHex() and toBase64() methods. So now you do not need to figure out how to correctly encode the data yourself.
- - -
  • Built-in Salt and repeated hashing support - Salts and repeated hash iterations are very valuable tools when hashing data, especially when it comes to protecting user passwords. Shiro's Hash implementations support salts and multiple hash iterations out of the box so you don't have to repeat this logic anywhere you might need it.
- - -

Get Started in 10 Minutes with Shiro

-

Try out Shiro for yourself with our 10 Minute Tutorial. And if you have any questions about Shiro, please check out our community forum or user mailing list for answers from the community.

\ No newline at end of file diff --git a/cryptography-features.md b/cryptography-features.md new file mode 100644 index 0000000000..a0ee09a6f6 --- /dev/null +++ b/cryptography-features.md @@ -0,0 +1,52 @@ + +#Apache Shiro Cryptography Features + +
+ Share + | + + + + +
+ + + + +Cryptography is the practice of protecting information from undesired access by hiding it or converting it into nonsense so know one else can read it. Shiro focuses on two core elements of Cryptography: ciphers that encrypt data like email using a public or private key, and hashes (aka message digests) that irreversibly encrypt data like passwords. + +Shiro Cryptography's primary goal is take what has traditionally be an extremely complex field and make it easy for the rest of us while providing a robust set of cryptography features. + + +##Simplicity Features + +* **Interface-driven, POJO based** - All of Shiro's APIs are interface-based and implemented as POJOs. This allows you to easily configure Shiro Cryptography components with JavaBeans-compatible formats like JSON, YAML, Spring XML and others. You can also override or customize Shiro as you see necessary, leveraging its API to save you time and effort. + +* **Simplified wrapper over JCE** - The Java Cryptography Extension (JCE) can be complicated and difficult to use unless you're a cryptography expert. Shiro's Cryptography APIs are much easier to understand and use, and they dramatically simplify JCE concepts. So now even Cryptography novices can find what they need in minutes rather than hours or days. And you won't sacrifice any functionality because you still have access to more complicated JCE options if you need them. + +* **“Object Orientifies” cryptography concepts** - The JDK/JCE's Cipher and Message Digest (Hash) classes are abstract classes and quite confusing, requiring you to use obtuse factory methods with type-unsafe string arguments to acquire instances you want to use. Shiro 'Object Orientifies' Ciphers and Hashes, basing them on a clean object hierarchy, and allows you to use them by simple instantiation. + +* **Runtime Exceptions** - Like everywhere else in Shiro, all cryptography exceptions are RuntimeExceptions. You can decide whether or not to catch an exception based on your needs. + + +##Cipher Features + +* **OO Hierarchy** - Unlike the JCE, Shiro Cipher representations follow an Object-Oriented class hierarchy that match their mathematical concepts: `AbstractSymmetricCipherService`, `DefaultBlockCipherService`, `AesCipherService`, etc. This allows you to easily override existing classes and extend functionality as needed. + +* **Just instantiate a class** - Unlike the JCE's confusing factory methods using String token arguments, using Shiro Ciphers are much easier - just instantiate a class, configure it with JavaBeans properties as necessary, and use it as desired. For example, `new AesCipherService()`. + +* **More secure default settings** - The JCE Cipher instances assume a 'lowest common denominator' default and do not automatically enable more secure options. Shiro will automatically enable the more secure options to ensure your data is as safe as it can be by default, helping you prevent accidental security holes. + + +##Hash Features + +* **Deault interface implementations** - Shiro provides default Hash (aka Message Digests in the JDK) implementations out-of-the-box, such as MD5, SHA1, SHA-256, et al. This provides a type-safe construction method (e.g. `new Md5Hash(data)`) instead of being forced to use type-unsafe string factory methods in the JDK. + +* **Built-in Hex and Base64 conversion** - Shiro Hash instances can automatically provide Hex and Base-64 encoding of hashed data via their `toHex()` and `toBase64()` methods. So now you do not need to figure out how to correctly encode the data yourself. + +* **Built-in Salt and repeated hashing support** - Salts and repeated hash iterations are very valuable tools when hashing data, especially when it comes to protecting user passwords. Shiro's Hash implementations support salts and multiple hash iterations out of the box so you don't have to repeat this logic anywhere you might need it. + + +##Get Started in 10 Minutes with Shiro + +Try out Shiro for yourself with our [10 Minute Tutorial](10-minute-tutorial.html "10 Minute Tutorial"). And if you have any questions about Shiro, please check out our [community forum](forums.html "Forums") or [user mailing list](mailing-lists.html "Mailing Lists") for answers from the community. \ No newline at end of file diff --git a/cryptography.html b/cryptography.html deleted file mode 100644 index a5f5faf98e..0000000000 --- a/cryptography.html +++ /dev/null @@ -1,7 +0,0 @@ -

TO DO. In the mean time, you can read more about Shiro's Crypography Features.

- -

Lend a hand with documentation

- -

While we hope this documentation helps you with the work you're doing with Apache Shiro, the community is improving and expanding the documentation all the time. If you'd like to help the Shiro project, please consider corrected, expanding, or adding documentation where you see a need. Every little bit of help you provide expands the community and in turn improves Shiro.

- -

The easiest way to contribute your documentation is to send it to the User Forum or the User Mailing List.

diff --git a/cryptography.md b/cryptography.md new file mode 100644 index 0000000000..1d41ddb09d --- /dev/null +++ b/cryptography.md @@ -0,0 +1,8 @@ +TODO. In the mean time, you can read more about [Shiro's Crypography Features](cryptography-features.html "Apache Shiro Cryptography Features"). + + +##Lend a hand with documentation + +While we hope this documentation helps you with the work you're doing with Apache Shiro, the community is improving and expanding the documentation all the time. If you'd like to help the Shiro project, please consider corrected, expanding, or adding documentation where you see a need. Every little bit of help you provide expands the community and in turn improves Shiro. + +The easiest way to contribute your documentation is to send it to the [User Forum](http://shiro-user.582556.n2.nabble.com/) or the [User Mailing List](mailing-lists.html "Mailing Lists"). \ No newline at end of file diff --git a/developer-resources.html.vtl b/developer-resources.html.vtl deleted file mode 100644 index 4faeafba2c..0000000000 --- a/developer-resources.html.vtl +++ /dev/null @@ -1,34 +0,0 @@ -

Apache Shiro Developer Resources

- -

This page and its children are dedicated for reference information used by the Apache Shiro development team when performing tasks as a committer or contributor

- -

Writing Documentation

- -

All non-JavaDoc documentation is managed in our apache/shiro-site repo.

- -

Source Code Repository

- -

We use a Git repository located at git://git.apache.org/shiro.git.

- -

Active development is done in the master branch, and maintenance typically on the 1.2.x branch.

- -

Building from Git

- -

For Shiro cutting-edge development, you can clone the code from Git and build it using Maven 2.2+:

- -
  1. Check out the code: -
    -
    -git clone https://github.com/apache/shiro.git
-
    -
  2. Build the project using Maven 2.2+: -
    -
    -cd shiro
-mvn install
-
    -
    -

    The resulting artifacts will be in your local M2 Repo under the org.apache.shiro group.

- - -#danger('Cutting-edge development', 'When building from master or any branches, use the generated artifacts at your own risk! Current and previous stable releases will always be available via the Download page.') \ No newline at end of file diff --git a/developer-resources.md.vtl b/developer-resources.md.vtl new file mode 100644 index 0000000000..eb4b12fbf3 --- /dev/null +++ b/developer-resources.md.vtl @@ -0,0 +1,38 @@ + +#[[#Apache Shiro Developer Resources]]# + +This page and its children are dedicated for reference information used by the Apache Shiro development team when performing tasks as a committer or contributor + + +#[[##Writing Documentation]]# + +All non-JavaDoc documentation is managed in our [apache/shiro-site](https://github.com/apache/shiro-site) repo. + + +#[[##Source Code Repository]]# + +We use a Git repository located at [git://git.apache.org/shiro.git](git://git.apache.org/shiro.git). + +Active development is done in the `master` branch, and maintenance typically on the `1.2.x` branch. + + +#[[###Building from Git]]# + +For Shiro cutting-edge development, you can clone the code from Git and build it using [Maven](http://maven.apache.org) 2.2+: + +1. Check out the code: + + ``` bash + git clone https://github.com/apache/shiro.git + ``` + +2. Build the project using [Maven](http://maven.apache.org) 3.x+: + + ``` bash + cd shiro + mvn install + ``` + + The resulting artifacts will be in your local M2 Repo under the org.apache.shiro group. + +#danger('Cutting-edge development', 'When building from `master` or any branches, use the generated artifacts at your own risk! Current and previous stable releases will always be available via the Download page.') \ No newline at end of file diff --git a/developers.html b/developers.html deleted file mode 100644 index fa94209ebe..0000000000 --- a/developers.html +++ /dev/null @@ -1,47 +0,0 @@ -

Apache Shiro Developer Reference Information

- -

This page and its children are dedicated for reference information used by the Apache Shiro development team when performing tasks as a committer.

- -

Writing Documentation

- -

All non-JavaDoc documentation is written in our Apache Shiro Confluence Wiki Space. This space is converted into the public website as described below.

- -

Version 2 Brainstorming

- -

Version 2 has no timeline yet, but if you're interested in seeing what the major ideas are, as well as to contribute any of your own, you can visit the Version 2 Brainstorming Page.

- -

Website

- -

The Shiro website is automatically generated based on the content maintained in the Apache Shiro Confluence Wiki Space, with a few notable exceptions that we'll cover in a bit. Here's how it works:

- -
  1. Shiro committers and approved contributors modify the Confluence wiki pages as necessary. The left navigation panel is controlled by the Navigation wiki page. -
    -
  2. Confluence detects changes to these pages and executes a 3rd-party Auto Export Confluence Plugin that renders the content to .html files that can be served to the world (this plugin was installed in Confluence by the Apache Infrastructure team). If you're setting up Auto Export for the first time, read the "Setting up Confluence Export" section below. -
    -
    -
    1. A project contributor makes a single Velocity-based HTML template file. It can reference associated static assets (images, css files, javascript, etc) as necessary. They test it in their HTML design tool of choice to get the look and feel they want. -
      -
    2. The template designer sends the one HTML template file only (and not the referenced static assets) to an Apache member with Confluence administrative privileges and asks them to install their HTML template file into the Auto Export plugin configuration. Unfortunately only a Confluence administrators may perform this function - the plugin does not support administration on a per-project level. -
      -
      -You will have to separately upload the any referenced static assets to another location. We'll cover that shortly. -
      -
    3. The Confluence administrator installs the HTML template for the project's space only.
    4. For each wiki page, the auto export plugin merges the page content with an HTML template and outputs a new .html file (html template + wiki content body = finished page).
    5. All of the output files and any associated data (attachments, etc) are placed in a filesystem directory that mirrors content tree hierarchy in the wiki.
      -the The output files mirror the fileThe auto export plugin takes all of the pages and their content (attachments, etc), applies a single HTML template to each wiki page, and outputs each 'merged' page (html template + embedded wiki content = finished page)
    -
- - -

The website files are maintained on people.apache.org in /www/shiro.apache.org:

- -
-
> ssh people.apache.org
-
-(a bunch of login messages)
-
-[lhazlewood@minotaur:~]$
-[lhazlewood@minotaur:~]$ cd /www/shiro.apache.org
-[lhazlewood@minotaur:/www/shiro.apache.org]$ 
-
-
- -

Changes made to any files under this directory are synced and published to a set of mirrored Apache web servers that we can't access. So note: Any changes to files under this directory will be propagated to the public Shiro site. Be careful!

\ No newline at end of file diff --git a/developers.md b/developers.md new file mode 100644 index 0000000000..e0a06d01da --- /dev/null +++ b/developers.md @@ -0,0 +1,48 @@ + +#Apache Shiro Developer Reference Information + +This page and its children are dedicated for reference information used by the Apache Shiro development team when performing tasks as a committer. + + +##Writing Documentation + +All non-JavaDoc documentation is written in our [Apache Shiro Confluence Wiki Space](https://cwiki.apache.org/confluence/display/SHIRO). This space is converted into the public website as described below. + + +##Version 2 Brainstorming + +Version 2 has no timeline yet, but if you're interested in seeing what the major ideas are, as well as to contribute any of your own, you can visit the [Version 2 Brainstorming Page](https://cwiki.apache.org/confluence/display/SHIRO/Version+2+Brainstorming). + + +##Website + +The Shiro website is automatically generated based on the content maintained in the [Apache Shiro Confluence Wiki Space](https://cwiki.apache.org/confluence/display/SHIRO), with a few notable exceptions that we'll cover in a bit. Here's how it works: + +1. Shiro committers and approved contributors modify the Confluence wiki pages as necessary. The left navigation panel is controlled by the [Navigation wiki page](https://cwiki.apache.org/confluence/display/SHIRO/Navigation). + +2. Confluence detects changes to these pages and executes a 3rd-party [Auto Export Confluence Plugin](http://code.google.com/p/couldit-autoexport) that renders the content to .html files that can be served to the world (this plugin was installed in Confluence by the Apache Infrastructure team). If you're setting up `Auto Export` for the first time, read the "Setting up Confluence Export" section below. + + 1. A project contributor makes a single Velocity-based HTML template file. It can reference associated static assets (images, css files, javascript, etc) as necessary. They test it in their HTML design tool of choice to get the look and feel they want. + + 2. The template designer sends the one HTML template file only (and not the referenced static assets) to an Apache member with Confluence administrative privileges and asks them to install their HTML template file into the `Auto Export` plugin configuration. Unfortunately only a Confluence administrators may perform this function - the plugin does not support administration on a per-project level. + + You will have to separately upload the any referenced static assets to another location. We'll cover that shortly. + + 3. The Confluence administrator installs the HTML template for the project's space only. + 4. For each wiki page, the auto export plugin merges the page content with an HTML template and outputs a new `.html` file (html template + wiki content body = finished page). + 5. All of the output files and any associated data (attachments, etc) are placed in a filesystem directory that mirrors content tree hierarchy in the wiki. + the The output files mirror the fileThe auto export plugin takes all of the pages and their content (attachments, etc), applies a single HTML template to each wiki page, and outputs each 'merged' page (html template + embedded wiki content = finished page) + +The website files are maintained on `people.apache.org` in `/www/shiro.apache.org`: + +``` bash +> ssh people.apache.org + +(a bunch of login messages) + +[lhazlewood@minotaur:~]$ +[lhazlewood@minotaur:~]$ cd /www/shiro.apache.org +[lhazlewood@minotaur:/www/shiro.apache.org]$ +``` + +Changes made to any files under this directory are synced and published to a set of mirrored Apache web servers that we can't access. So note: **Any changes to files under this directory will be propagated to the public Shiro site**. Be careful! \ No newline at end of file diff --git a/documentation-help-block.html b/documentation-help-block.html deleted file mode 100644 index 58035baae4..0000000000 --- a/documentation-help-block.html +++ /dev/null @@ -1,5 +0,0 @@ -

Lend a hand with documentation

- -

While we hope this documentation helps you with the work you're doing with Apache Shiro, the community is improving and expanding the documentation all the time. If you'd like to help the Shiro project, please consider corrected, expanding, or adding documentation where you see a need. Every little bit of help you provide expands the community and in turn improves Shiro.

- -

The easiest way to contribute your documentation is to send it to the User Forum or the User Mailing List.

\ No newline at end of file diff --git a/documentation-help-block.md b/documentation-help-block.md new file mode 100644 index 0000000000..0c75793941 --- /dev/null +++ b/documentation-help-block.md @@ -0,0 +1,6 @@ + +##Lend a hand with documentation + +While we hope this documentation helps you with the work you're doing with Apache Shiro, the community is improving and expanding the documentation all the time. If you'd like to help the Shiro project, please consider corrected, expanding, or adding documentation where you see a need. Every little bit of help you provide expands the community and in turn improves Shiro. + +The easiest way to contribute your documentation is to send it to the [User Forum](http://shiro-user.582556.n2.nabble.com/) or the [User Mailing List](mailing-lists.html "Mailing Lists"). \ No newline at end of file diff --git a/events.html b/events.html deleted file mode 100644 index b053cd30b2..0000000000 --- a/events.html +++ /dev/null @@ -1,18 +0,0 @@ -

Apache Shiro Events

- -

Below is list of upcoming and past Shiro events.

- -

Upcoming Events

- -

DevNexus: Application Security with Apache Shiro

-

March 22, 2011, Atlanta, GA -
https://www.devnexus.com/s/presentations#1138

- -

Past Events

- -

San Francisco Java User Group: Super Simple Application Security with Apache Shiro

-

October 12, 2010, San Francisco, CA -
http://www.meetup.com/sfjava/

- -

SDForum: Securing Applications with Apache Shiro

-

June 1, 2010, Palo Alto, CA

\ No newline at end of file diff --git a/events.md b/events.md new file mode 100644 index 0000000000..e2e3a366f8 --- /dev/null +++ b/events.md @@ -0,0 +1,27 @@ + +#Apache Shiro Events + +Below is list of upcoming and past Shiro events. + + +##Upcoming Events + + +###DevNexus: Application Security with Apache Shiro + +March 22, 2011, Atlanta, GA +[https://www.devnexus.com/s/presentations#1138](https://www.devnexus.com/s/presentations#1138) + + +##Past Events + + +###San Francisco Java User Group: Super Simple Application Security with Apache Shiro + +October 12, 2010, San Francisco, CA +[http://www.meetup.com/sfjava/](http://www.meetup.com/sfjava/) + + +###SDForum: Securing Applications with Apache Shiro + +June 1, 2010, Palo Alto, CA \ No newline at end of file diff --git a/getting-started-block.html b/getting-started-block.html deleted file mode 100644 index a6df7c22a2..0000000000 --- a/getting-started-block.html +++ /dev/null @@ -1,2 +0,0 @@ -

Get Started in 10 Minutes with Shiro

-

Try out Shiro for yourself with our 10 Minute Tutorial. And if you have any questions about Shiro, please check out our community forum or user mailing list for answers from the community.

\ No newline at end of file diff --git a/getting-started-block.md b/getting-started-block.md new file mode 100644 index 0000000000..02209ea769 --- /dev/null +++ b/getting-started-block.md @@ -0,0 +1,4 @@ + +##Get Started in 10 Minutes with Shiro + +Try out Shiro for yourself with our [10 Minute Tutorial](10-minute-tutorial.html "10 Minute Tutorial"). And if you have any questions about Shiro, please check out our [community forum](forums.html "Forums") or [user mailing list](mailing-lists.html "Mailing Lists") for answers from the community. \ No newline at end of file diff --git a/graduation-resolution.html b/graduation-resolution.md similarity index 88% rename from graduation-resolution.html rename to graduation-resolution.md index e2920097b9..9c1c62c267 100644 --- a/graduation-resolution.html +++ b/graduation-resolution.md @@ -1,7 +1,8 @@ -

Apache Shiro Graduation Resolution

+ +#Apache Shiro Graduation Resolution -
-
Establish Apache Shiro Project
+``` nohighlight
+Establish Apache Shiro Project
 
 WHEREAS, the Board of Directors deems it to be in the best
 interests of the Foundation and consistent with the Foundation's
@@ -51,5 +52,4 @@ 
Apache Sh
 RESOLVED, that all responsibility pertaining to the Apache
 Incubator Shiro podling encumbered upon the Apache Incubator
 PMC are hereafter discharged.
-
-
\ No newline at end of file +``` \ No newline at end of file diff --git a/jsp-tag-library.html b/jsp-tag-library.html deleted file mode 100644 index 9297073fcc..0000000000 --- a/jsp-tag-library.html +++ /dev/null @@ -1,30 +0,0 @@ -

JSP/GSP Tag Library for Apache Shiro

- -
  • <shiro:guest/> - Displays body content only if the current Subject IS NOT known to the system, either because they have not logged in or they have no corresponding 'RememberMe' identity. It is logically opposite to the 'user' tag.
- - -
  • <shiro:user/> - Displays body content only if the current Subject has a known identity, either from a previous login or from 'RememberMe' services. Note that this is semantically different from the 'authenticated' tag, which is more restrictive. It is logically opposite to the 'guest' tag.
- - -
  • <shiro:principal/> - Displays the user's principal or a property of the user's principal.
- - -
  • <shiro:hasPermission/> - Displays body content only if the current Subject (user) 'has' (implies) the specified permission (i.e the user has the specified ability).
- - -
  • <shiro:lacksPermission/> - Displays body content only if the current Subject (user) does NOT have (not imply) the specified permission (i.e. the user lacks the specified ability)
- - -
  • <shiro:hasRole/> - Displays body content only if the current user has the specified role.
- - -
  • <shiro:lacksRole/> - Displays body content only if the current user does NOT have the specified role (i.e. they explicitly lack the specified role)
- - -
  • <shiro:hasAnyRoles/> - Displays body content only if the current user has one of the specified roles from a comma-separated list of role names
- - -
  • <shiro:authenticated/> - Displays body content only if the current user has successfully authenticated during their current session. It is more restrictive than the 'user' tag. It is logically opposite to the 'notAuthenticated' tag.
- - -
  • <shiro:notAuthenticated/> - Displays body content only if the current user has NOT succesfully authenticated during their current session. It is logically opposite to the 'authenticated' tag.
diff --git a/jsp-tag-library.md b/jsp-tag-library.md new file mode 100644 index 0000000000..5804469da3 --- /dev/null +++ b/jsp-tag-library.md @@ -0,0 +1,22 @@ + +#JSP/GSP Tag Library for Apache Shiro + +* **** - Displays body content only if the current Subject IS NOT known to the system, either because they have not logged in or they have no corresponding 'RememberMe' identity. It is logically opposite to the 'user' tag. + +* **** - Displays body content only if the current Subject has a known identity, either from a previous login or from 'RememberMe' services. Note that this is semantically different from the 'authenticated' tag, which is more restrictive. It is logically opposite to the 'guest' tag. + +* **** - Displays the user's principal or a property of the user's principal. + +* **** - Displays body content only if the current Subject (user) 'has' (implies) the specified permission (i.e the user has the specified ability). + +* **** - Displays body content only if the current Subject (user) does NOT have (not imply) the specified permission (i.e. the user lacks the specified ability) + +* **** - Displays body content only if the current user has the specified role. + +* **** - Displays body content only if the current user does NOT have the specified role (i.e. they explicitly lack the specified role) + +* **** - Displays body content only if the current user has one of the specified roles from a comma-separated list of role names + +* **** - Displays body content only if the current user has successfully authenticated _during their current session_. It is more restrictive than the 'user' tag. It is logically opposite to the 'notAuthenticated' tag. + +* **** - Displays body content only if the current user has NOT succesfully authenticated _during their current session_. It is logically opposite to the 'authenticated' tag. \ No newline at end of file diff --git a/mailing-lists.html b/mailing-lists.md similarity index 63% rename from mailing-lists.html rename to mailing-lists.md index 751d45b22e..b480febedc 100644 --- a/mailing-lists.html +++ b/mailing-lists.md @@ -1,4 +1,13 @@ -

Apache Shiro Mailing Lists

+ +#Apache Shiro Mailing Lists + +
@@ -41,6 +50,7 @@

Apache Shiro Mailing List -

Discussion Forums

+ +###Discussion Forums -

If you prefer you could use our discussion Forums which are sync'd with the above mailing lists.

\ No newline at end of file +If you prefer you could use our discussion [Forums](forums.html "Forums") which are sync'd with the above mailing lists. \ No newline at end of file diff --git a/permissions.html b/permissions.html deleted file mode 100644 index 9fe4d4f7bb..0000000000 --- a/permissions.html +++ /dev/null @@ -1,326 +0,0 @@ -

Understanding Permissions in Apache Shiro

- -
- - - - -
-
-

Related Content

- -

Java Authorization Guide

-

Learn how Shiro handles access control in Java.
Read More >>

- -

Web App Tutorial

-

Step-by-step tutorial for securing a web application with Shiro.
Read More >>

- -

Getting Started

-

Resources, guides and tutorials for new Shiro users.
Read More >>

- -

10-Minute Shiro Tutorial

-

Try Apache Shiro for yourself in under 10 minutes.
Read More >>

- -
-
- -

Shiro defines a Permission as a statement that defines an explicit behavior or action. It is a statement of raw functionality in an application and nothing more. Permissions are the lowest-level constructs in security polices, and they explicitly define only "what" the application can do.

- -

They do not at all describe "who" is able to perform the action(s).

- -

Some examples of permissions:

-
  • Open a file
  • View the '/user/list' web page
  • Print documents
  • Delete the 'jsmith' user
- - -

Defining "who" (users) is allowed to do "what" (permissions) is an exercise of assigning permissions to users in some way. This is always done by the application's data model and can vary greatly across applications.

- -

For example, permissions can be grouped in a Role and that Role could be associated with one or more User objects. Or some applications can have a Group of users and a Group can be assigned a Role, which by transitive association would mean that all the Users in that Group are implicitly granted the permissions in the Role.

- -

There are many variations for how permissions could be granted to users - the application determines how to model this based on the application requirements.

- -

Wildcard Permissions

- -

The above examples of permissions, "Open a file", "View the 'user/list' web page", etc are all valid permission statements. However, it would be very difficult computationally to interpret those natural language strings and determine if a user is allowed to perform that behavior or not.

- -

So to enable easy-to-process yet still readable permission statements, Shiro provides powerful and intuitive permission syntax we refer to as the WildcardPermission.

- -

Simple Usage

- -

Let's you want to protect access to your company's printers such that some people can print to particular printers, while others can query what jobs are currently in the queue.

- -

An extremely simple approach would be to use grant the user a "queryPrinter" permission. Then you could check to see if the user has the queryPrinter permission by calling:

- -
-
-subject.isPermitted("queryPrinter")
-
-
- -

This is (mostly) equivalent to

- -
-
-subject.isPermitted( new WildcardPermission("queryPrinter") )
-
-
- -

but more on that later.

- -

The simple permission string may work for simple applications, but it requires you to have permissions like "printPrinter", "queryPrinter", "managePrinter", etc. You can also grant a user "*" permissions using the wildcard character (giving this permission construct its name), which means they have all permissions across the entire application.

- -

But using this approach there's no way to just say a user has "all printer permissions". For this reason, Wildcard Permissions supports multiple levels of permissioning.

- -

Multiple Parts

- -

Wildcard Permissions support the concept of multiple levels or parts. For example, you could restructure the previous simple example by granting a user the permission

-
-
-printer:query
-
-
-

The colon in this example is a special character used to delimit the next part in the permission string.

- -

In this example, the first part is the domain that is being operated on (printer) and the second part is the action (query) being performed. The other above examples would be changed to:

- -
-
-printer:print
-printer:manage
-
-
- -

There is no limit to the number of parts that can be used, so it is up to your imagination in terms of ways that this could be used in your application.

- -

Multiple Values

- -

Each part can contain multiple values. So instead of granting the user both the "printer:print" and "printer:query" permissions, you could simply grant them one:

-
-
-printer:print,query
-
-
- -

which gives them the ability to print and query printers. And since they are granted both those actions, you could check to see if the user has the ability to query printers by calling:

-
-
-subject.isPermitted("printer:query")
-
-
-

which would return true

- -

All Values

- -

What if you wanted to grant a user all values in a particular part? It would be more convenient to do this than to have to manually list every value. Again, based on the wildcard character, we can do this. If the printer domain had 3 possible actions (query, print, and manage), this:

-
-
-printer:query,print,manage
-
-
-

simply becomes this:

-
-
-printer:*
-
-
- -

Then, any permission check for "printer:XXX" will return true. Using the wildcard in this way scales better than explicitly listing actions since, if you added a new action to the application later, you don't need to update the permissions that use the wildcard character in that part.

- -

Finally, it is also possible to use the wildcard token in any part of a wildcard permission string. For example, if you wanted to grant a user the "view" action across all domains (not just printers), you could grant this:

-
-
-*:view
-
-
- -

Then any permission check for "foo:view" would return true

- -

Instance-Level Access Control

- -

Another common usage of wildcard permissions is to model instance-level Access Control Lists. In this scenario you use three parts - the first is the domain, the second is the action(s), and the third is the instance(s) being acted upon.

- -

So for example you could have

-
-
-printer:query:lp7200
-printer:print:epsoncolor
-
-
- -

The first defines the behavior to query the printer with the ID lp7200. The second permission defines the behavior to print to the printer with ID epsoncolor. If you grant these permissions to users, then they can perform specific behavior on specific instances. Then you can do a check in code:

-
-
-if ( SecurityUtils.getSubject().isPermitted("printer:query:lp7200") {
-    // Return the current jobs on printer lp7200
-}
-
-
- -

This is an extremely powerful way to express permissions. But again, having to define multiple instance IDs for all printers does not scale well, particularly when new printers are added to the system. You can instead use a wildcard:

-
-
-printer:print:*
-
-
- -

This does scale, because it covers any new printers as well. You could even allow access to all actions on all printers:

-
-
-printer:*:*
-
-
- -

or all actions on a single printer:

-
-
-printer:*:lp7200
-
-
- -

or even specific actions:

-
-
-printer:query,print:lp7200
-
-
- -

The '*' wildcard and ',' sub-part separator can be used in any part of the permission.

- -

Missing Parts

- -

One final thing to note about permission assignments: missing parts imply that the user has access to all values corresponding to that part. In other words,

-
-
-printer:print
-
-
- -

is equivalent to

-
-
-printer:print:*
-
-
- -

and

-
-
-printer
-
-
- -

is equivalent to

-
-
-printer:*:*
-
-
- -

However, you can only leave off parts from the end of the string, so this:

-
-
-printer:lp7200
-
-
- -

is not equivalent to

-
-
-printer:*:lp7200
-
-
- -

Checking Permissions

- -

While permission assignments use the wildcard construct quite a bit ("printer:print:*" = print to any printer) for convenience and scalability, permission checks at runtime should always be based on the most specific permission string possible.

- -

For example, if the user had a UI and they wanted to print a document to the lp7200 printer, you should check if the user is permitted to do so by executing this code:
-

-
-
-if ( SecurityUtils.getSubject().isPermitted("printer:print:lp7200") ) {
-    //print the document to the lp7200 printer
-}
-
-
- -

That check is very specific and explicitly reflects what the user is attempting to do at that moment in time.

- - -

The following however is much less ideal for a runtime check:

-
-
-if ( SecurityUtils.getSubject().isPermitted("printer:print") ) {
-    //print the document
-}
-
-
- -

Why? Because the second example says "You must be able to print to any printer for the following code block to execute". But remember that "printer:print" is equivalent to "printer:print:*"!

- -

Therefore, this is an incorrect check. What if the current user does not have the ability to print to any printer, but they do have the ability to print to say, the lp7200 and epsoncolor printers. Then the 2nd example above would never allow them to print to the lp7200 printer even though they have been granted that ability!

- -

So the rule of thumb is to use the most specific permission string possible when performing permission checks. Of course, the 2nd block above might be a valid check somewhere else in the application if you really did only want to execute the code block if the user was allowed to print to any printer (suspect, but possible). Your application will determine what checks make sense, but in general, the more specific, the better.

- -

Implication, not Equality

- -

Why is it that runtime permission checks should be as specific as possible, but permission assignments can be a little more generic? It is because the permission checks are evaluated by implication logic - not equality checks.

- -

That is, if a user is assigned the user:* permission, this implies that the user can perform the user:view action. The string "user:*" is clearly not equal to "user:view", but the former implies the latter. "user:*" describes a superset of functionality of that defined by "user:view".

- -

To support implication rules, all permissions are translated in to object instances that implement the org.apache.shiro.authz.Permission interface. This is so that implication logic can be executed at runtime and that implication logic is often more complex than a simple string equality check. All of the wildcard behavior described in this document is actually made possible by the org.apache.shiro.authz.permission.WildcardPermission class implementation. Here are some more wildcard permission strings that show access by implication:

- -
-
-user:*
-
-
-

implies the ability to also delete a user:

-
-
-user:delete
-
-
- -

Similarly,

- -
-
-user:*:12345
-
-
-

implies the ability to also update user account with ID 12345:

-
-
-user:update:12345
-
-
- -

and

- -
-
-printer
-
-
-

implies the ability to print to any printer

-
-
-printer:print
-
-
- -

Performance Considerations

- -

Permission checks are more complex than a simple equals comparison, so runtime implication logic must execute for each assigned Permission. When using permission strings like the ones shown above, you're implicitly using Shiro's default WildcardPermission which executes the necessary implication logic.

- -

Shiro's default behavior for Realm implementations is that, for every permission check (for example, a call to subject.isPermitted ), all of the permissions assigned to that user (in their Groups, Roles, or directly assigned to them) need to be checked individually for implication. Shiro 'short circuits' this process by returning immediately after the first successful check occurs to increase performance, but it is not a silver bullet.

- -

This is usually extremely fast when users, roles and permissions are cached in memory when using a proper CacheManager, which Shiro does support for Realm implementations. Just know that with this default behavior, as the number of permissions assigned to a user or their roles or groups increase, the time to perform the check will necessarily increase.

- -

If a Realm implementor has a more efficient way of checking permissions and performing this implication logic, especially if based on the applicaton's data model, they should implement that as part of their Realm isPermitted* method implementations. The default Realm/WildcardPermission support exists to cover 80-90% of most use cases, but it might not be the best solution for applications that have massive amounts of permissions to store and/or check at runtime.

- -

Lend a hand with documentation

- -

While we hope this documentation helps you with the work you're doing with Apache Shiro, the community is improving and expanding the documentation all the time. If you'd like to help the Shiro project, please consider corrected, expanding, or adding documentation where you see a need. Every little bit of help you provide expands the community and in turn improves Shiro.

- -

The easiest way to contribute your documentation is to send it to the User Forum or the User Mailing List.

diff --git a/permissions.md b/permissions.md new file mode 100644 index 0000000000..13c0ee379d --- /dev/null +++ b/permissions.md @@ -0,0 +1,306 @@ +# Understanding Permissions in Apache Shiro + +
+ +
+

Related Content

+ +

Java Authorization Guide

+

Learn how Shiro handles access control in Java.
Read More >>

+ +

Web App Tutorial

+

Step-by-step tutorial for securing a web application with Shiro.
Read More >>

+ +

Getting Started

+

Resources, guides and tutorials for new Shiro users.
Read More >>

+ +

10-Minute Shiro Tutorial

+

Try Apache Shiro for yourself in under 10 minutes.
Read More >>

+ +
+ +
+ +Shiro defines a Permission as a statement that defines an explicit behavior or action. It is a statement of raw functionality in an application and nothing more. Permissions are the lowest-level constructs in security polices, and they explicitly define only "what" the application can do. + +They do _not_ at all describe "who" is able to perform the action(s). + +Some examples of permissions: + +* Open a file +* View the '/user/list' web page +* Print documents +* Delete the 'jsmith' user + +Defining "who" (users) is allowed to do "what" (permissions) is an exercise of assigning permissions to users in some way. This is always done by the application's data model and can vary greatly across applications. + +For example, permissions can be grouped in a Role and that Role could be associated with one or more User objects. Or some applications can have a Group of users and a Group can be assigned a Role, which by transitive association would mean that all the Users in that Group are implicitly granted the permissions in the Role. + +There are many variations for how permissions could be granted to users - the application determines how to model this based on the application requirements. + + +##Wildcard Permissions + +The above examples of permissions, "Open a file", "View the 'user/list' web page", etc are all valid permission statements. However, it would be very difficult computationally to interpret those natural language strings and determine if a user is allowed to perform that behavior or not. + +So to enable easy-to-process yet still readable permission statements, Shiro provides powerful and intuitive permission syntax we refer to as the WildcardPermission. + + +###Simple Usage + +Let's you want to protect access to your company's printers such that some people can print to particular printers, while others can query what jobs are currently in the queue. + +An extremely simple approach would be to use grant the user a "queryPrinter" permission. Then you could check to see if the user has the queryPrinter permission by calling: + +``` java +subject.isPermitted("queryPrinter") +``` + +This is (mostly) equivalent to + +``` java +subject.isPermitted( new WildcardPermission("queryPrinter") ) +``` + +but more on that later. + +The simple permission string may work for simple applications, but it requires you to have permissions like "printPrinter", "queryPrinter", "managePrinter", etc. You can also grant a user "*" permissions using the wildcard character (giving this permission construct its name), which means they have **_all_** permissions across _the entire application_. + +But using this approach there's no way to just say a user has "all printer permissions". For this reason, Wildcard Permissions supports multiple _levels_ of permissioning. + + +###Multiple Parts + +Wildcard Permissions support the concept of multiple _levels_ or _parts_. For example, you could restructure the previous simple example by granting a user the permission + +``` ini +printer:query +``` + +The colon in this example is a special character used to delimit the next part in the permission string. + +In this example, the first part is the domain that is being operated on (`printer`) and the second part is the action (`query`) being performed. The other above examples would be changed to: + +``` ini +printer:print +printer:manage +``` + +There is no limit to the number of parts that can be used, so it is up to your imagination in terms of ways that this could be used in your application. + + +####Multiple Values + +Each part can contain multiple values. So instead of granting the user both the "printer:print" and "printer:query" permissions, you could simply grant them one: + +``` ini +printer:print,query +``` + +which gives them the ability to `print` and `query` printers. And since they are granted both those actions, you could check to see if the user has the ability to query printers by calling: + +``` java +subject.isPermitted("printer:query") +``` + +which would return `true` + + +####All Values + +What if you wanted to grant a user _all_ values in a particular part? It would be more convenient to do this than to have to manually list every value. Again, based on the wildcard character, we can do this. If the `printer` domain had 3 possible actions (`query`, `print`, and `manage`), this: + +``` ini +printer:query,print,manage +``` + +simply becomes this: + +``` ini +printer:* +``` + +Then, _any_ permission check for "printer:XXX" will return `true`. Using the wildcard in this way scales better than explicitly listing actions since, if you added a new action to the application later, you don't need to update the permissions that use the wildcard character in that part. + +Finally, it is also possible to use the wildcard token in any part of a wildcard permission string. For example, if you wanted to grant a user the "view" action across _all_ domains (not just printers), you could grant this: + +``` ini +*:view +``` + +Then any permission check for "foo:view" would return `true` + + +###Instance-Level Access Control + +Another common usage of wildcard permissions is to model instance-level Access Control Lists. In this scenario you use three parts - the first is the _domain_, the second is the _action_(s), and the third is the instance(s) being acted upon. + +So for example you could have + +``` ini +printer:query:lp7200 +printer:print:epsoncolor +``` + +The first defines the behavior to `query` the `printer` with the ID `lp7200`. The second permission defines the behavior to `print` to the `printer` with ID `epsoncolor`. If you grant these permissions to users, then they can perform specific behavior on _specific instances_. Then you can do a check in code: + +``` java +if ( SecurityUtils.getSubject().isPermitted("printer:query:lp7200") { + // Return the current jobs on printer lp7200 } +} +``` + +This is an extremely powerful way to express permissions. But again, having to define multiple instance IDs for all printers does not scale well, particularly when new printers are added to the system. You can instead use a wildcard: + +``` ini +printer:print:* +``` + +This does scale, because it covers any new printers as well. You could even allow access to all actions on all printers: + +``` ini +printer:*:* +``` + +or all actions on a single printer: + +``` ini +printer:*:lp7200 +``` + +or even specific actions: + +``` ini +printer:query,print:lp7200 +``` + +The '*' wildcard and ',' sub-part separator can be used in any part of the permission. + + +####Missing Parts + +One final thing to note about permission assignments: missing parts imply that the user has access to all values corresponding to that part. In other words, + +``` ini +printer:print +``` + +is equivalent to + +``` ini +printer:print:* +``` + +and + +``` ini +printer +``` + +is equivalent to + +``` ini +printer:*:* +``` + +However, you can only leave off parts from the _end_ of the string, so this: + +``` ini +printer:lp7200 +``` + +is **_not_** equivalent to + +``` ini +printer:*:lp7200 +``` + + +##Checking Permissions + +While permission assignments use the wildcard construct quite a bit ("printer:print:*" = print to any printer) for convenience and scalability, permission **checks** at runtime should _always_ be based on the most specific permission string possible. + +For example, if the user had a UI and they wanted to print a document to the `lp7200` printer, you **should** check if the user is permitted to do so by executing this code: + +``` java +if ( SecurityUtils.getSubject().isPermitted("printer:print:lp7200") ) { + //print the document to the lp7200 printer } +} +``` + +That check is very specific and explicitly reflects what the user is attempting to do at that moment in time. + +The following however is much less ideal for a runtime check: + +```java +if ( SecurityUtils.getSubject().isPermitted("printer:print") ) { + //print the document } +} +``` + +Why? Because the second example says "You must be able to print to **any** printer for the following code block to execute". But remember that "printer:print" is equivalent to "printer:print:*"! + +Therefore, this is an incorrect check. What if the current user does not have the ability to print to any printer, but they **do** have the ability to print to say, the `lp7200` and `epsoncolor` printers. Then the 2nd example above would never allow them to print to the `lp7200` printer even though they have been granted that ability! + +So the rule of thumb is to use the most specific permission string possible when performing permission checks. Of course, the 2nd block above might be a valid check somewhere else in the application if you really did only want to execute the code block if the user was allowed to print to any printer (suspect, but possible). Your application will determine what checks make sense, but in general, the more specific, the better. + + +##Implication, not Equality + +Why is it that runtime permission checks should be as specific as possible, but permission assignments can be a little more generic? It is because the permission checks are evaluated by _implication_ logic - not equality checks. + +That is, if a user is assigned the `user:*` permission, this _implies_ that the user can perform the `user:view` action. The string "user:*" is clearly not equal to "user:view", but the former implies the latter. "user:*" describes a superset of functionality of that defined by "user:view". + +To support implication rules, all permissions are translated in to object instances that implement the `org.apache.shiro.authz.Permission` interface. This is so that implication logic can be executed at runtime and that implication logic is often more complex than a simple string equality check. All of the wildcard behavior described in this document is actually made possible by the `org.apache.shiro.authz.permission.WildcardPermission` class implementation. Here are some more wildcard permission strings that show access by implication: + +``` ini +user:* +``` + +_implies_ the ability to also delete a user: + +``` ini +user:delete +``` + +Similarly, + +``` ini +user:*:12345 +``` + +_implies_ the ability to also update user account with ID 12345: + +``` ini +user:update:12345 +``` + +and + +``` ini +printer +``` + +_implies_ the ability to print to any printer + +``` ini +printer:print +``` + + +##Performance Considerations + +Permission checks are more complex than a simple equals comparison, so runtime implication logic must execute for each assigned Permission. When using permission strings like the ones shown above, you're implicitly using Shiro's default `WildcardPermission` which executes the necessary implication logic. + +Shiro's default behavior for Realm implementations is that, for every permission check (for example, a call to `subject.isPermitted`), _all_ of the permissions assigned to that user (in their Groups, Roles, or directly assigned to them) need to be checked individually for implication. Shiro 'short circuits' this process by returning immediately after the first successful check occurs to increase performance, but it is not a silver bullet. + +This is usually extremely fast when users, roles and permissions are cached in memory when using a proper [CacheManager](cachemanager.html "CacheManager"), which Shiro does support for Realm implementations. Just know that with this default behavior, as the number of permissions assigned to a user or their roles or groups increase, the time to perform the check will necessarily increase. + +If a Realm implementor has a more efficient way of checking permissions and performing this implication logic, especially if based on the applicaton's data model, they should implement that as part of their Realm isPermitted* method implementations. The default Realm/WildcardPermission support exists to cover 80-90% of most use cases, but it might not be the best solution for applications that have massive amounts of permissions to store and/or check at runtime. + + +##Lend a hand with documentation + +While we hope this documentation helps you with the work you're doing with Apache Shiro, the community is improving and expanding the documentation all the time. If you'd like to help the Shiro project, please consider corrected, expanding, or adding documentation where you see a need. Every little bit of help you provide expands the community and in turn improves Shiro. + +The easiest way to contribute your documentation is to send it to the [User Forum](http://shiro-user.582556.n2.nabble.com/) or the [User Mailing List](mailing-lists.html "Mailing Lists").