shiro-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From lhazlew...@apache.org
Subject svn commit: r1481417 [5/13] - in /shiro/site: ./ 2010/ 2011/ 2012/ assets/ templates/ trunk/ trunk/2010/ trunk/2010/03/ trunk/2010/03/18/ trunk/2010/06/ trunk/2010/06/01/ trunk/2010/09/ trunk/2010/09/14/ trunk/2010/09/20/ trunk/2010/09/24/ trunk/2010/1...
Date Sat, 11 May 2013 21:10:45 GMT
Added: shiro/site/trunk/cas.html
URL: http://svn.apache.org/viewvc/shiro/site/trunk/cas.html?rev=1481417&view=auto
==============================================================================
--- shiro/site/trunk/cas.html (added)
+++ shiro/site/trunk/cas.html Sat May 11 21:10:40 2013
@@ -0,0 +1,161 @@
+<h1><a name="CAS-IntegratingApacheShirowithCASSSOserver"></a>Integrating Apache Shiro with CAS SSO server</h1>
+
+<p>The <em>shiro-cas</em> module is made to protect a web application with a <a class="external-link" href="http://www.jasig.org/cas" rel="nofollow">Jasig CAS</a> SSO server. It enables a Shiro-enabled application to be a CAS client.</p>
+
+<h2><a name="CAS-BasicunderstandingoftheCASprotocol"></a>Basic understanding of the CAS protocol</h2>
+
+<p>1. If you want to access an application protected by a CAS client and if you are not authenticated in this application, you are redirected by the CAS client to the CAS server login page. A service parameter in the CAS login url defines the application the user wants to login.</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">http:<span class="code-comment">//application.examples.com/<span class="code-keyword">protected</span>/index.jsp &#8594; HTTP 302
+</span>&#8594; https:<span class="code-comment">//server.cas.com/login?service=http://application.examples.com/shiro-cas</span></pre>
+</div></div>
+
+<p>2. You fill the login and password and authenticate in CAS server which then redirects the user to the application (the service url) with a service ticket in url. The service ticket is a short-lived one-time-use token redeemable at the CAS server for a user identifier (and optionally, user attributes).</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">https:<span class="code-comment">//server.cas.com/login?service=http://application.examples.com/shiro-cas &#8594; HTTP 302
+</span>&#8594; http:<span class="code-comment">//application.examples.com/shiro-cas?ticket=ST-4545454542121-cas</span></pre>
+</div></div>
+
+<p>3. The application asks directly the CAS server if the service ticket is valid and the CAS server responds by the identity of the authenticated user. Generally, the CAS client forwards the user to the originally called protected page.</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">http:<span class="code-comment">//application.examples.com/shiro-cas?ticket=ST-4545454542121-cas &#8594; HTTP 302
+</span>&#8594; http:<span class="code-comment">//application.examples.com/<span class="code-keyword">protected</span>/index.jsp</span></pre>
+</div></div>
+
+
+<h2><a name="CAS-HowtoconfigureshirotoworkwithCASserver%3F"></a>How to configure shiro to work with CAS server ?</h2>
+
+<h3><a name="CAS-Dependency"></a>Dependency</h3>
+
+<p>You need to add the <em>shiro-cas</em> Maven dependency in your application :</p>
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-xml">
+<span class="code-tag">&lt;dependency&gt;</span>
+    <span class="code-tag">&lt;groupId&gt;</span>org.apache.shiro<span class="code-tag">&lt;/groupId&gt;</span>
+    <span class="code-tag">&lt;artifactId&gt;</span>shiro-cas<span class="code-tag">&lt;/artifactId&gt;</span>
+    <span class="code-tag">&lt;version&gt;</span>version<span class="code-tag">&lt;/version&gt;</span>
+<span class="code-tag">&lt;/dependency&gt;</span></pre>
+</div></div>
+<p>(<em>version</em> &gt;= 1.2.0).</p>
+
+<h3><a name="CAS-CasFilter"></a>CasFilter</h3>
+
+<p>You have to define the service url of your application (which has to be declared also in the CAS server). This url will be used to receive CAS service ticket. For example&#160;: <a class="external-link" href="http://application.examples.com/shiro-cas" rel="nofollow">http://application.examples.com/shiro-cas</a></p>
+
+<p>In your shiro configuration, you have to define the <tt>CasFilter</tt>&#160;:</p>
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">[main]
+casFilter = org.apache.shiro.cas.CasFilter
+casFilter.failureUrl = /error.jsp</pre>
+</div></div>
+<p>(the failure url is called when the service ticket validation fails).</p>
+
+<p>And the url on which it is available&#160;:</p>
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">[urls]
+/shiro-cas = casFilter</pre>
+</div></div>
+
+<p>This way, when the user is redirected to the application service url (<em>/shiro-cas</em>) by the CAS server with a valid service ticket (after authentication), this filter receives the service ticket and creates a <tt>CasToken</tt> which can be used by the <tt>CasRealm</tt>.</p>
+
+<h3><a name="CAS-CasRealm"></a>CasRealm</h3>
+
+<p>The <tt>CasRealm</tt> uses the <tt>CasToken</tt> created by the <tt>CasFilter</tt> to authenticate the user by validating the CAS service ticket against the CAS server.</p>
+
+<p>In your shiro configuration, you have to add the <tt>CasRealm</tt>&#160;:</p>
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">[main]
+casRealm = org.apache.shiro.cas.CasRealm
+casRealm.defaultRoles = ROLE_USER
+#casRealm.defaultPermissions
+#casRealm.roleAttributeNames
+#casRealm.permissionAttributeNames
+#casRealm.validationProtocol = SAML
+casRealm.casServerUrlPrefix =&#160;https:<span class="code-comment">//server.cas.com/
+</span>casRealm.casService =&#160;http:<span class="code-comment">//application.examples.com/shiro-cas</span></pre>
+</div></div>
+
+<p>The <em>casServerUrlPrefix</em> is the url of the CAS server (for example&#160;: <a class="external-link" href="https://server.cas.com" rel="nofollow">https://server.cas.com</a>).<br clear="none">
+The <em>casService</em> is the application service url, the url on wich the application receives CAS service ticket (for example&#160;: <a class="external-link" href="http://application.examples.com/shiro-cas" rel="nofollow">http://application.examples.com/shiro-cas</a>).<br clear="none">
+The <em>validationProcol</em> can be SAML or CAS (default)&#160;: attributes and remember me information are only pushed throught the SAML validation procotol (except specific customizations). It depends on the version of the CAS server&#160;: SAML protocol can be used with CAS server version &gt;= 3.1.</p>
+<div class="panelMacro"><table class="warningMacro"><colgroup span="1"><col span="1" width="24"><col span="1"></colgroup><tr><td colspan="1" rowspan="1" valign="top"><img align="middle" src="https://cwiki.apache.org/confluence/images/icons/emoticons/forbidden.gif" width="16" height="16" alt="" border="0"></td><td colspan="1" rowspan="1">If you choose SAML validation, you need some more specific dependencies :</td></tr></table></div>
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-xml">
+<span class="code-tag">&lt;dependency&gt;</span>
+    <span class="code-tag">&lt;groupId&gt;</span>commons-codec<span class="code-tag">&lt;/groupId&gt;</span>
+    <span class="code-tag">&lt;artifactId&gt;</span>commons-codec<span class="code-tag">&lt;/artifactId&gt;</span>
+<span class="code-tag">&lt;/dependency&gt;</span>
+<span class="code-tag">&lt;dependency&gt;</span>
+    <span class="code-tag">&lt;groupId&gt;</span>org.opensaml<span class="code-tag">&lt;/groupId&gt;</span>
+    <span class="code-tag">&lt;artifactId&gt;</span>opensaml<span class="code-tag">&lt;/artifactId&gt;</span>
+    <span class="code-tag">&lt;version&gt;</span>1.1<span class="code-tag">&lt;/version&gt;</span>
+<span class="code-tag">&lt;/dependency&gt;</span>
+<span class="code-tag">&lt;dependency&gt;</span>
+    <span class="code-tag">&lt;groupId&gt;</span>org.apache.santuario<span class="code-tag">&lt;/groupId&gt;</span>
+    <span class="code-tag">&lt;artifactId&gt;</span>xmlsec<span class="code-tag">&lt;/artifactId&gt;</span>
+    <span class="code-tag">&lt;version&gt;</span>1.4.3<span class="code-tag">&lt;/version&gt;</span>
+<span class="code-tag">&lt;/dependency&gt;</span></pre>
+</div></div>
+<p>The <em>defaultRoles</em> is the default roles given to the authenticated user after CAS authentication success.<br clear="none">
+The <em>defaultPermissions</em> is the default permissions given to the authenticated user after CAS authentication success.<br clear="none">
+The <em>roleAttributeNames</em> defines the names of the attributes received from CAS response which define roles to give to the authenticated user (the roles are separated by comas).<br clear="none">
+The <em>permissionAttributeNames</em> defines the names of the attributes received from CAS response which define permissions to give to the authenticated user (the permissions are separated by comas).</p>
+
+<h3><a name="CAS-CasSubjectFactory"></a>CasSubjectFactory</h3>
+
+<p>In CAS server, you can have "remember me" support. This information is pushed through SAML validation or CAS customized validation.<br clear="none">
+To reflect the CAS-remember me status in Shiro, you have to define a specific <tt>CasSubjectFactory</tt> in your Shiro configuration :</p>
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">[main]
+casSubjectFactory = org.apache.shiro.cas.CasSubjectFactory
+securityManager.subjectFactory = $casSubjectFactory</pre>
+</div></div>
+
+<h3><a name="CAS-Security%C2%A0oftheapplication"></a>Security&#160;of the application</h3>
+
+<p>Finally, you have to define the security of your application.</p>
+
+<p>In your Shiro configuration, you have to protect url with roles&#160;(for example) :</p>
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">[urls]
+/<span class="code-keyword">protected</span>/** = roles[ROLE_USER]
+/** = anon</pre>
+</div></div>
+
+<p>And the login url if the user is not authenticated is to be defined on the CAS server with the application service url&#160;:</p>
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">[main]
+roles.loginUrl = https:<span class="code-comment">//server.cas.com/login?service=http://application.examples.com/shiro-cas</span></pre>
+</div></div>
+
+<p>This way, if you are not authenticated and try to acces a <em>/protected/**</em> url, you are redirected to the CAS server for authentication.</p>
+
+<h3><a name="CAS-Completeconfigurationsample"></a>Complete configuration sample</h3>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">[main]
+casFilter = org.apache.shiro.cas.CasFilter
+casFilter.failureUrl = /error.jsp
+
+casRealm = org.apache.shiro.cas.CasRealm
+casRealm.defaultRoles = ROLE_USER
+casRealm.casServerUrlPrefix =&#160;https:<span class="code-comment">//server.cas.com/
+</span>casRealm.casService =&#160;http:<span class="code-comment">//application.examples.com/shiro-cas
+</span>
+casSubjectFactory = org.apache.shiro.cas.CasSubjectFactory
+securityManager.subjectFactory = $casSubjectFactory
+
+roles.loginUrl = https:<span class="code-comment">//server.cas.com/login?service=http://application.examples.com/shiro-cas
+</span>
+[urls]
+/shiro-cas = casFilter
+/<span class="code-keyword">protected</span>/** = roles[ROLE_USER]
+/** = anon</pre>
+</div></div>
+
+<h2><a name="CAS-History"></a>History</h2>
+
+<p><em>Version 1.2.0</em>&#160;: first release of the <em>shiro-cas</em> module.</p>
\ No newline at end of file

Added: shiro/site/trunk/codec.html
URL: http://svn.apache.org/viewvc/shiro/site/trunk/codec.html?rev=1481417&view=auto
==============================================================================
--- shiro/site/trunk/codec.html (added)
+++ shiro/site/trunk/codec.html Sat May 11 21:10:40 2013
@@ -0,0 +1,7 @@
+<p>TODO</p>
+
+<h2><a name="Codec-Lendahandwithdocumentation"></a>Lend a hand with documentation </h2>
+
+<p>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. </p>
+
+<p>The easiest way to contribute your documentation is to send it to the <a class="external-link" href="http://shiro-user.582556.n2.nabble.com/" rel="nofollow">User Forum</a> or the <a href="mailing-lists.html" title="Mailing Lists">User Mailing List</a>.</p>
\ No newline at end of file

Added: shiro/site/trunk/command-line-hasher.html
URL: http://svn.apache.org/viewvc/shiro/site/trunk/command-line-hasher.html?rev=1481417&view=auto
==============================================================================
--- shiro/site/trunk/command-line-hasher.html (added)
+++ shiro/site/trunk/command-line-hasher.html Sat May 11 21:10:40 2013
@@ -0,0 +1,99 @@
+<h1><a name="CommandLineHasher-CommandLineHasher"></a>Command Line Hasher</h1>
+
+<div class="toc">
+<ul><li><a href="#CommandLineHasher-Usage">Usage</a></li><li><a href="#CommandLineHasher-CommonScenarios">Common Scenarios</a></li><ul><li><a href="#CommandLineHasher-%7B%7Bshiro.ini%7D%7DUserPasswords"> <tt>shiro.ini</tt> User Passwords</a></li><li><a href="#CommandLineHasher-MD5checksum">MD5 checksum</a></li></ul></ul></div>
+
+<p>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 <tt>$PATH</tt> environment variable.</p>
+
+<h2><a name="CommandLineHasher-Usage"></a>Usage</h2>
+
+<p>Ensure you have access to the <tt>shiro-tools-hasher-</tt><em>version</em><tt>-cli.jar</tt> file.  You can either find this in a source build in the <em>buildroot</em><tt>/tools/hasher/target</tt> directory or via download through Maven.</p>
+
+<p>Once you have access to the jar, you can run the following command:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+&gt; java -jar shiro-tools-hasher-X.X.X-cli.jar
+</pre>
+</div></div>
+
+<p>This will print all available options for both standard (MD5, SHA1) and more complex password hashing scenarios.</p>
+
+<h2><a name="CommandLineHasher-CommonScenarios"></a>Common Scenarios</h2>
+
+<p>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.</p>
+
+<h3><a name="CommandLineHasher-%7B%7Bshiro.ini%7D%7DUserPasswords"></a><tt>shiro.ini</tt> User Passwords</h3>
+
+<p>It is best to keep user passwords in the <tt>shiro.ini</tt> <tt>[users]</tt> section secure.  To add a new user account line, use the above command with the <tt><b>-p</b></tt> (or <tt>--password</tt>) option:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+&gt; java -jar shiro-tools-hasher-X.X.X-cli.jar -p
+</pre>
+</div></div>
+
+<p>It will then ask you to enter the password and then confirm it:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+Password to hash:
+Password to hash (confirm):
+</pre>
+</div></div>
+
+<p>When this command executes, it will print out the securely-salted-iterated-and-hashed password.  For example:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+$shiro1$SHA-256$500000$eWpVX2tGX7WCP2J+jMCNqw==$it/NRclMOHrfOvhAEFZ0mxIZRdbcfqIBdwdwdDXW2dM=
+</pre>
+</div></div>
+
+<p>Take this value and place it as the password in the user definition line (followed by any optional roles) as defined in the <a href="configuration.html#Configuration-%5Cusers%5C">INI Users Configuration</a> documentation.  For example:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+[users]
+...
+user1 = $shiro1$SHA-256$500000$eWpVX2tGX7WCP2J+jMCNqw==$it/NRclMOHrfOvhAEFZ0mxIZRdbcfqIBdwdwdDXW2dM=
+</pre>
+</div></div>
+
+<p>You will also need to ensure that the implicit <tt>iniRealm</tt> uses a <tt>CredentialsMatcher</tt> that knows how to perform secure hashed password comparisons.  So configure this in the <tt>[main]</tt> section as well:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+[main]
+...
+passwordMatcher = org.apache.shiro.authc.credential.PasswordMatcher
+iniRealm.credentialsMatcher = $passwordMatcher
+...
+</pre>
+</div></div>
+
+
+<h3><a name="CommandLineHasher-MD5checksum"></a>MD5 checksum</h3>
+
+<p>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 <tt><b>-r</b></tt> (or <tt>--resource</tt>) option to indicate the following value is a resource location (and not text you wish hashed):</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+&gt; java -jar shiro-tools-hasher-X.X.X-cli.jar -r RESOURCE_PATH
+</pre>
+</div></div>
+
+<p>By default <tt>RESOURCE_PATH</tt> is expected to be a file path, but you may specify classpath or URL resources by using the <tt>classpath:</tt> or <tt>url:</tt> prefix respectively.</p>
+
+<p>Some examples:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+&lt;command&gt; -r fileInCurrentDirectory.txt
+&lt;command&gt; -r ../../relativePathFile.xml
+&lt;command&gt; -r ~/documents/myfile.pdf
+&lt;command&gt; -r /usr/local/logs/absolutePathFile.log
+&lt;command&gt; -r url:http:<span class="code-comment">//foo.com/page.html
+</span>&lt;command&gt; -r classpath:/WEB-INF/lib/something.jar
+</pre>
+</div></div>
\ No newline at end of file

Added: shiro/site/trunk/commercial-support.html
URL: http://svn.apache.org/viewvc/shiro/site/trunk/commercial-support.html?rev=1481417&view=auto
==============================================================================
--- shiro/site/trunk/commercial-support.html (added)
+++ shiro/site/trunk/commercial-support.html Sat May 11 21:10:40 2013
@@ -0,0 +1,5 @@
+<h1><a name="CommercialSupport-CommercialSupportandConsultingforApacheShiro"></a>Commercial Support and Consulting for Apache Shiro</h1>
+
+<p>Shiro commercial support and consulting services are available from Stormpath, a company started by Shiro author and project chair, Les Hazlewood:</p>
+
+<p><a class="external-link" href="http://www.stormpath.com/apache-shiro-support" rel="nofollow">http://www.stormpath.com/apache-shiro-support</a></p>
\ No newline at end of file

Added: shiro/site/trunk/community.html
URL: http://svn.apache.org/viewvc/shiro/site/trunk/community.html?rev=1481417&view=auto
==============================================================================
--- shiro/site/trunk/community.html (added)
+++ shiro/site/trunk/community.html Sat May 11 21:10:40 2013
@@ -0,0 +1,21 @@
+<h1><a name="Community-ApacheShiroCommunity"></a>Apache Shiro Community</h1>
+
+<p>Welcome to the Apache Shiro Community!  We have a great user and developer community and hope that you become an active participant.</p>
+
+<p>Our community is here to help you learn about Shiro, figure out how to do what you need, identify and fix any bugs, and improve Shiro so that it continues to be a powerful and useful software project.</p>
+
+<p>Below are some helpful links related to the Shiro Community.</p>
+
+<ul><li><b><a href="how-to-contribute.html" title="How to Contribute">How to Contribute</a></b> - Join our community and help make Apache Shiro even better</li></ul>
+
+
+<ul><li><b><a href="news.html" title="News">News</a></b> - Stay up to date on the latest Shiro news</li></ul>
+
+
+<ul><li><b><a href="events.html" title="Events">Events</a></b> - Check out the next Shiro events and see if there's something near you to attend</li></ul>
+
+
+<ul><li><b><a href="articles.html" title="Articles">Articles</a></b> - Read up on the latest discussions, guides, and how-tos created by members of our community</li></ul>
+
+
+<ul><li><b><a href="developer-resources.html" title="Developer Resources">Developer Resources</a></b> - Information for the Apache Shiro Development team performing tasks as a committer or contributor</li></ul>

Added: shiro/site/trunk/concurrency.md
URL: http://svn.apache.org/viewvc/shiro/site/trunk/concurrency.md?rev=1481417&view=auto
==============================================================================
--- shiro/site/trunk/concurrency.md (added)
+++ shiro/site/trunk/concurrency.md Sat May 11 21:10:40 2013
@@ -0,0 +1 @@
+TBD
\ No newline at end of file

Added: shiro/site/trunk/conferences.md
URL: http://svn.apache.org/viewvc/shiro/site/trunk/conferences.md?rev=1481417&view=auto
==============================================================================
--- shiro/site/trunk/conferences.md (added)
+++ shiro/site/trunk/conferences.md Sat May 11 21:10:40 2013
@@ -0,0 +1 @@
+If Shiro is presented at any conferences, we'll update this page with details.
\ No newline at end of file

Added: shiro/site/trunk/config.scms.groovy
URL: http://svn.apache.org/viewvc/shiro/site/trunk/config.scms.groovy?rev=1481417&view=auto
==============================================================================
--- shiro/site/trunk/config.scms.groovy (added)
+++ shiro/site/trunk/config.scms.groovy Sat May 11 21:10:40 2013
@@ -0,0 +1,24 @@
+scms {
+
+    excludes = ['templates/**', '.svn', '.git', '.gitignore', '**/*.iml', '**/*.ipr', '**/*.iws']
+
+    patterns {
+
+        '**/*.html' {
+            template = 'templates/default.vtl'
+            model {
+                //the above template uses the year for a copyright notice:
+                year = Calendar.getInstance().get(Calendar.YEAR)
+            }
+        }
+
+        '**/*.md' {
+            template = 'templates/default.vtl'
+            model {
+                //the above template uses the year for a copyright notice:
+                year = Calendar.getInstance().get(Calendar.YEAR)
+            }
+        }
+    }
+
+}
\ No newline at end of file

Added: shiro/site/trunk/configuration.html
URL: http://svn.apache.org/viewvc/shiro/site/trunk/configuration.html?rev=1481417&view=auto
==============================================================================
--- shiro/site/trunk/configuration.html (added)
+++ shiro/site/trunk/configuration.html Sat May 11 21:10:40 2013
@@ -0,0 +1,476 @@
+<h1><a name="Configuration-ApacheShiroConfiguration"></a>Apache Shiro Configuration</h1>
+
+<div class="toc">
+<ul><li><a href="#Configuration-ProgrammaticConfiguration">Programmatic Configuration</a></li><ul><li><a href="#Configuration-SecurityManagerObjectGraph">SecurityManager Object Graph</a></li></ul><li><a href="#Configuration-INIConfiguration">INI Configuration</a></li><ul><li><a href="#Configuration-CreatingaSecurityManagerfromINI">Creating a SecurityManager from INI</a></li><ul><li><a href="#Configuration-SecurityManagerfromanINIresource">SecurityManager from an INI resource</a></li><li><a href="#Configuration-SecurityManagerfromanINIinstance">SecurityManager from an INI instance</a></li></ul><li><a href="#Configuration-INISections">INI Sections</a></li><ul><li><a href="#Configuration-%5Cmain%5C">[main]</a></li><ul><li><a href="#Configuration-Defininganobject">Defining an object</a></li><li><a href="#Configuration-Settingobjectproperties">Setting object properties</a></li><ul><li><a href="#Configuration-PrimitiveValues">Primitive Values</a></li><li><a href="#Configuration-Re
 ferenceValues">Reference Values</a></li><li><a href="#Configuration-NestedProperties">Nested Properties</a></li><li><a href="#Configuration-ByteArrayValues">Byte Array Values</a></li><li><a href="#Configuration-CollectionProperties">Collection Properties</a></li></ul><li><a href="#Configuration-Considerations">Considerations</a></li><ul><li><a href="#Configuration-OrderMatters">Order Matters</a></li><li><a href="#Configuration-OverridingInstances">Overriding Instances</a></li><li><a href="#Configuration-DefaultSecurityManager">Default SecurityManager</a></li></ul></ul><li><a href="#Configuration-%5Cusers%5C">[users]</a></li><ul><li><a href="#Configuration-LineFormat">Line Format</a></li><li><a href="#Configuration-EncryptingPasswords">Encrypting Passwords</a></li></ul><li><a href="#Configuration-%5Croles%5C">[roles]</a></li><ul><li><a href="#Configuration-LineFormat">Line Format</a></li></ul><li><a href="#Configuration-%5Curls%5C">[urls]</a></li></ul></ul><li><a href="#Confi
 guration-Lendahandwithdocumentation">Lend a hand with documentation</a></li></ul></div>
+
+<p>Shiro is designed to work in any environment, from simple command-line applications to the largest enterprise clustered applications.  Because of this diversity of environments, there are a number of configuration mechanisms that are suitable for configuration.  This section covers the configuration mechanisms that are supported by Shiro core only.</p>
+
+<div class="panelMacro"><table class="tipMacro"><colgroup span="1"><col span="1" width="24"><col span="1"></colgroup><tr><td colspan="1" rowspan="1" valign="top"><img align="middle" src="https://cwiki.apache.org/confluence/images/icons/emoticons/check.gif" width="16" height="16" alt="" border="0"></td><td colspan="1" rowspan="1"><b>Many Configuration Options</b><br clear="none">Shiro's <tt>SecurityManager</tt> implementations and all supporting components are all JavaBeans compatible.  This allows Shiro to be configured with practically any configuration format such as regular Java, XML (Spring, JBoss, Guice, etc), <a class="external-link" href="http://www.yaml.org/" rel="nofollow">YAML</a>, JSON, Groovy Builder markup, and more.</td></tr></table></div>
+
+<h2><a name="Configuration-ProgrammaticConfiguration"></a>Programmatic Configuration</h2>
+
+<p>The absolute simplest way to create a SecurityManager and make it available to the application is to create an <tt>org.apache.shiro.mgt.DefaultSecurityManager</tt> and wire it up in code.  For example:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+Realm realm = <span class="code-comment">//instantiate or acquire a Realm instance.  We'll discuss Realms later.
+</span>
+<span class="code-object">SecurityManager</span> securityManager = <span class="code-keyword">new</span> DefaultSecurityManager(realm);
+
+<span class="code-comment">//Make the <span class="code-object">SecurityManager</span> instance available to the entire application via <span class="code-keyword">static</span> memory:
+</span>SecurityUtils.setSecurityManager(securityManager);
+</pre>
+</div></div>
+
+<p>Surprisingly, after only 3 lines of code, you now have a fully functional Shiro environment suitable for many applications.  How easy was that!?</p>
+
+<h3><a name="Configuration-SecurityManagerObjectGraph"></a>SecurityManager Object Graph</h3>
+
+<p>As discussed in the <a href="architecture.html" title="Architecture">Architecture</a> chapter, Shiro's <tt>SecurityManager</tt> implementations are essentially a modular object graph of nested security-specific components.  Because they are also JavaBeans-compatible, you can call any of the nested components <tt>getter</tt> and <tt>setter</tt> methods to configure the <tt>SecurityManager</tt> and its internal object graph.</p>
+
+<p>For example, if you wanted to configure the <tt>SecurityManager</tt> instance to use a custom <tt>SessionDAO</tt> to customize <a href="session-management.html" title="Session Management">Session Management</a>, you could set the <tt>SessionDAO</tt> directly with the nested SessionManager's <tt>setSessionDAO</tt> method:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+...
+
+DefaultSecurityManager securityManager = <span class="code-keyword">new</span> DefaultSecurityManager(realm);
+
+SessionDAO sessionDAO = <span class="code-keyword">new</span> CustomSessionDAO();
+
+((DefaultSessionManager)securityManager.getSessionManager()).setSessionDAO(sessionDAO);
+...
+</pre>
+</div></div>
+
+<p>Using direct method invocations, you can configure any part of the <tt>SecurityManager</tt>'s object graph.</p>
+
+<p>But, as simple as programmatic customization is, it does not represent the ideal configuration for most real world applications.  There are a few reasons why programmatic configuration may not be suitable for your application:</p>
+
+<ul><li>It requires you to know about and instantiate a direct implementation.  It would be nicer if you didn't have to know about concrete implementations and where to find them.
+<br clear="none" class="atl-forced-newline">
+<br clear="none" class="atl-forced-newline"></li><li>Because of Java's type-safe nature, you're required to cast objects obtained via <tt>get*</tt> methods to their specific implementation.  So much casting is ugly, verbose, and tightly-couples you to implementation classes.
+<br clear="none" class="atl-forced-newline">
+<br clear="none" class="atl-forced-newline"></li><li>The <tt>SecurityUtils.setSecurityManager</tt> method call makes the instantiated <tt>SecurityManager</tt> instance a VM static singleton, which, while fine for many applications, would cause problems if more than one Shiro-enabled application was running on the same JVM.  It could be better if the instance was an application singleton, but not a static memory reference.
+<br clear="none" class="atl-forced-newline">
+<br clear="none" class="atl-forced-newline"></li><li>It requires you to recompile your application every time you want to make a Shiro configuration change.</li></ul>
+
+
+<p>However, even with these caveats, the direct programmatic manipulation approach could still be valuable in memory-constrained environments, like smart-phone applications.  If your application does not run in a memory-constrained environment, you'll find text-based configuration to be easier to use and read.</p>
+
+<h2><a name="Configuration-INIConfiguration"></a>INI Configuration</h2>
+
+<p>Most applications instead benefit from text-based configuration that could be modified independently of source code and even make things easier to understand for those not intimately familiar with Shiro's APIs.</p>
+
+<p>To ensure a common-denominator text-based configuration mechanism that can work in all environments with minimal 3rd party dependencies, Shiro supports the <a class="external-link" href="http://en.wikipedia.org/wiki/INI_file" rel="nofollow">INI format</a> to build the <tt>SecurityManager</tt> object graph and its supporting components.  INI is easy to read, easy to configure, and is simple to set-up and suits most applications well.</p>
+
+<h3><a name="Configuration-CreatingaSecurityManagerfromINI"></a>Creating a SecurityManager from INI</h3>
+
+<p>Here are two examples of how to build a SecurityManager based on INI configuration.</p>
+
+<h4><a name="Configuration-SecurityManagerfromanINIresource"></a>SecurityManager from an INI resource</h4>
+
+<p>We can create the SecurityManager instance from an INI resource path.  Resources can be acquired from the file system, classpath, or URLs when prefixed with <tt>file:</tt>, <tt>classpath:</tt>, or <tt>url:</tt> respectively.  This example uses a <tt>Factory</tt> to ingest a <tt>shiro.ini</tt> file from the root of the classpath and return the <tt>SecurityManager</tt> instance:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+<span class="code-keyword">import</span> org.apache.shiro.SecurityUtils;
+<span class="code-keyword">import</span> org.apache.shiro.util.Factory;
+<span class="code-keyword">import</span> org.apache.shiro.mgt.<span class="code-object">SecurityManager</span>;
+<span class="code-keyword">import</span> org.apache.shiro.config.IniSecurityManagerFactory;
+
+...
+
+Factory&lt;<span class="code-object">SecurityManager</span>&gt; factory = <span class="code-keyword">new</span> IniSecurityManagerFactory(<span class="code-quote">"classpath:shiro.ini"</span>);
+<span class="code-object">SecurityManager</span> securityManager = factory.getInstance();
+SecurityUtils.setSecurityManager(securityManager);
+</pre>
+</div></div>
+
+<h4><a name="Configuration-SecurityManagerfromanINIinstance"></a>SecurityManager from an INI instance</h4>
+
+<p>The INI configuration can be constructed programmatically as well if desired via the <tt><a class="external-link" href="static/current/apidocs/org/apache/shiro/config/Ini.html">org.apache.shiro.config.Ini</a></tt> class.  The Ini class functions similarly to the JDK <tt><a class="external-link" href="http://download.oracle.com/javase/6/docs/api/java/util/Properties.html" rel="nofollow">java.util.Properties</a></tt> class, but additionally supports segmentation by section name.  </p>
+
+<p>For example:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+<span class="code-keyword">import</span> org.apache.shiro.SecurityUtils;
+<span class="code-keyword">import</span> org.apache.shiro.util.Factory;
+<span class="code-keyword">import</span> org.apache.shiro.mgt.<span class="code-object">SecurityManager</span>;
+<span class="code-keyword">import</span> org.apache.shiro.config.Ini;
+<span class="code-keyword">import</span> org.apache.shiro.config.IniSecurityManagerFactory;
+
+...
+
+Ini ini = <span class="code-keyword">new</span> Ini();
+<span class="code-comment">//populate the Ini instance as necessary
+</span>...
+Factory&lt;<span class="code-object">SecurityManager</span>&gt; factory = <span class="code-keyword">new</span> IniSecurityManagerFactory(ini);
+<span class="code-object">SecurityManager</span> securityManager = factory.getInstance();
+SecurityUtils.setSecurityManager(securityManager);
+</pre>
+</div></div>
+
+<p>Now that we know how to construct a <tt>SecurityManager</tt> from INI configuration, let's take a look at exactly how to define a Shiro INI configuration.</p>
+
+<h3><a name="Configuration-INISections"></a>INI Sections</h3>
+
+<p>INI is basically a text configuration consisting of key/value pairs organized by uniquely-named sections.  Keys are unique per section only, not over the entire configuration (unlike the JDK  <a class="external-link" href="http://java.sun.com/javase/6/docs/api/java/util/Properties.html" rel="nofollow">Properties</a>).  Each section may be viewed like a single <tt>Properties</tt> definition however.</p>
+
+<p>Commented lines can start with either with an Octothorpe (# - aka the 'hash', 'pound' or 'number' sign) or a Semi-colon (';')</p>
+
+<p>Here is an example of the sections understood by Shiro:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+# =======================
+# Shiro INI configuration
+# =======================
+
+[main]
+# Objects and their properties are defined here, 
+# Such as the securityManager, Realms and anything
+# <span class="code-keyword">else</span> needed to build the <span class="code-object">SecurityManager</span>
+
+[users]
+# The 'users' section is <span class="code-keyword">for</span> simple deployments
+# when you only need a small number of statically-defined 
+# set of User accounts.
+
+[roles]
+# The 'roles' section is <span class="code-keyword">for</span> simple deployments
+# when you only need a small number of statically-defined
+# roles.
+
+[urls]
+# The 'urls' section is used <span class="code-keyword">for</span> url-based security
+# in web applications.  We'll discuss <span class="code-keyword">this</span> section in the
+# Web documentation
+</pre>
+</div></div>
+
+<h4><a name="Configuration-%5Cmain%5C"></a>[main]</h4>
+
+<p>The <tt><b>[main]</b></tt> section is where you configure the application's <tt>SecurityManager</tt> instance and any of its dependencies, such as <a href="realm.html" title="Realm">Realm</a>s.</p>
+
+<p>Configuring object instances like the SecurityManager or any of its dependencies sounds like a difficult thing to do with INI, where we can only use name/value pairs.  But through a little bit of convention and understanding of object graphs, you'll find that you can do quite a lot.  Shiro uses these assumptions to enable a simple yet fairly concise configuration mechanism.</p>
+
+<p>We often like to refer to this approach as "poor man's" Dependency Injection, and although not as powerful as full-blown Spring/Guice/JBoss XML files, you'll find it gets quite a lot done without much complexity.  Of course those other configuration mechanism are available as well, but they're not required to use Shiro.</p>
+
+<p>Just to whet your appetite, here is an example of a valid <tt>[main]</tt> configuration.  We'll cover it in detail below, but you might find that you understand quite a bit of what is going on already by intuition alone:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+[main]
+sha256Matcher = org.apache.shiro.authc.credential.Sha256CredentialsMatcher
+
+myRealm = com.company.security.shiro.DatabaseRealm
+myRealm.connectionTimeout = 30000
+myRealm.username = jsmith
+myRealm.password = secret
+myRealm.credentialsMatcher = $sha256Matcher
+
+securityManager.sessionManager.globalSessionTimeout = 1800000
+</pre>
+</div></div>
+
+<h5><a name="Configuration-Defininganobject"></a>Defining an object</h5>
+
+<p>Consider the following <tt>[main]</tt> section snippet:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+[main]
+myRealm = com.company.shiro.realm.MyRealm
+...
+</pre>
+</div></div>
+
+<p>This line instantiates a new object instance of type <tt>com.company.shiro.realm.MyRealm</tt> and makes that object available under the <b>myRealm</b> name for further reference and configuration.</p>
+
+<p>If the object instantiated implements the <tt>org.apache.shiro.util.Nameable</tt> interface, then the the <tt>Nameable.setName</tt> method will be invoked on the object with the name value (<b>myRealm</b> in this example).</p>
+
+<h5><a name="Configuration-Settingobjectproperties"></a>Setting object properties</h5>
+
+<h6><a name="Configuration-PrimitiveValues"></a>Primitive Values</h6>
+
+<p>Simple primitive properties can be assigned just by using the equals sign:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+...
+myRealm.connectionTimeout = 30000
+myRealm.username = jsmith
+...
+</pre>
+</div></div>
+
+<p>these lines of configuration translate into method calls:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+...
+myRealm.setConnectionTimeout(30000);
+myRealm.setUsername(<span class="code-quote">"jsmith"</span>);
+...
+</pre>
+</div></div>
+
+<p>How is this possible?  It assumes that all objects are <a class="external-link" href="http://en.wikipedia.org/wiki/JavaBean" rel="nofollow">Java Beans</a>-compatible <a class="external-link" href="http://en.wikipedia.org/wiki/Plain_Old_Java_Object" rel="nofollow">POJO</a>s.</p>
+
+<p>Under the covers, Shiro by default uses Apache Commons <a class="external-link" href="http://commons.apache.org/beanutils/">BeanUtils</a> to do all the heavy lifting when setting these properties.  So although INI values are text, BeanUtils knows how to convert the string values to the proper primitive types and then invoke the corresponding JavaBeans setter method.</p>
+
+<h6><a name="Configuration-ReferenceValues"></a>Reference Values</h6>
+
+<p>What if the value you need to set is not a primitive, but another object?  Well, you can use a dollar sign ($) to reference a previously-defined instance.  For example:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+...
+sha256Matcher = org.apache.shiro.authc.credential.Sha256CredentialsMatcher
+...
+myRealm.credentialsMatcher = $sha256Matcher
+...
+</pre>
+</div></div>
+
+<p>This simply locates the object defined by the name <b>sha256Matcher</b> and then uses BeanUtils to set that object on the <b>myRealm</b> instance (by calling the <tt>myRealm.setCredentialsMatcher(sha256Matcher)</tt> method).</p>
+
+<h6><a name="Configuration-NestedProperties"></a>Nested Properties</h6>
+
+<p>Using dotted notation on the left side of the INI line's equals sign, you can traverse an object graph to get to the final object/property that you want set.  For example, this config line:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+...
+securityManager.sessionManager.globalSessionTimeout = 1800000
+...
+</pre>
+</div></div>
+
+<p>Translates (by BeanUtils) into the following logic:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+securityManager.getSessionManager().setGlobalSessionTimeout(1800000);
+</pre>
+</div></div>
+
+<p>The graph traversal can be as deep as necessary: <tt>object.property1.property2....propertyN.value = blah</tt></p>
+
+<div class="panelMacro"><table class="tipMacro"><colgroup span="1"><col span="1" width="24"><col span="1"></colgroup><tr><td colspan="1" rowspan="1" valign="top"><img align="middle" src="https://cwiki.apache.org/confluence/images/icons/emoticons/check.gif" width="16" height="16" alt="" border="0"></td><td colspan="1" rowspan="1"><b>BeanUtils Property Support</b><br clear="none">Any property assignment operation supported by the BeanUtils.<a class="external-link" href="http://commons.apache.org/beanutils/v1.8.2/apidocs/org/apache/commons/beanutils/BeanUtils.html#setProperty%28java.lang.Object,%20java.lang.String,%20java.lang.Object%29">setProperty</a> method will work in Shiro's [main] section, including set/list/map element assignments.  See the <a class="external-link" href="http://commons.apache.org/beanutils/">Apache Commons BeanUtils Website</a> and documentation for more information.</td></tr></table></div>
+
+<h6><a name="Configuration-ByteArrayValues"></a>Byte Array Values</h6>
+
+<p>Because raw byte arrays can't be specified natively in a text format, we must use a text encoding of the byte array.  The values can be specified either as a Base64 encoded string (the default) or as a Hex encoded string.  The default is Base64 because Base64 encoding requires less actual text to represent values - it has a larger encoding alphabet, meaning your tokens are shorter (a bit nicer for text config).</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+# The 'cipherKey' attribute is a <span class="code-object">byte</span> array.    By <span class="code-keyword">default</span>, text values 
+# <span class="code-keyword">for</span> all <span class="code-object">byte</span> array properties are expected to be Base64 encoded:
+
+securityManager.rememberMeManager.cipherKey = kPH+bIxk5D2deZiIxcaaaA==
+...
+</pre>
+</div></div>
+
+<p>However, if you prefer to use Hex encoding instead, you must prefix the String token with <tt>0x</tt> ('zero' 'x'):</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+securityManager.rememberMeManager.cipherKey = 0x3707344A4093822299F31D008
+</pre>
+</div></div>
+
+<h6><a name="Configuration-CollectionProperties"></a>Collection Properties</h6>
+
+<p>Lists, Sets and Maps can be set like any other property - either directly or as a nested property.  For sets and lists, just specify a comma-delimited set of values or object references.</p>
+
+<p>For example, some SessionListeners:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+sessionListener1 = com.company.my.SessionListenerImplementation
+...
+sessionListener2 = com.company.my.other.SessionListenerImplementation
+...
+securityManager.sessionManager.sessionListeners = $sessionListener1, $sessionListener2
+</pre>
+</div></div>
+
+<p>For Maps, you specify a comma-delimited list of key-value pairs, where each key-value pair is delimited by a colon ':'</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+object1 = com.company.some.<span class="code-object">Class</span>
+object2 = com.company.another.<span class="code-object">Class</span>
+...
+anObject = some.class.with.a.Map.property
+
+anObject.mapProperty = key1:$object1, key2:$object2
+</pre>
+</div></div>
+
+<p>In the above example, the object referenced by <tt>$object1</tt> will be in the map under the String key <tt>key1</tt>, i.e. <tt>map.get("key1")</tt> returns <tt>object1</tt>.  You can also use other objects as the keys:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+anObject.map = $objectKey1:$objectValue1, $objectKey2:$objectValue2
+...
+</pre>
+</div></div>
+
+<h5><a name="Configuration-Considerations"></a>Considerations</h5>
+
+<h6><a name="Configuration-OrderMatters"></a>Order Matters</h6>
+
+<p>The INI format and conventions above are very convenient and easy to understand, but it is not as powerful as other text/XML-based configuration mechanisms.  The most important thing to understand when using the above mechanism is that <b>Order Matters!</b></p>
+
+<div class="panelMacro"><table class="noteMacro"><colgroup span="1"><col span="1" width="24"><col span="1"></colgroup><tr><td colspan="1" rowspan="1" valign="top"><img align="middle" src="https://cwiki.apache.org/confluence/images/icons/emoticons/warning.gif" width="16" height="16" alt="" border="0"></td><td colspan="1" rowspan="1"><b>Be Careful</b><br clear="none">Each object instantiation and each value assignment is executed <em>in the order they occur in the [main] section</em>.  These lines ultimately translate to a JavaBeans getter/setter method invocation, and so those methods are invoked in the same order!
+
+<p>Keep this in mind when writing your configuration.</p></td></tr></table></div>
+
+<h6><a name="Configuration-OverridingInstances"></a>Overriding Instances</h6>
+
+<p>Any object can be overridden by a new instance defined later in the configuration.  So for example, the 2nd <tt>myRealm</tt> definition would overwrite the first:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+...
+myRealm = com.company.security.MyRealm
+...
+myRealm = com.company.security.DatabaseRealm
+...
+</pre>
+</div></div>
+
+<p>This would result in <tt>myRealm</tt> being a <tt>com.company.security.DatabaseRealm</tt> instance and the previous instance will never be used (and garbage collected).</p>
+
+<h6><a name="Configuration-DefaultSecurityManager"></a>Default SecurityManager</h6>
+
+<p>You may have noticed in the complete example above that the SecurityManager instance's class isn't defined, and we jumped right in to just setting a nested property:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+myRealm = ...
+
+securityManager.sessionManager.globalSessionTimeout = 1800000
+...
+</pre>
+</div></div>
+
+<p>This is because the <tt>securityManager</tt> instance is a special one - it is already instantiated for you and ready to go so you don't need to know the specific <tt>SecurityManager</tt> implementation class to instantiate.</p>
+
+<p>Of course, if you actually <em>want</em> to specify your own implementation, you can, just define your implementation as specified in the "Overriding Instances" section above:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+...
+securityManager = com.company.security.shiro.MyCustomSecurityManager
+...
+</pre>
+</div></div>
+
+<p>Of course, this is rarely needed - Shiro's SecurityManager implementations are very customizable and can typically be configured with anything necessary.  You might want to ask yourself (or the user list) if you really need to do this.<br clear="none">
+<a href="#Configuration-users">users</a></p>
+<h4><a name="Configuration-%5Cusers%5C"></a>[users]</h4>
+
+<p>The <tt><b>[users]</b></tt> section allows you to define a static set of user accounts.  This is mostly useful in environments with a very small number of user accounts or where user accounts don't need to be created dynamically at runtime.  Here's an example:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+[users]
+admin = secret
+lonestarr = vespa, goodguy, schwartz
+darkhelmet = ludicrousspeed, badguy, schwartz
+</pre>
+</div></div>
+
+<div class="panelMacro"><table class="infoMacro"><colgroup span="1"><col span="1" width="24"><col span="1"></colgroup><tr><td colspan="1" rowspan="1" valign="top"><img align="middle" src="https://cwiki.apache.org/confluence/images/icons/emoticons/information.gif" width="16" height="16" alt="" border="0"></td><td colspan="1" rowspan="1"><b>Automatic IniRealm</b><br clear="none">Just defining non-empty [users] or [roles] sections will automatically trigger the creation of an <tt><a class="external-link" href="static/current/apidocs/org/apache/shiro/realm/text/IniRealm.html">org.apache.shiro.realm.text.IniRealm</a></tt> instance and make it available in the [main] section under the name <tt><b>iniRealm</b></tt>.  You can configure it like any other object as described above.</td></tr></table></div>
+
+<h5><a name="Configuration-LineFormat"></a>Line Format</h5>
+
+<p>Each line in the [users] section must conform to the following format:</p>
+
+<p><tt>username</tt> = <tt>password</tt>, <em>roleName1</em>, <em>roleName2</em>, ..., <em>roleNameN</em></p>
+
+<ul><li>The value on the left of the equals sign is the username</li><li>The first value on the right of the equals sign is the user's password.  A password is required.</li><li>Any comma-delimited values after the password are the names of roles assigned to that user.  Role names are optional.</li></ul>
+
+
+<h5><a name="Configuration-EncryptingPasswords"></a>Encrypting Passwords</h5>
+
+<p>If you don't want the [users] section passwords to be in plain-text, you can encrypt them using your favorite hash algorithm (MD5, Sha1, Sha256, etc) however you like and use the resulting string as the password value.  By default, the password string is expected to be Hex encoded, but can be configured to be Base64 encoded instead (see below).</p>
+
+<div class="panelMacro"><table class="tipMacro"><colgroup span="1"><col span="1" width="24"><col span="1"></colgroup><tr><td colspan="1" rowspan="1" valign="top"><img align="middle" src="https://cwiki.apache.org/confluence/images/icons/emoticons/check.gif" width="16" height="16" alt="" border="0"></td><td colspan="1" rowspan="1"><b>Easy Secure Passwords</b><br clear="none">To save time and use best-practices, you might want to use Shiro's <a href="command-line-hasher.html" title="Command Line Hasher">Command Line Hasher</a>, which will hash passwords as well as any other type of resource.  It is especially convenient for encrypting INI <tt>[users]</tt> passwords.</td></tr></table></div>
+
+<p>Once you've specified the hashed text password values, you have to tell Shiro that these are encrypted.  You do that by configuring the implicitly created <tt>iniRealm</tt> in the [main] section to use an appropriate <tt>CredentialsMatcher</tt> implementation corresponding to the hash algorithm you've specified:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+[main]
+...
+sha256Matcher = org.apache.shiro.authc.credential.Sha256CredentialsMatcher
+...
+iniRealm.credentialsMatcher = $sha256Matcher
+...
+
+[users]
+# user1 = sha256-hashed-hex-encoded password, role1, role2, ...
+user1 = 2bb80d537b1da3e38bd30361aa855686bde0eacd7162fef6a25fe97bf527a25b, role1, role2, ... 
+</pre>
+</div></div>
+
+<p>You can configure any properties on the <tt>CredentialsMatcher</tt> like any other object to reflect your hashing strategy, for example, to specify if salting is used or how many hash iterations to execute.  See the <tt><a class="external-link" href="static/current/apidocs/org/apache/shiro/authc/credential/HashedCredentialsMatcher.html">org.apache.shiro.authc.credential.HashedCredentialsMatcher</a></tt> JavaDoc to better understand hashing strategies and if they might be useful to you.  </p>
+
+<p>For example, if your users' password strings were Base64 encoded instead of the default Hex, you could specify:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+[main]
+...
+# <span class="code-keyword">true</span> = hex, <span class="code-keyword">false</span> = base64:
+sha256Matcher.storedCredentialsHexEncoded = <span class="code-keyword">false</span>
+</pre>
+</div></div>
+
+<h4><a name="Configuration-%5Croles%5C"></a>[roles]</h4>
+
+<p>The <tt><b>[roles]</b></tt> section allows you to associate <a href="permissions.html" title="Permissions">Permissions</a> with the roles defined in the [users] section.  Again, this is useful in environments with a small number of roles or where roles don't need to be created dynamically at runtime.  Here's an example:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+[roles]
+# 'admin' role has all permissions, indicated by the wildcard '*'
+admin = *
+# The 'schwartz' role can <span class="code-keyword">do</span> anything (*) with any lightsaber:
+schwartz = lightsaber:*
+# The 'goodguy' role is allowed to 'drive' (action) the winnebago (type) with
+# license plate 'eagle5' (instance specific id)
+goodguy = winnebago:drive:eagle5
+</pre>
+</div></div>
+
+<h5><a name="Configuration-LineFormat"></a>Line Format</h5>
+
+<p>Each line in the [roles] section must must define a role-to-permission(s) key/value mapping with in the following format:</p>
+
+<p><tt>rolename</tt> = <em>permissionDefinition1</em>, <em>permissionDefinition2</em>, ..., <em>permissionDefinitionN</em></p>
+
+<p>where <em>permissionDefinition</em> is an arbitrary String, but most people will want to use strings that conform<br clear="none">
+to the <tt><a class="external-link" href="static/current/apidocs/org/apache/shiro/authz/permission/WildcardPermission.html">org.apache.shiro.authz.permission.WildcardPermission</a></tt> format for ease of use and flexibility.  See the <a href="permissions.html" title="Permissions">Permissions</a> documentation for more information on Permissions and how you can benefit from them. </p>
+
+<div class="panelMacro"><table class="infoMacro"><colgroup span="1"><col span="1" width="24"><col span="1"></colgroup><tr><td colspan="1" rowspan="1" valign="top"><img align="middle" src="https://cwiki.apache.org/confluence/images/icons/emoticons/information.gif" width="16" height="16" alt="" border="0"></td><td colspan="1" rowspan="1"><b>Internal commas</b><br clear="none">Note that if an individual <em>permissionDefinition</em> needs to be internally comma-delimited (e.g. <tt>printer:5thFloor:print,info</tt>), you will need to surround that definition with double quotes (") to avoid parsing errors:<br clear="none">
+<tt>"printer:5thFloor:print,info"</tt></td></tr></table></div>
+
+<div class="panelMacro"><table class="tipMacro"><colgroup span="1"><col span="1" width="24"><col span="1"></colgroup><tr><td colspan="1" rowspan="1" valign="top"><img align="middle" src="https://cwiki.apache.org/confluence/images/icons/emoticons/check.gif" width="16" height="16" alt="" border="0"></td><td colspan="1" rowspan="1"><b>Roles without Permissions</b><br clear="none">If you have roles that don't require permission associations, you don't need to list them in the [roles] section if you don't want to.  Just defining the role names in the [users] section is enough to create the role if it does not exist yet.</td></tr></table></div>
+
+<h4><a name="Configuration-%5Curls%5C"></a>[urls]</h4>
+
+<p>This section and its options is described in the <a href="web.html" title="Web">Web</a> chapter.</p>
+
+<h2><a name="Configuration-Lendahandwithdocumentation"></a>Lend a hand with documentation </h2>
+
+<p>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. </p>
+
+<p>The easiest way to contribute your documentation is to send it to the <a class="external-link" href="http://shiro-user.582556.n2.nabble.com/" rel="nofollow">User Forum</a> or the <a href="mailing-lists.html" title="Mailing Lists">User Mailing List</a>.</p>
\ No newline at end of file

Added: shiro/site/trunk/confluence-auto-export.html
URL: http://svn.apache.org/viewvc/shiro/site/trunk/confluence-auto-export.html?rev=1481417&view=auto
==============================================================================
--- shiro/site/trunk/confluence-auto-export.html (added)
+++ shiro/site/trunk/confluence-auto-export.html Sat May 11 21:10:40 2013
@@ -0,0 +1,165 @@
+<h1><a name="ConfluenceAutoExport-ConfluenceAutoExportProcessforApacheShiro"></a>Confluence Auto Export Process for Apache Shiro</h1>
+
+<p>This page describes how we use the Confluence <tt>Auto Export</tt> plugin to create a custom look and feel for our project's public website while still using Confluence to manage and host our content.  </p>
+
+<p>This page is especially useful if you're a member of another Apache project that wants to use Confluence as your content repository but have a nicely formatted custom look and feel that you can design.</p>
+
+<h3><a name="ConfluenceAutoExport-Overview"></a>Overview</h3>
+
+<p>The high level overview is that you create a custom look and feel in the form of an HTML template.  Confluence is then configured to automatically export your project space to static .html files that conform to the template.  This allows a project website to have a different look entirely than the default Confluence theme.</p>
+
+<p>The generated 'templatized' static .html files are then served as the project's public facing website, which is beneficial for scalability - an Apache farm of web servers can serve the static files (doing what Apache does best), relieving the Confluence server from direct and/or heavy load.</p>
+
+<h3><a name="ConfluenceAutoExport-StepbyStep"></a>Step-by-Step</h3>
+
+<p>Here are step-by-step instructions to enable this for your project:</p>
+
+<ol><li><b>Create Your HTML Template</b>
+<br clear="none" class="atl-forced-newline">
+<br clear="none" class="atl-forced-newline">
+A project contributor creates a single Velocity-based HTML template file.  The Confluence documentation has a <a class="external-link" href="http://confluence.atlassian.com/display/CONFDEV/Basic+Introduction+to+Velocity" rel="nofollow">Basic Introduction to Velocity</a> that links to the <a class="external-link" href="http://velocity.apache.org/engine/releases/velocity-1.4/user-guide.html">Velocity User Guide</a>.  You'll want to read the Velocity User Guide to understand how to set template variables, write conditional statements, etc.
+<br clear="none" class="atl-forced-newline">
+<br clear="none" class="atl-forced-newline">
+<div class="panelMacro"><table class="tipMacro"><colgroup span="1"><col span="1" width="24"><col span="1"></colgroup><tr><td colspan="1" rowspan="1" valign="top"><img align="middle" src="https://cwiki.apache.org/confluence/images/icons/emoticons/check.gif" width="16" height="16" alt="" border="0"></td><td colspan="1" rowspan="1"><b>Confluence Velocity Objects</b><br clear="none">When writing your template, you will want to know about the <a class="external-link" href="http://confluence.atlassian.com/display/CONFDEV/Confluence+Objects+Accessible+From+Velocity" rel="nofollow">Confluence Objects Accessible From Velocity</a>.  You can use these existing variables and macros from within your template as necessary.</td></tr></table></div>
+<p><br clear="none" class="atl-forced-newline">
+<br clear="none" class="atl-forced-newline">
+Also note that your template file can reference static assets such as images, css files and javascript as necessary.  Typically a template designer will work in whatever design tool they like and test it out on browsers etc.  Its just that the static assets themselves are not imported into the <tt>Auto Export</tt> plugin directly.  They need to be hosted in a separate location.  We'll cover that next.
+<br clear="none" class="atl-forced-newline">
+<br clear="none" class="atl-forced-newline">
+<b>Example</b>: Here is <a href="shiroConfluenceAutoExportTemplate.vhtml.txt?version=1&amp;modificationDate=1274492875000">Shiro's Auto Export HTML Template</a> (as of 21 May 2010).  You can use it as an example or modify as necessary for your own site in accordance with the Apache 2.0 license.
+<br clear="none" class="atl-forced-newline">
+<br clear="none" class="atl-forced-newline"></p></li><li><b>Upload Template Static Resources</b>
+<br clear="none" class="atl-forced-newline">
+<br clear="none" class="atl-forced-newline">
+Static resources that your .html template file references are not imported into the <tt>Auto Export</tt> plugin - you need to place those in a separate location.  The way we've done it for Shiro is to create a single purposefully reserved directory at the root of our website called <tt>static</tt>.  So if our public website root is located here:
+<br clear="none" class="atl-forced-newline">
+<br clear="none" class="atl-forced-newline">
+<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+<pre>people.apache.org:/www/incubator.apache.org/shiro/
+</pre>
+</div></div>
+<p><br clear="none" class="atl-forced-newline">
+then all of our static content that we manage manually will be in this directory:
+<br clear="none" class="atl-forced-newline">
+<br clear="none" class="atl-forced-newline"></p>
+<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+<pre>people.apache.org:/www/incubator.apache.org/shiro/static/
+</pre>
+</div></div>
+<p><br clear="none" class="atl-forced-newline">
+It is important that you don't create a Confluence page at the root of your Confluence space named <tt>Static</tt> as it will conflict with your manually managed static directory above.
+<br clear="none" class="atl-forced-newline">
+<br clear="none" class="atl-forced-newline">
+Also note that because everything else in the <tt>/www/incubator.apache.org/shiro</tt> directory is auto-exported from Confluence, you really don't ever want to mess with any files in that directory.  Stick to only manually editing things in the <tt>static</tt> subdirectory and you'll be fine.
+<br clear="none" class="atl-forced-newline">
+<br clear="none" class="atl-forced-newline">
+So, if our .html template referenced some images, css, and javascript in an <tt>assets</tt> directory while we were designing the template, you'll need to secure <tt>rsync</tt> or <tt>sftp</tt> those resources to a matching directory structure on <tt>people.apache.org</tt> under our reserved <tt>static</tt> directory:
+<br clear="none" class="atl-forced-newline">
+<br clear="none" class="atl-forced-newline"></p>
+<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+<pre>/www/incubator.apache.org/shiro/static/assets/images/header.jpg
+/www/incubator.apache.org/shiro/static/assets/css/style.css
+/www/incubator.apache.org/shiro/static/assets/js/some-javscript-library-minified.js
+...
+</pre>
+</div></div>
+<div class="panelMacro"><table class="tipMacro"><colgroup span="1"><col span="1" width="24"><col span="1"></colgroup><tr><td colspan="1" rowspan="1" valign="top"><img align="middle" src="https://cwiki.apache.org/confluence/images/icons/emoticons/check.gif" width="16" height="16" alt="" border="0"></td><td colspan="1" rowspan="1"><b>Heavy CSS</b><br clear="none">For reasons that will become apparent later, it is recommended to make heavy use of CSS in your template as well as ensure that the CSS definitions are in an external static file and <b>not</b> embedded in the template itself: you will be able to freely change your CSS files in this static directory, while it will be much harder to change the template after it is installed.  If your template heavily leverages CSS, you can change the CSS whenever you want.</td></tr></table></div>
+<p><br clear="none" class="atl-forced-newline"></p></li><li><b>Update Template Resource References</b>
+<br clear="none" class="atl-forced-newline">
+<br clear="none" class="atl-forced-newline">
+Once you've uploaded those resources to their appropriate place on <tt>people.apache.org</tt> filesystem, you need to now change your template to reference their runtime location where they will be when your page is served by the web server.  We did this by setting a Velocity variable in our template that reflects the runtime site root:
+<br clear="none" class="atl-forced-newline">
+<br clear="none" class="atl-forced-newline">
+<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+<pre>&lt;!DOCTYPE html PUBLIC ...
+ASF license header here ...
+##
+#set ($siteroot = "http://incubator.apache.org/shiro")
+... other variables, macro definitions, etc here ...
+##
+&lt;html&gt;
+... rest of html template here ...
+&lt;/html&gt;
+</pre>
+</div></div>
+<p><br clear="none" class="atl-forced-newline">
+Then you an use the Velocity variables in your html to reference their location:
+<br clear="none" class="atl-forced-newline">
+<br clear="none" class="atl-forced-newline"></p>
+<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+<pre>&lt;img src="$siteroot/assets/images/header.jpg"/&gt;
+</pre>
+</div></div>
+<p><br clear="none" class="atl-forced-newline">
+<br clear="none" class="atl-forced-newline">
+Again, see <a href="shiroConfluenceAutoExportTemplate.vhtml.txt?version=1&amp;modificationDate=1274492875000">Shiro's Auto Export HTML Template</a> as an example.
+<br clear="none" class="atl-forced-newline">
+<br clear="none" class="atl-forced-newline"></p></li><li><b>Set Up a Cron Job to Sync Auto-Exported Content</b>
+<br clear="none" class="atl-forced-newline">
+<br clear="none" class="atl-forced-newline">
+When <tt>Auto Export</tt> runs, it outputs its content into a different directory than your website filesystem location.  You need to ensure that after <tt>Auto Export</tt> runs, the generated content will make its way to the correct filesystem location that will be published to the web server farm.  You can do that by setting up a cron job on <b>one</b> of the project team member's <tt>people.apache.org</tt> account:
+<br clear="none" class="atl-forced-newline">
+<br clear="none" class="atl-forced-newline">
+First make sure that when the crontab editor runs, it is using an editor that you feel comfortable in (VI, Emacs, etc):
+<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+<pre>&gt; export EDITOR=vi
+</pre>
+</div></div>
+<p><br clear="none" class="atl-forced-newline">
+Then execute the following crontab command, which will launch your preferred editor:
+<br clear="none" class="atl-forced-newline"></p>
+<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+<pre>&gt; crontab -e
+</pre>
+</div></div>
+<p><br clear="none" class="atl-forced-newline">
+Ensure the following 3 cron lines* are in that file (where <tt>SPACENAME</tt> is the case-sensitive Confluence space name (in our case <tt>SHIRO</tt>) and <tt>PROJECTNAME</tt> is typically your lower-case project name (in our case <tt>shiro</tt>):
+<br clear="none" class="atl-forced-newline">
+<br clear="none" class="atl-forced-newline"></p>
+<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+<pre>0 * * * * /usr/local/bin/rsync -p -r /www/confluence-exports/SPACENAME/ /www/incubator.apache.org/PROJECTNAME &gt;/dev/null 2&gt;&amp;1
+5 * * * * find /www/incubator.apache.org/PROJECTNAME -type f -exec chmod g+rw {} \; &gt;/dev/null 2&gt;&amp;1
+5 * * * * find /www/incubator.apache.org/PROJECTNAME -type d -exec chmod g+rwx {} \; &gt;/dev/null 2&gt;&amp;1
+</pre>
+</div></div>
+<p><br clear="none" class="atl-forced-newline">
+<br clear="none" class="atl-forced-newline">
+Then save and exit the file.
+<br clear="none" class="atl-forced-newline">
+<br clear="none" class="atl-forced-newline">
+These 3 cron lines say:</p>
+	<ul><li>Line 1: "Every minute (on the minute), rsync the Confluence auto-exported content from its output directory to my project's public website directory"</li><li>Line 2: "Every minute (at the 5 second mark), ensure all the files in my project's public website are (recursively) made group readable and writable".  You want other project team members to be able to write to them if necessary.</li><li>Line 3: "Every minute (at the 5 second mark), ensure all the directories in my project's public website are (recursively) made group readable, writable and executable".
+<br clear="none" class="atl-forced-newline">
+<br clear="none" class="atl-forced-newline">
+* The <tt><b>&gt;/dev/null 2&gt;&amp;1</b></tt> parts at the end of each line will swallow any output that would have been emailed to you if anything failed.  Typically you'll see some innocuous permission-related messages that can be ignored.  You can always take off that part on each line if you want regular emails - up to you.
+<br clear="none" class="atl-forced-newline">
+<br clear="none" class="atl-forced-newline"></li></ul>
+	</li><li><b>Ask a Confluence Administrator to Import Your Template</b>
+<br clear="none" class="atl-forced-newline">
+<br clear="none" class="atl-forced-newline">
+After you've updated your template to reference the correct resource paths and made your crontab entries, you need to find an Apache member with Confluence administrative privileges to add your template file to the <tt>Auto Export</tt> plugin configuration.  Unfortunately only a Confluence administrator may perform this function - the plugin does not support per-project administrators.  Check with your project mentors or the Incubator PMC as they will typically know who to contact.
+<br clear="none" class="atl-forced-newline">
+<br clear="none" class="atl-forced-newline">
+Once they've added the template to the configuration, also (kindly) ask them if they would explicitly export your Confluence space so you can test the results.  You can also change and save a wiki page at any time to trigger the export process and it will be copied to your project webspace when the cron job runs.
+<br clear="none" class="atl-forced-newline">
+<br clear="none" class="atl-forced-newline">
+<b>Note</b>: This is why it is important to use CSS heavily in your template. Because you may not have direct access to change the template whenever you want, it is better to rely on CSS that you <em>can</em> change whenever you want.
+<br clear="none" class="atl-forced-newline">
+<br clear="none" class="atl-forced-newline"></li><li><b>Verify Pages Export Correctly</b>
+<br clear="none" class="atl-forced-newline">
+<br clear="none" class="atl-forced-newline">
+After your template has been installed and you make modifications to your space pages, you should see them start to show up within a minute or two in your project's root web directory (again, for Shiro, this is in <tt>people.apache.org:/www/incubator.apache.org/shiro</tt>).  Look inside the .html files and you should see your HTML template code surrounding the wiki content.  If you see this, <tt>Auto Export</tt> and your cron job are running propertly.
+<br clear="none" class="atl-forced-newline">
+<br clear="none" class="atl-forced-newline"></li><li><b>Wait For the Web Server Farm</b>
+<br clear="none" class="atl-forced-newline">
+<br clear="none" class="atl-forced-newline">
+As mentioned before, the static .html files exported to your <tt>/www/incubator.apache.org/projectname</tt> web directory need to propagate to an Apache web server farm that actually services HTTP requests.  We don't have access to those machines, so we have to wait for an automated process (managed by Apache Infrastructure) to pick up the files in <tt>/www</tt> and sync them to the server farm.  This process can take up to an hour or two.
+<br clear="none" class="atl-forced-newline">
+<br clear="none" class="atl-forced-newline">
+After an hour or two, visit the site, hit refresh, and you should see any changes that you made previously in Confluence display as a nice page with your template's look and feel.  You can make changes to Confluence pages from this point on and you won't need to touch the template or <tt>Auto Export</tt> settings again (unless you want to change the template).
+<br clear="none" class="atl-forced-newline">
+<br clear="none" class="atl-forced-newline">
+Now you're done setting up Auto Export!</li></ol>
+
+
+<p>Please contact the <tt>dev@shiro.apache.org</tt> mailing list with errata.</p>
\ No newline at end of file

Added: shiro/site/trunk/contribute.html
URL: http://svn.apache.org/viewvc/shiro/site/trunk/contribute.html?rev=1481417&view=auto
==============================================================================
--- shiro/site/trunk/contribute.html (added)
+++ shiro/site/trunk/contribute.html Sat May 11 21:10:40 2013
@@ -0,0 +1,18 @@
+<h1><a name="Contribute-ContributingtoApacheShiro"></a>Contributing to Apache Shiro</h1>
+
+<p>Apache Shiro is a non-profit project and relies on your help and contributions in order to evolve and improve.</p>
+
+<p>At the Shiro project we make it easy for anyone to join our great community and lend a hand.  We welcome any help you can offer inlcuding help with documentation, identifying bugs, providing answers on the user mailing list, and providing helpful code improvements.</p>
+
+<p>Below are helpful links on how you can contribute to the Apache Shiro project.</p>
+
+<ul class="alternate" type="square"><li><b><a href="how-to-contribute.html" title="How to Contribute">How to Contribute</a></b> - A starting point for contributing to the Shiro project</li></ul>
+
+
+<ul class="alternate" type="square"><li><b><a class="external-link" href="https://issues.apache.org/jira/issues/?jql=project%20%3D%20SHIRO%20AND%20status%20%3D%20Open%20ORDER%20BY%20priority%20DESC">Shiro Issue Tracker</a></b> - Once you're ready to contribute, this is a good place to see what needs to get done</li></ul>
+
+
+<ul class="alternate" type="square"><li><b><a class="external-link" href="http://www.apache.org/foundation/sponsorship.html">Donate to ASF</a></b> - Shiro is a project under the Apache Software Foundation, a non-profit that relies on donations and community support</li></ul>
+
+
+<ul class="alternate" type="square"><li><b><a href="developer-resources.html" title="Developer Resources">Developer Resources</a></b> - Helpful information for anyone providing project help as a committer or contributor</li></ul>

Added: shiro/site/trunk/core.html
URL: http://svn.apache.org/viewvc/shiro/site/trunk/core.html?rev=1481417&view=auto
==============================================================================
--- shiro/site/trunk/core.html (added)
+++ shiro/site/trunk/core.html Sat May 11 21:10:40 2013
@@ -0,0 +1,31 @@
+<h1><a name="Core-CoreConceptsinApacheShiro"></a>Core Concepts in Apache Shiro</h1>
+
+<p>This part of the documentation covers Shiro's core architectural concepts.</p>
+
+<p>First we'll present Shiro's architecture and a summary of each core concept.  Then we'll cover the most important concept in Shiro - the <tt>Subject</tt>, a security-specific 'view' of a <em>single</em> application user.  Next we'll discuss the <tt>SecurityManager</tt>, an application singleton that manages all Subjects for the application, and as well as the SecurityManager's supporting components that do most of Shiro's heavy lifting. Then onto Realms, the security-specific DAOs, Shiro communicates with and then Permissions, the building block of any security policy.</p>
+
+<p></p>
+
+<ul><li><a href="architecture.html" title="Architecture">Architecture</a></li></ul>
+
+
+<ul><li><a href="subject.html" title="Subject">Subject</a></li></ul>
+
+
+<ul><li><a href="securitymanager.html" title="SecurityManager">SecurityManager</a><br clear="none">
+</li></ul>
+
+
+<ul><li><a href="realm.html" title="Realm">Realms</a></li></ul>
+
+
+<ul><li><a href="permissions.html" title="Permissions">Permissions</a></li></ul>
+
+
+<p></p>
+
+<h2><a name="Core-Lendahandwithdocumentation"></a>Lend a hand with documentation </h2>
+
+<p>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. </p>
+
+<p>The easiest way to contribute your documentation is to send it to the <a class="external-link" href="http://shiro-user.582556.n2.nabble.com/" rel="nofollow">User Forum</a> or the <a href="mailing-lists.html" title="Mailing Lists">User Mailing List</a>.</p>
\ No newline at end of file

Added: shiro/site/trunk/cryptography-features.html
URL: http://svn.apache.org/viewvc/shiro/site/trunk/cryptography-features.html?rev=1481417&view=auto
==============================================================================
--- shiro/site/trunk/cryptography-features.html (added)
+++ shiro/site/trunk/cryptography-features.html Sat May 11 21:10:40 2013
@@ -0,0 +1,58 @@
+<h1><a name="CryptographyFeatures-ApacheShiroCryptographyFeatures"></a>Apache Shiro Cryptography Features</h1>
+
+
+<div class="addthis_toolbox addthis_default_style">
+<a class="addthis_button_compact" href="http://www.addthis.com/bookmark.php?v=250&amp;pubid=ra-4d66ef016022c3bd">Share</a>
+<span class="addthis_separator">|</span>
+<a class="addthis_button_preferred_1"></a>
+<a class="addthis_button_preferred_2"></a>
+<a class="addthis_button_preferred_3"></a>
+<a class="addthis_button_preferred_4"></a>
+</div>
+<script type="text/javascript">var addthis_config = {"data_track_clickback":true};</script>
+<script type="text/javascript" src="http://s7.addthis.com/js/250/addthis_widget.js#pubid=ra-4d66ef016022c3bd"></script>
+
+
+<p><br clear="none" class="atl-forced-newline">
+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.</p>
+
+<p>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.</p>
+
+<h2><a name="CryptographyFeatures-SimplicityFeatures"></a>Simplicity Features</h2>
+
+<ul><li><b>Interface-driven, POJO based</b> - 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.</li></ul>
+
+
+<ul><li><b>Simplified wrapper over JCE</b> - 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.</li></ul>
+
+
+<ul><li><b>&#8220;Object Orientifies&#8221; cryptography concepts</b> - 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.</li></ul>
+
+
+<ul><li><b>Runtime Exceptions</b> - Like everywhere else in Shiro, all cryptography exceptions are RuntimeExceptions.  You can decide whether or not to catch an exception based on your needs.</li></ul>
+
+
+<h2><a name="CryptographyFeatures-CipherFeatures"></a>Cipher Features</h2>
+
+<ul><li><b>OO Hierarchy</b> - Unlike the JCE, Shiro Cipher representations follow an Object-Oriented class hierarchy that match their mathematical concepts: <tt>AbstractSymmetricCipherService</tt>, <tt>DefaultBlockCipherService</tt>, <tt>AesCipherService</tt>, etc.  This allows you to easily override existing classes and extend functionality as needed.</li></ul>
+
+
+<ul><li><b>Just instantiate a class</b> - 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, <tt>new AesCipherService()</tt>.</li></ul>
+
+
+<ul><li><b>More secure default settings</b> - 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.</li></ul>
+
+
+<h2><a name="CryptographyFeatures-HashFeatures"></a>Hash Features</h2>
+
+<ul><li><b>Deault interface implementations</b> - 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. <tt>new Md5Hash(data)</tt>) instead of being forced to use type-unsafe string factory methods in the JDK.</li></ul>
+
+
+<ul><li><b>Built-in Hex and Base64 conversion</b> - Shiro Hash instances can automatically provide Hex and Base-64 encoding of hashed data via their <tt>toHex()</tt> and <tt>toBase64()</tt> methods.  So now you do not need to figure out how to correctly encode the data yourself.</li></ul>
+
+
+<ul><li><b>Built-in Salt and repeated hashing support</b> - 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.</li></ul>
+
+
+<h2><a name="CryptographyFeatures-GetStartedin10MinuteswithShiro"></a>Get Started in 10 Minutes with Shiro</h2>
+<p>Try out Shiro for yourself with our <a href="10-minute-tutorial.html" title="10 Minute Tutorial">10 Minute Tutorial</a>.  And if you have any questions about Shiro, please check out our <a href="forums.html" title="Forums">community forum</a> or <a href="mailing-lists.html" title="Mailing Lists">user mailing list</a> for answers from the community.</p>
\ No newline at end of file

Added: shiro/site/trunk/cryptography.html
URL: http://svn.apache.org/viewvc/shiro/site/trunk/cryptography.html?rev=1481417&view=auto
==============================================================================
--- shiro/site/trunk/cryptography.html (added)
+++ shiro/site/trunk/cryptography.html Sat May 11 21:10:40 2013
@@ -0,0 +1,7 @@
+<p>TODO</p>
+
+<h2><a name="Cryptography-Lendahandwithdocumentation"></a>Lend a hand with documentation </h2>
+
+<p>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. </p>
+
+<p>The easiest way to contribute your documentation is to send it to the <a class="external-link" href="http://shiro-user.582556.n2.nabble.com/" rel="nofollow">User Forum</a> or the <a href="mailing-lists.html" title="Mailing Lists">User Mailing List</a>.</p>
\ No newline at end of file

Added: shiro/site/trunk/deprecated-pages.html
URL: http://svn.apache.org/viewvc/shiro/site/trunk/deprecated-pages.html?rev=1481417&view=auto
==============================================================================
    (empty)

Added: shiro/site/trunk/developer-resources.html
URL: http://svn.apache.org/viewvc/shiro/site/trunk/developer-resources.html?rev=1481417&view=auto
==============================================================================
--- shiro/site/trunk/developer-resources.html (added)
+++ shiro/site/trunk/developer-resources.html Sat May 11 21:10:40 2013
@@ -0,0 +1,36 @@
+<h1><a name="DeveloperResources-ApacheShiroDeveloperResources"></a>Apache Shiro Developer Resources</h1>
+
+<p>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</p>
+
+<h2><a name="DeveloperResources-WritingDocumentation"></a>Writing Documentation</h2>
+
+<p>All non-JavaDoc documentation is written in our <a class="external-link" href="http://cwiki.apache.org/confluence/display/SHIRO/">Apache Shiro Confluence Wiki Space</a>.  This space is converted into the public website by the <a href="confluence-auto-export.html" title="Confluence Auto Export">Confluence Auto Export Process</a>.</p>
+
+<h2><a name="DeveloperResources-SourceCodeRepository"></a>Source Code Repository</h2>
+
+<p>We use the Subversion repository located at <a class="external-link" href="http://svn.apache.org/repos/asf/shiro">http://svn.apache.org/repos/asf/shiro</a>.  Committers must use the <tt>https</tt> scheme (not <tt>http</tt>).</p>
+
+<p>Active development is done in the <tt>trunk</tt> subdirectory.  The <tt>branches</tt> and <tt>tags</tt> peer subdirectories exist based on the <a class="external-link" href="http://apr.apache.org/versioning.html">Apache APR Versioning Scheme</a> and are generally created/maintained by the dev team using the <a class="external-link" href="http://maven.apache.org/plugins/maven-release-plugin/">Maven Release Plugin</a>.</p>
+
+<h3><a name="DeveloperResources-BuildingfromSubversion"></a>Building from Subversion</h3>
+
+<p>For Shiro cutting-edge development, you can check-out the code from Subversion and build it using <a class="external-link" href="http://maven.apache.org">Maven</a> 2.2+:</p>
+
+<ol><li>Check out the code:
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+mkdir shiro
+cd shiro
+svn co https:<span class="code-comment">//svn.apache.org/repos/asf/shiro/trunk trunk</span>
+</pre>
+</div></div></li><li>Build the project using <a class="external-link" href="http://maven.apache.org">Maven</a> 2.2+:
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+cd trunk
+mvn install
+</pre>
+</div></div>
+<p>The resulting artifacts will be in your local M2 Repo under the org.apache.shiro group.</p></li></ol>
+
+
+<div class="panelMacro"><table class="warningMacro"><colgroup span="1"><col span="1" width="24"><col span="1"></colgroup><tr><td colspan="1" rowspan="1" valign="top"><img align="middle" src="https://cwiki.apache.org/confluence/images/icons/emoticons/forbidden.gif" width="16" height="16" alt="" border="0"></td><td colspan="1" rowspan="1"><b>Cutting-edge development</b><br clear="none">When building from <tt>trunk</tt> or any branches, use the generated artifacts at your own risk!  Current and previous stable releases will always be available via the <a href="download.html" title="Download">Download</a> page.</td></tr></table></div>
\ No newline at end of file



Mime
View raw message