http://git-wip-us.apache.org/repos/asf/shiro-site/blob/ddea166c/java-authorization-guide.html.vtl ---------------------------------------------------------------------- diff --git a/java-authorization-guide.html.vtl b/java-authorization-guide.html.vtl new file mode 100644 index 0000000..13cb3b6 --- /dev/null +++ b/java-authorization-guide.html.vtl @@ -0,0 +1,234 @@ +<h1><a name="JavaAuthorizationGuide-JavaAuthorizationGuidewithApacheShiro"></a>Java Authorization Guide with Apache Shiro</h1> + +<p><br clear="none" class="atl-forced-newline"> +Authorization, or access control, is the function of specifying access rights to resources. In other words, <em>who</em> has access to <em>what</em>.</p> + +<p>Examples of authorization checks are: Is the user allowed to look at this webpage, edit this data, view this button, or print to this printer? Those are all decisions determining what a user has access to.</p> + +<h2><a name="JavaAuthorizationGuide-ElementsofAuthorization"></a>Elements of Authorization</h2> +<p>Authorization has three core elements that we reference quite a bit in Shiro-- permissions, roles, and users. </p> + +<h3><a name="JavaAuthorizationGuide-PermissionsDefined"></a>Permissions Defined</h3> + +<table align="right" width="275" style="margin-left: 20px; margin-bottom: 20px; border-style: solid; border-width: 2px; border-color: navy" cellpadding="10px"> + +<tr> +<td> +<div id="border"> + <h2>Related Content</h2> + + <h3><a href="authorization-features.html">Authorization Features</a></h3> + <p>Quick overview of permissions, roles, and users in Shiro. </br><span style="font-size:11"><a href="authorization-features.html">Read More >></a></span></p> + + <h3><a href="authorization.html">Authorization Docs</a></h3> + <p>Full documentation on Apache Shiro's Authorization functionality. </br><span style="font-size:11"><a href="authorization.html">Read More >></a></span></p> + + <h3><a href="get-started.html">Getting Started</a></h3> + <p>Resources, guides and tutorials for new Shiro users. </br><span style="font-size:11"><a href="get-started.html">Read More >></a></span></p> + + <h3><a href="10-minute-tutorial.html">10-Minute Shiro Tutorial</a></h3> + <p>Try Apache Shiro for yourself in under 10 minutes. </br><span style="font-size:11"><a href="10-minute-tutorial.html">Read More >></a></span></p> + + <h3><a href="webapp-tutorial.html">Web App Tutorial</a></h3> + <p>Step-by-step tutorial for securing a web application with Shiro. </br><span style="font-size:11"><a href="webapp-tutorial.html">Read More >></a></span></p> + +</div> +</td> +</tr> +</table> + +<p>Permissions are the most atomic level of a security policy and they are statements of functionality. Permissions represent what can be done in your application. A well formed permission describes a resource types and what actions are possible when you interact with those resources. Can you <em>open</em> a <em>door</em>? Can you <em>read</em> a <em>file</em>? Can you <em>delete</em> a <em>customer record</em>? Can you <em>push</em> a <em>button</em>? </p> + +<p>Common actions for data-related resources are create, read, update, and delete, commonly referred to as CRUD.</p> + +<p>It is important to understand that permissions do not have knowledge of <em>who</em> can perform the actions-- they are just statements of <em>what</em> actions can be performed.</p> + +<h4><a name="JavaAuthorizationGuide-Levelsofpermissiongranularity"></a>Levels of permission granularity</h4> +<p>The permissions above all specify an actions (open, read, delete, etc) on a resource (door, file, customer record, etc). In Shiro, you can define a permission to any depth you like. Here are a few common permission levels in order of granularity.</p> + +<ul><li>Resource Level - This is the broadest and easiest to build. A user can edit customer records or open doors. The resource is specified but not a specific instance of that resource.</li><li>Instance Level - The permission specifies the instance of a resource. A user can edit the customer record for IBM or open the kitchen door.</li><li>Attribute Level - The permission now specifies an attribute of an instance or resource. A user can edit the address on the IBM customer record.</li></ul> + + +<p>For more information on Permissions please check out the <a href="permissions.html" title="Permissions">Permissions Documentation</a></p> + +<h3><a name="JavaAuthorizationGuide-RolesDefined"></a>Roles Defined</h3> +<p>In the context of Authorization, Roles are effectively a collection of permissions used to simplify the management of permissions and users. So users can be assigned roles instead of being assigned permissions directly, which can get complicated with larger user bases and more complex applications. So, for example, a bank application might have an <em>administrator</em> role or a <em>bank teller</em> role.</p> + +<p>There are two types of roles that you need to be aware of and Shiro will support both.</p> + +<h4><a name="JavaAuthorizationGuide-ImplicitRoles"></a>Implicit Roles</h4> +<p>Most people view roles as what we define as an implicit role where your application <em>implies</em> a set of permissions because a user has a particular role as opposed to the role explicitly being assigned permissions or your application checking for those permissions. Role checks in code are generally a reflection of an implicit role. You can view patient data because you have the <em>administrator</em> role. You can create an account because you have the <em>bank teller</em> role. The fact that these names exist does not have a correlation to what the software can actually do. Most people use roles in this manner. It is easiest but it can create a lot of maintenance and management problems for all the but the simplest application.</p> + +<h4><a name="JavaAuthorizationGuide-ExplicitRoles"></a>Explicit Roles</h4> +<p>An explicit role has permissions <em>explicitly</em> assigned to it and therefore is an <em>explicit</em> collection of permissions. Permission checks in code are a reflection of an explicit role. You can view patient data because because you have the <em>view patient data</em> permission as part of your <em>administrator</em> role. You can create an account because you have the <em>create account</em> permission as part of your <em>bank teller</em> role. You can perform these actions, not because of some implicit role name based on a string but because the corresponding permission was explicitly assigned to your role.</p> + +<p>The big benefits of explicit roles are easier manageability and lower maintenance of your application. If you ever need to add, remove, or change a role, you can do so without touching your source code. And in Shiro, you'll also be able to dynamically add, remove, or change roles at runtime and your authorization checks will always have up to date values. This means you won't have to force users to log out and log back in order to get their new permissions.</p> + +<h3><a name="JavaAuthorizationGuide-UsersDefined"></a>Users Defined</h3> +<p>A user is the "who" of an application. In Shiro, though, the concept of a user is really the <a href="subject.html" title="Subject">Subject</a> instance. We use word Subject instead of user because user usually implies a human being and in Shiro a Subject can be anything interacting with your application-- whether it be a human or a service. </p> + +<p>Users are allowed to perform certain actions in your application through their association with roles or direct permissions. So you are able to open a customer record because you've been assigned the <em>open customer record</em> permission, either through a role you've been assigned or through a direct permission assignment.</p> + +<p>For more information on Users, aka Subjects, please check out the <a href="subject.html" title="Subject">Subject Documentation</a>.</p> + +#info('Note', 'Ultimately, your <a href="realm.html" title="Realm">Realm</a> implementation is what communicates with your data source (RDBMS, LDAP, etc). So your realm is what will tell Shiro whether or not roles or permissions exist. You have full control over how your authorization model works.') + +<h2><a name="JavaAuthorizationGuide-HowtoperformAuthorizationinJavawithShiro"></a>How to perform Authorization in Java with Shiro</h2> +<p>Authorization in Shiro can be handled in four ways.</p> + +<ul><li>Programmatically - You can perform authorization checks in your java code with structures like <tt>if</tt> and <tt>else</tt> blocks.</li><li>JDK annotations - You can attach an authorization annotation to your Java methods</li><li>JSP/GSP TagLibs - You can control jsp or gsp page output based on roles and permissions</li></ul> + + +<h3><a name="JavaAuthorizationGuide-ProgrammaticAuthorization"></a>Programmatic Authorization</h3> +<p>Checking for permissions and roles, programmatically in your Java code is the traditional way of handling authorization. Here's how you can perform a permission check or role check in Shiro.</p> + +<h4><a name="JavaAuthorizationGuide-RoleCheck"></a>Role Check</h4> +<p>This is an example of how you do a role check programmatically in your application. We want to check if a user has the <em>administrator</em> role and if they do, then we'll show a special button, otherwise we won't show it.</p> + +<p>First we get access to the current user, the <a href="subject.html" title="Subject">Subject</a>. Then we pass the <em>adminstrator</em> to the Subject's <tt><a class="external-link" href="static/current/apidocs/org/apache/shiro/subject/Subject.html\#hasRole(java.lang.String)">.hasRole()</a></tt> method. It will return <tt>TRUE</tt> or <tt>FALSE</tt>. </p> + +<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> +<pre class="code-java"> +<span class="code-comment">//get the current Subject +</span>Subject currentUser = + SecurityUtils.getSubject(); + +<span class="code-keyword">if</span> (currentUser.hasRole(“administrator”)) { + <span class="code-comment">//show a special button‏ +</span>} <span class="code-keyword">else</span> { + <span class="code-comment">//don’t show the button?)‏ +</span>} +</pre> +</div></div> + +<p>Now a role based check is quick and easy to implement but it has a major drawback. It is implicit.</p> + +<p>What if you just want to add, remove, or redefine a role later? You'll have to crack open your source code and change all your role checks to reflect the change in your security model. You'll have to shut down the application, crack open the code, test it, and then restart it everytime. </p> + +<p>In very simple applications this is probably good enough but for larger apps this can be a major problem throughout the life of your application and drive a large maintenance cost for your software. </p> + +<h4><a name="JavaAuthorizationGuide-PermissionCheck"></a>Permission Check</h4> +<p>This is an example of how you do security checks by permission. We want to check if a user has permission to print to laserjet3000n and if they do, then we'll show a print button, otherwise we won't show it. This is an example of an instance level permission or instance level authorization.</p> + +<p>Again, first you get access to the current user, the <a href="subject.html" title="Subject">Subject</a>. Then you construct a <tt><a class="external-link" href="static/current/apidocs/org/apache/shiro/authz/Permission.html">Permission</a></tt> object or an instance that represents an action on a resource. In this case, the instance is named <tt>printerPermission</tt>, the resource is <em>laserjet3000n</em>, and the action is <em>print</em>. Then we pass <tt>printerPermission</tt> to the Subject's <tt><a class="external-link" href="static/current/apidocs/org/apache/shiro/subject/Subject.html\#isPermitted(java.util.List)">.isPermitted()</a></tt> method. It will return true or false. </p> + +<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> +<pre class="code-java"> +Subject currentUser = + SecurityUtils.getSubject(); + +Permission printPermission = +<span class="code-keyword">new</span> PrinterPermission(“laserjet3000n”,“print”); + +If (currentUser.isPermitted(printPermission)) { + <span class="code-comment">//<span class="code-keyword">do</span> one thing (show the print button?)‏ +</span>} <span class="code-keyword">else</span> { + <span class="code-comment">//don’t show the button? +</span>} +</pre> +</div></div> + +<h4><a name="JavaAuthorizationGuide-PermissionCheck%28Stringbased%29"></a>Permission Check (String-based)</h4> +<p>You can also a permission check using a simple string instead of a permission class.</p> + +<p>So, if you don't want to implement our <a class="external-link" href="static/current/apidocs/org/apache/shiro/authz/Permission.html">permission interface</a> then you just pass in a String. In this example, we pass the <tt>.isPermitted()</tt> method a string, <tt>printer:print:LaserJet4400n</tt></p> + +<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> +<pre class="code-java"> +<span class="code-object">String</span> perm = “printer:print:laserjet4400n”; + +<span class="code-keyword">if</span>(currentUser.isPermitted(perm)){ + <span class="code-comment">//show the print button? +</span>} <span class="code-keyword">else</span> { + <span class="code-comment">//don’t show the button? +</span>} +</pre> +</div></div> + +<p>You can construct the permission string the way you want so long as your <a href="realm.html" title="Realm">Realm</a> knows how to work with it. In this example we use Shiro's optional permission syntax, <a href="permissions.html" title="Permissions">WildCardPermissions</a>. WildCardPermissions are powerful and intuitive. If you'd like to learn more about them then check out the <a class="external-link" href="static/current/apidocs/org/apache/shiro/authz/Permission.html">Permissions Documentation</a>.</p> + +<p>With string-based permission checks, you get the same functionality as the example before. The benefit is that you are not forced to implement a permission interface and you can construct the permission via a simple string. The downside is that you don't have type safety and if you needed more complicated permission capabilitues that are outside the scope of what this represents, you're going to want to implement your own permission objects based on the permission interface.</p> + +<h3><a name="JavaAuthorizationGuide-AnnotationAuthorization"></a>Annotation Authorization</h3> + +<p>If you don't want to do code level authorization checks, then you can use Java Annotations as well. Shiro offers a number of <a href="java-annotations-list.html" title="Java Annotations List">Java annotations</a> that allow you to annotate methods. </p> + +<h4><a name="JavaAuthorizationGuide-EnablingAnnotationSupport"></a>Enabling Annotation Support</h4> +<p>Before you can use Java annotations, you'll need to enable AOP support in your application. There are a number of different AOP frameworks so, unfortunately, there is no standard way to enable AOP in an application.</p> + +<p>For AspectJ, you can review our <a class="external-link" href="https://github.com/apache/shiro/tree/master/samples/aspectj";>AspectJ sample application</a>.</p> + +<p>For Spring, you can look into our <a href="spring.html" title="Spring">Spring Integration</a> documentation.</p> + +<p>For Guice, you can look into our <a href="guice.html" title="Guice">Guice Integration</a> documentation.</p> + +<h4><a name="JavaAuthorizationGuide-PermissionCheck"></a>Permission Check</h4> +<p>In this example, we want to check that a user has the <tt>account:create</tt> permission before they can invoke the <tt>openAccount</tt> method. If they do, then the method is called as expected, and if they don't, then an exception is thrown. </p> + +<p>Like programmatic checks, you can use the <a class="external-link" href="static/current/apidocs/org/apache/shiro/authz/Permission.html">Permission</a> objects or the simple string methods with this annotation.</p> + +<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> +<pre class="code-java"> +<span class="code-comment">//Will <span class="code-keyword">throw</span> an AuthorizationException <span class="code-keyword">if</span> none +</span><span class="code-comment">//of the caller’s roles imply the Account +</span><span class="code-comment">//'create' permission� +</span>@RequiresPermissions(“account:create”)‏ +<span class="code-keyword">public</span> void openAccount( Account acct ) { + <span class="code-comment">//create the account +</span>} +</pre> +</div></div> + +<h4><a name="JavaAuthorizationGuide-RoleCheck"></a>Role Check</h4> +<p>In this example, we want to check that a user has the <tt>teller</tt> role before they can invoke the <tt>openAccount</tt> method. If they do, then the method is called as expected, and if they don't, then an exception is thrown.</p> + +<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> +<pre class="code-java"> +<span class="code-comment">//Throws an AuthorizationException <span class="code-keyword">if</span> the caller +</span><span class="code-comment">//doesn’t have the ‘teller’ role: +</span> +@RequiresRoles( “teller” ) +<span class="code-keyword">public</span> void openAccount( Account acct ) { + <span class="code-comment">//<span class="code-keyword">do</span> something in here that only a teller +</span> <span class="code-comment">//should <span class="code-keyword">do</span> +</span>} +</pre> +</div></div> + +<h3><a name="JavaAuthorizationGuide-JSPTagLibAuthorization"></a>JSP TagLib Authorization</h3> +<p>For JSP/GSP based web applications, Shiro also offers a <a href="jsp-tag-library.html" title="JSP Tag Library">tag library</a> for you to use. </p> + +<p>In this example, we're going to show users with the <em>users:manage</em> permission a link to the Manage Users page. If they do not have the permission, then we'll show them a nice message.</p> + +<p>First, we'll need to add the Shiro taglib to our web application. Next, we add the <tt><shiro:hasPermission></tt> tag with a check for <em>users:manage</em>. Within the <tt><shiro:hasPermission></tt> tags we will place the code we want to execute if the user has the permission we're checking for. If we want to take an action if the user lacks the permission, then we need to also add the <tt><shiro:lacksPermission></tt> tag, again checking for <em>users:manage</em>. And any code we want to excute if the user lacks the permission will need to be placed within the <tt><shiro:lacksPermission></tt> tags.</p> + +<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> +<pre class="code-java"> +<%@ taglib prefix=“shiro” uri=http:<span class="code-comment">//shiro.apache.org/tags %> +</span><html> +<body> + <shiro:hasPermission name=“users:manage”> + <a href=“manageUsers.jsp”> + Click here to manage users + </a> + </shiro:hasPermission> + <shiro:lacksPermission name=“users:manage”> + No user management <span class="code-keyword">for</span> you! + </shiro:lacksPermission> +</body> +</html> +</pre> +</div></div> + +<p>Of course, there also tags for checking roles and other user data and states.</p> + +<p>For more information on JSP/GSP Tags please check out the <a href="jsp-tag-library.html" title="JSP Tag Library">JSP Tag Library</a> and for more information on integration your application in your web application, please read the <a href="web.html" title="Web">Web Integration Documentation</a></p> + +<h2><a name="JavaAuthorizationGuide-CachingAuthorization"></a>Caching Authorization</h2> +<p>TBD</p> + +<h2><a name="JavaAuthorizationGuide-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>
http://git-wip-us.apache.org/repos/asf/shiro-site/blob/ddea166c/java-cryptography-guide.html ---------------------------------------------------------------------- diff --git a/java-cryptography-guide.html b/java-cryptography-guide.html deleted file mode 100644 index 67fbd6d..0000000 --- a/java-cryptography-guide.html +++ /dev/null @@ -1,95 +0,0 @@ -<h1><a name="JavaCryptographyGuide-JavaCryptographyGuidewithApacheShiro"></a>Java Cryptography Guide with Apache Shiro</h1> - - -<div class="addthis_toolbox addthis_default_style"> -<a class="addthis_button_compact" href="http://www.addthis.com/bookmark.php?v=250&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 protecting of information from undesired access by hiding it or converting it into nonsense so that no one can read it.</p> - -<p>Shiro is a major part of Shiro because we wanted to provide you with simplicity on what is typically a very complex topic. For example, the Java Cryptophay Environments (JCE) already handles cryptogrpahy in a Java environment but is very difficult to learn and use. So we grabbed the concepts made available by the JCE API and make them available to us mortals. In addition, all of the calls in the JCE are procedural which doesn't fit in Java's Object Oriented paradigm. So in Shiro, our cryptography features are all object oriented.</p> - -<h2><a name="JavaCryptographyGuide-ElementsofCryptography"></a>Elements of Cryptography</h2> -<p>Cryptogrpahy has two core elements in Shiro-- ciphers and hashes. </p> - -<h3><a name="JavaCryptographyGuide-CiphersDefined"></a>Ciphers Defined</h3> -<p>Ciphers are algorightms that can either encrypt or decrypt based on public or private key pair. And there are two different types of ciphers:</p> - -<ul class="alternate" type="square"><li>Symmetric Cipher - encrypts and decrypts using the same key.</li></ul> - - -<ul class="alternate" type="square"><li>Asymmetric Cipher - uses different keys for encryption and decryption.</li></ul> - - -<p>Both cipher type are support in Shiro.</p> - -<h3><a name="JavaCryptographyGuide-HashesDefined"></a>Hashes Defined</h3> -<p>A hash is a one-way irreversible conversion of an input source. In the JDK, a hash is referred to as a message digest. A cryptographic hash and a message digests are the same thing and both terms or correct.</p> - -<h4><a name="JavaCryptographyGuide-CommonusesforHashes"></a>Common uses for Hashes</h4> -<p>Hashes are often used to transforms credentials like passwords or biometric data. It's a one way transformation so you can never see what the original value was. This is a very safe way of storing passwords so that no one other than the user will ever know a password, even if your system is compromised.</p> - -<p>In addition, Shiro's hashes can be used with any type of data with an underlying byte array. Examples of this data include files, streams, byte arrays, strings, and character arrays.</p> - -<h2><a name="JavaCryptographyGuide-CipherFeatures"></a>Cipher Features</h2> -<h3><a name="JavaCryptographyGuide-Shiro%27sCipherServiceInterface"></a>Shiro's CipherService Interface</h3> -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -<span class="code-keyword">public</span> <span class="code-keyword">interface</span> CipherService { - - ByteSource encrypt( <span class="code-object">byte</span>[] raw, <span class="code-object">byte</span>[] key); - - void encrypt(InputStream in, OutputStream out, <span class="code-object">byte</span>[] key); - - ByteSource decrypt( <span class="code-object">byte</span>[] cipherText, <span class="code-object">byte</span>[] key); - - void decrypt(InputStream in, OutputStream out, <span class="code-object">byte</span>[] key); -} -</pre> -</div></div> - -<h2><a name="JavaCryptographyGuide-HashFeatures"></a>Hash Features</h2> -<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">Salts are important when hashing ...</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">Repeated hashes are important when hashing ...</td></tr></table></div> - -<h3><a name="JavaCryptographyGuide-Shiro%27sHashInterface"></a>Shiro's Hash Interface</h3> -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -<span class="code-keyword">public</span> <span class="code-keyword">interface</span> Hash { - <span class="code-object">byte</span>[] getBytes(); - <span class="code-object">String</span> toHex(); - <span class="code-object">String</span> toBase64(); -} -</pre> -</div></div> - -<h3><a name="JavaCryptographyGuide-ExamplesofhowtouseHashesinyourcode"></a>Examples of how to use Hashes in your code</h3> -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -<span class="code-comment">//some examples: -</span><span class="code-keyword">new</span> Md5Hash(“foo”).toHex(); - -<span class="code-comment">//File MD5 Hash value <span class="code-keyword">for</span> checksum: -</span><span class="code-keyword">new</span> MD5Hash( aFile ).toHex(); - -<span class="code-comment">//store a password, but not raw: -</span><span class="code-keyword">new</span> Sha256(aPassword, salt, - 1024).toBase64(); -</pre> -</div></div> - -<h2><a name="JavaCryptographyGuide-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 http://git-wip-us.apache.org/repos/asf/shiro-site/blob/ddea166c/java-cryptography-guide.html.vtl ---------------------------------------------------------------------- diff --git a/java-cryptography-guide.html.vtl b/java-cryptography-guide.html.vtl new file mode 100644 index 0000000..6707406 --- /dev/null +++ b/java-cryptography-guide.html.vtl @@ -0,0 +1,95 @@ +<h1><a name="JavaCryptographyGuide-JavaCryptographyGuidewithApacheShiro"></a>Java Cryptography Guide with Apache Shiro</h1> + + +<div class="addthis_toolbox addthis_default_style"> +<a class="addthis_button_compact" href="http://www.addthis.com/bookmark.php?v=250&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 protecting of information from undesired access by hiding it or converting it into nonsense so that no one can read it.</p> + +<p>Shiro is a major part of Shiro because we wanted to provide you with simplicity on what is typically a very complex topic. For example, the Java Cryptophay Environments (JCE) already handles cryptogrpahy in a Java environment but is very difficult to learn and use. So we grabbed the concepts made available by the JCE API and make them available to us mortals. In addition, all of the calls in the JCE are procedural which doesn't fit in Java's Object Oriented paradigm. So in Shiro, our cryptography features are all object oriented.</p> + +<h2><a name="JavaCryptographyGuide-ElementsofCryptography"></a>Elements of Cryptography</h2> +<p>Cryptogrpahy has two core elements in Shiro-- ciphers and hashes. </p> + +<h3><a name="JavaCryptographyGuide-CiphersDefined"></a>Ciphers Defined</h3> +<p>Ciphers are algorightms that can either encrypt or decrypt based on public or private key pair. And there are two different types of ciphers:</p> + +<ul class="alternate" type="square"><li>Symmetric Cipher - encrypts and decrypts using the same key.</li></ul> + + +<ul class="alternate" type="square"><li>Asymmetric Cipher - uses different keys for encryption and decryption.</li></ul> + + +<p>Both cipher type are support in Shiro.</p> + +<h3><a name="JavaCryptographyGuide-HashesDefined"></a>Hashes Defined</h3> +<p>A hash is a one-way irreversible conversion of an input source. In the JDK, a hash is referred to as a message digest. A cryptographic hash and a message digests are the same thing and both terms or correct.</p> + +<h4><a name="JavaCryptographyGuide-CommonusesforHashes"></a>Common uses for Hashes</h4> +<p>Hashes are often used to transforms credentials like passwords or biometric data. It's a one way transformation so you can never see what the original value was. This is a very safe way of storing passwords so that no one other than the user will ever know a password, even if your system is compromised.</p> + +<p>In addition, Shiro's hashes can be used with any type of data with an underlying byte array. Examples of this data include files, streams, byte arrays, strings, and character arrays.</p> + +<h2><a name="JavaCryptographyGuide-CipherFeatures"></a>Cipher Features</h2> +<h3><a name="JavaCryptographyGuide-Shiro%27sCipherServiceInterface"></a>Shiro's CipherService Interface</h3> +<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> +<pre class="code-java"> +<span class="code-keyword">public</span> <span class="code-keyword">interface</span> CipherService { + + ByteSource encrypt( <span class="code-object">byte</span>[] raw, <span class="code-object">byte</span>[] key); + + void encrypt(InputStream in, OutputStream out, <span class="code-object">byte</span>[] key); + + ByteSource decrypt( <span class="code-object">byte</span>[] cipherText, <span class="code-object">byte</span>[] key); + + void decrypt(InputStream in, OutputStream out, <span class="code-object">byte</span>[] key); +} +</pre> +</div></div> + +<h2><a name="JavaCryptographyGuide-HashFeatures"></a>Hash Features</h2> +#tip('Tip', 'Salts are important when hashing ...') + +#tip('Tip', 'Repeated hashes are important when hashing ...') + +<h3><a name="JavaCryptographyGuide-Shiro%27sHashInterface"></a>Shiro's Hash Interface</h3> +<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> +<pre class="code-java"> +<span class="code-keyword">public</span> <span class="code-keyword">interface</span> Hash { + <span class="code-object">byte</span>[] getBytes(); + <span class="code-object">String</span> toHex(); + <span class="code-object">String</span> toBase64(); +} +</pre> +</div></div> + +<h3><a name="JavaCryptographyGuide-ExamplesofhowtouseHashesinyourcode"></a>Examples of how to use Hashes in your code</h3> +<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> +<pre class="code-java"> +<span class="code-comment">//some examples: +</span><span class="code-keyword">new</span> Md5Hash(“foo”).toHex(); + +<span class="code-comment">//File MD5 Hash value <span class="code-keyword">for</span> checksum: +</span><span class="code-keyword">new</span> MD5Hash( aFile ).toHex(); + +<span class="code-comment">//store a password, but not raw: +</span><span class="code-keyword">new</span> Sha256(aPassword, salt, + 1024).toBase64(); +</pre> +</div></div> + +<h2><a name="JavaCryptographyGuide-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 http://git-wip-us.apache.org/repos/asf/shiro-site/blob/ddea166c/performing-a-release.html ---------------------------------------------------------------------- diff --git a/performing-a-release.html b/performing-a-release.html deleted file mode 100644 index 032022d..0000000 --- a/performing-a-release.html +++ /dev/null @@ -1,98 +0,0 @@ -<h2><a name="PerformingaRelease-CreatetheReleaseandVote"></a>Create the Release and Vote</h2> - -<ol><li>Ensure you are using JDK 1.6 (1.7 will not work) and Maven 3.0.3 (or later) for the following steps.</li><li>Run Apache RAT to ensure that we're Apache compliant: -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -> mvn apache-rat:check -</pre> -</div></div> -<p>Resolve any errors as necessary (usually amounts to placing the ASF license header at the top of files).</p></li><li>Execute the maven commands below to go through the release process. If there are any errors that you can't resolve, contact the <tt>[email protected]</tt> mailing list. -<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>GPG Installed</b><br clear="none">This release process requires the <tt>gpg</tt> binary to be in your command $PATH and your code signing key configured for your account.</td></tr></table></div> -<p>Commands:</p> -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -> mvn clean install -Pdocs,apache-release -> mvn release:prepare -DdryRun=<span class="code-keyword">true</span> -> mvn deploy -Pdocs -> mvn release:clean -> mvn release:prepare -Dusername=YOUR_ASF_USERNAME -Dpassword=YOUR_ASF_PASSWORD -> mvn release:perform -Dusername=YOUR_ASF_USERNAME -Dpassword=YOUR_ASF_PASSWORD -</pre> -</div></div></li><li>Log in to <a class="external-link" href="https://repository.apache.org";>https://repository.apache.org</a>. Navigate to "Staging Repositories" (on the left nav panel). Find the repository starting with 'org.apache.shiro' and <tt>close</tt> it.</li><li>Send out the VOTE email to the <tt>[email protected]</tt> mailing list. Here's a good template: -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -This is a call to vote in favor of releasing Apache Shiro version 1.2.0. - -The 59 issues solved <span class="code-keyword">for</span> 1.2.0: - -https:<span class="code-comment">//issues.apache.org/jira/secure/IssueNavigator!executeAdvanced.jspa?jqlQuery=project+%3D+SHIRO+AND+fixVersion+%3D+%221.2.0%22+AND+%28status+%21%3D+Open+and+status+%21%3D+%22In+Progress%22%29+ORDER+BY+priority+DESC&runQuery=<span class="code-keyword">true</span>&clear=<span class="code-keyword">true</span> -</span> -The tag to be voted upon: -<GIT_URL_OF_THE_RELEASE_TAG> (e.g. https:<span class="code-comment">//github.com/apache/shiro/tree/1.2.0) -</span> -Staging repo <span class="code-keyword">for</span> binaries: -<URL_OF_THE_CLOSED_REPO_FROM_ABOVE_STEP> (e.g. https:<span class="code-comment">//repository.apache.org/content/repositories/orgapacheshiro-92/) -</span> -Project website (just <span class="code-keyword">for</span> informational purposes, not to be voted upon): -http:<span class="code-comment">//shiro.apache.org/ -</span>and maven <span class="code-keyword">static</span> generated site (<span class="code-keyword">for</span> informational purposes, not to be voted upon): -people.apache.org:/www/shiro.apache.org/<span class="code-keyword">static</span>/1.2.0 or http:<span class="code-comment">//shiro.apache.org/<span class="code-keyword">static</span>/1.2.0 (once it propagates to web servers) -</span> -Guide to testing staged releases: -http:<span class="code-comment">//maven.apache.org/guides/development/guide-testing-releases.html -</span> -Vote open <span class="code-keyword">for</span> 72 hours. Please <span class="code-keyword">do</span> examine the source and binaries before voting. - -[ ] +1 -[ ] +0 -[ ] -1 (please include reasoning) -</pre> -</div></div></li></ol> - - -<h2><a name="PerformingaRelease-AfteraSuccessfulVote"></a>After a Successful Vote</h2> - -<ol><li>Update the <a class="external-link" href="https://github.com/apache/shiro/blob/master/shiro.doap.rdf";>Shiro DOAP file in git</a> to include another release information chunk (<em>after</em> the other similar chunks): -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-xml"> -<span class="code-tag"><release></span> - <span class="code-tag"><Version></span> - <span class="code-tag"><name></span>Apache Shiro VERSION<span class="code-tag"></name></span> - <span class="code-tag"><created></span>RELEASE_DATE<span class="code-tag"></created></span> - <span class="code-tag"><revision></span>VERSION<span class="code-tag"></revision></span> - <span class="code-tag"></Version></span> -<span class="code-tag"></release></span> -</pre> -</div></div> -<p><br clear="none" class="atl-forced-newline"> -With the appropriate <tt>RELEASE_DATE</tt> (e.g. 2011-10-01) and <tt>VERSION</tt> (e.g. 1.1.0). Save and commit the file to Git. -<br clear="none" class="atl-forced-newline"> -<br clear="none" class="atl-forced-newline"></p></li><li>Put the distribution on the ASF web servers - <ol><li>SSH into people.apache.org and cd to to Shiro's distribution location: -<br clear="none" class="atl-forced-newline"> -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java">cd /www/www.apache.org/dist/shiro</pre> -</div></div></li><li>Create a subdirectory for the specific version number released: -<br clear="none" class="atl-forced-newline"> -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java">mkdir 1.2.1</pre> -</div></div></li><li>Acquire the source release .zip and it's verifying files (.md5, .sha1, .asc, .asc.md5, .asc.sha1) from <a class="external-link" href="https://repository.apache.org";>https://repository.apache.org</a> -<br clear="none" class="atl-forced-newline"> -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java">wget --no-check-certificate https:<span class="code-comment">//repository.apache.org/content/groups/<span class="code-keyword">public</span>/org/apache/shiro/shiro-root/<version>/shiro-root-<version>-source-release.zip -</span>wget --no-check-certificate https:<span class="code-comment">//repository.apache.org/content/groups/<span class="code-keyword">public</span>/org/apache/shiro/shiro-root/<version>/shiro-root-<version>-source-release.zip.md5 -</span>wget --no-check-certificate https:<span class="code-comment">//repository.apache.org/content/groups/<span class="code-keyword">public</span>/org/apache/shiro/shiro-root/<version>/shiro-root-<version>-source-release.zip.sha1 -</span>wget --no-check-certificate https:<span class="code-comment">//repository.apache.org/content/groups/<span class="code-keyword">public</span>/org/apache/shiro/shiro-root/<version>/shiro-root-<version>-source-release.zip.asc -</span>wget --no-check-certificate https:<span class="code-comment">//repository.apache.org/content/groups/<span class="code-keyword">public</span>/org/apache/shiro/shiro-root/<version>/shiro-root-<version>-source-release.zip.asc.md5 -</span>wget --no-check-certificate https:<span class="code-comment">//repository.apache.org/content/groups/<span class="code-keyword">public</span>/org/apache/shiro/shiro-root/<version>/shiro-root-<version>-source-release.zip.asc.sha1</span></pre> -</div></div></li></ol> - </li><li>Update the Shiro wiki's <a href="download.html" title="Download">Download</a> page to include a new entry for 1.2.1</li><li>Update the Shiro wiki's <a href="index.html" title="Index">Index</a> page and update the download 'block'.  This must be done via the Wiki Markup View so JavaScript can be edited.</li><li>Make an announcement as a Shiro blog article. You can look at <a class="external-link" href="2012/01/24/apache-shiro-120-released.html">a previous announcement</a> as an example.</li><li>Make the same announcement on the Shiro user list (subject: [ANNOUNCE] Apache Shiro <version> released) and CC the developer list.</li><li>Update the <a class="external-link" href="http://en.wikipedia.org/wiki/Apache_Shiro"; rel="nofollow">Apache Shiro Wikipedia page</a> to reflect the latest release information.</li><li>Update the 'current' symbolic link on people.apache.org to reference the latest static site documentation. For exampl e (replace <b>1.2.1</b> with the latest version): -<br clear="none" class="atl-forced-newline"> -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -$ ssh people.apache.org -$ cd /www/apache.shiro.org/<span class="code-keyword">static</span> -$ rm current -$ ln -s 1.2.1 current -</pre> -</div></div></li></ol> http://git-wip-us.apache.org/repos/asf/shiro-site/blob/ddea166c/performing-a-release.html.vtl ---------------------------------------------------------------------- diff --git a/performing-a-release.html.vtl b/performing-a-release.html.vtl new file mode 100644 index 0000000..24096db --- /dev/null +++ b/performing-a-release.html.vtl @@ -0,0 +1 @@ +#redirect('https://cwiki.apache.org/confluence/display/SHIRO/Performing+a+Release', 'https://cwiki.apache.org/confluence/display/SHIRO/Performing+a+Release') \ No newline at end of file http://git-wip-us.apache.org/repos/asf/shiro-site/blob/ddea166c/quickstart.html ---------------------------------------------------------------------- diff --git a/quickstart.html b/quickstart.html deleted file mode 100644 index 1030b09..0000000 --- a/quickstart.html +++ /dev/null @@ -1,3 +0,0 @@ -<p>This page has been moved. You are being redirected.</p> - -<p></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>Redirection Notice</b><br clear="none">This page should redirect to <a href="10-minute-tutorial.html" title="10 Minute Tutorial">10 Minute Tutorial</a>.</td></tr></table></div> \ No newline at end of file http://git-wip-us.apache.org/repos/asf/shiro-site/blob/ddea166c/quickstart.html.vtl ---------------------------------------------------------------------- diff --git a/quickstart.html.vtl b/quickstart.html.vtl new file mode 100644 index 0000000..266a47b --- /dev/null +++ b/quickstart.html.vtl @@ -0,0 +1 @@ +#redirect('10-minute-tutorial.html', '10 Minute Tutorial') \ No newline at end of file http://git-wip-us.apache.org/repos/asf/shiro-site/blob/ddea166c/realm.html ---------------------------------------------------------------------- diff --git a/realm.html b/realm.html deleted file mode 100644 index 6c05d18..0000000 --- a/realm.html +++ /dev/null @@ -1,218 +0,0 @@ -<h1><a name="Realm-ApacheShiroRealms"></a>Apache Shiro Realms</h1> - -<div class="toc"> -<ul><li><a href="#Realm-RealmConfiguration">Realm Configuration</a></li><ul><li><a href="#Realm-ExplicitAssignment">Explicit Assignment</a></li><li><a href="#Realm-ImplicitAssignment">Implicit Assignment</a></li></ul><li><a href="#Realm-RealmAuthentication">Realm Authentication</a></li><ul><li><a href="#Realm-Supporting%7B%7BAuthenticationTokens%7D%7D">Supporting <tt>AuthenticationTokens</tt></a></li><li><a href="#Realm-Handlingsupported%7B%7BAuthenticationTokens%7D%7D">Handling supported <tt>AuthenticationTokens</tt></a></li><li><a href="#Realm-CredentialsMatching">Credentials Matching</a></li><ul><li><a href="#Realm-SimpleEqualityCheck">Simple Equality Check</a></li><li><a href="#Realm-HashingCredentials">Hashing Credentials</a></li><ul><li><a href="#Realm-HashingandCorrespondingMatchers">Hashing and Corresponding Matchers</a></li><ul><li><a href="#Realm-%7B%7BSaltedAuthenticationInfo%7D%7D"> <tt>SaltedAuthenticationInfo</tt></a></li></ul></ul></ul><li><a href="#Realm-DisablingAut hentication">Disabling Authentication</a></li></ul><li><a href="#Realm-RealmAuthorization">Realm Authorization</a></li><li><a href="#Realm-Lendahandwithdocumentation">Lend a hand with documentation</a></li></ul></div> - -<p>A <tt>Realm</tt> is a component that can access application-specific security data such as users, roles, and permissions. The <tt>Realm</tt> translates this application-specific data into a format that Shiro understands so Shiro can in turn provide a single easy-to-understand <a href="subject.html" title="Subject">Subject</a> programming API no matter how many data sources exist or how application-specific your data might be.</p> - -<p>Realms usually have a 1-to-1 correlation with a data source such as a relational database, LDAP directory, file system, or other similar resource. As such, implementations of the <tt>Realm</tt> interface use data source-specific APIs to discover authorization data (roles, permissions, etc), such as JDBC, File IO, Hibernate or JPA, or any other Data Access API. </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">A Realm is essentially a security-specific <a class="external-link" href="http://en.wikipedia.org/wiki/Data_Access_Object"; rel="nofollow">DAO</a></td></tr></table></div> - -<p>Because most of these data sources usually store both authentication data (credentials such as passwords) as well as authorization data (such as roles or permissions), every Shiro <tt>Realm</tt> can perform <em>both</em> authentication and authorization operations.</p> - -<h2><a name="Realm-RealmConfiguration"></a>Realm Configuration</h2> - -<p>If using Shiro's INI configuration, you define and reference <tt>Realms</tt> like any other object in the <tt>[main]</tt> section, but they are configured on the <tt>securityManager</tt> in one of two ways: explicitly or implicitly.</p> - -<h3><a name="Realm-ExplicitAssignment"></a>Explicit Assignment</h3> - -<p>Based on knowledge of INI configuration thus far, this is an obvious configuration approach. After defining one or more Realms, you set them as a collection property on the <tt>securityManager</tt> object.</p> - -<p>For example:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -fooRealm = com.company.foo.Realm -barRealm = com.company.another.Realm -bazRealm = com.company.baz.Realm - -securityManager.realms = $fooRealm, $barRealm, $bazRealm -</pre> -</div></div> - -<p>Explicit assignment is deterministic - you control exactly which realms are used as well as <em>the order</em> that they will be used for authentication and authorization. Realm ordering effects are described in detail in the Authentication chapter's <a href="authentication.html#Authentication-sequence">Authentication Sequence</a> section. </p> - -<h3><a name="Realm-ImplicitAssignment"></a>Implicit Assignment</h3> - -<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>Not Preferred</b><br clear="none">Implicit assignment can cause unexpected behavior if you change the order in which realms are defined. It is recommended that you avoid this approach and use Explicit Assignment, which has deterministic behavior. It is likely Implicit Assignment will be deprecated/removed from a future Shiro release.</td></tr></table></div> - -<p>If for some reason you don't want to explicitly configure the <tt>securityManager.realms</tt> property, you can allow Shiro to detect all configured realms and assign them to the <tt>securityManager</tt> directly.</p> - -<p>Using this approach, realms are assigned to the <tt>securityManager</tt> instance in the <em>order that they are defined</em>.</p> - -<p>That is, for the following <tt>shiro.ini</tt> example:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -blahRealm = com.company.blah.Realm -fooRealm = com.company.foo.Realm -barRealm = com.company.another.Realm - -# no securityManager.realms assignment here -</pre> -</div></div> - -<p>basically has the same effect as if the following line were appended:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -securityManager.realms = $blahRealm, $fooRealm, $barRealm -</pre> -</div></div> - -<p>However, realize that with implicit assignment, just the order that the realms are defined directly affects how they are consulted during authentication and authorization attempts. If you change their definition order, you will change how the master <tt>Authenticator</tt>'s <a href="authentication.html#Authentication-sequence">Authentication Sequence</a> functions.</p> - -<p>For this reason, and to ensure deterministic behavior, we recommend using Explicit Assignment instead of Implicit Assignment. <br clear="none"> -<a name="Realm-authentication"></a></p> -<h2><a name="Realm-RealmAuthentication"></a>Realm Authentication</h2> - -<p>Once you understand Shiro's master <a href="authentication.html#Authentication-sequence">Authentication workflow</a>, it is important to know exactly what happens when the <tt>Authenticator</tt> interacts with a <tt>Realm</tt> during an authentication attempt.</p> - -<h3><a name="Realm-Supporting%7B%7BAuthenticationTokens%7D%7D"></a>Supporting <tt>AuthenticationTokens</tt></h3> - -<p>As mentioned in the <a href="authentication.html#Authentication-sequence">authentication sequence</a>, just before a <tt>Realm</tt> is consulted to perform an authentication attempt, its <tt><a class="external-link" href="static/current/apidocs/org/apache/shiro/realm/Realm.html#supports(org.apache.shiro.authc.AuthenticationToken)">supports</a></tt> method is called. If the return value is <tt>true</tt>, only then will its <tt>getAuthenticationInfo(token)</tt> method be invoked.</p> - -<p>Typically a realm will check the type (interface or class) of the submitted token to see if it can process it. For example, a Realm that processes biometric data may not understand <tt>UsernamePasswordTokens</tt> at all, in which case it would return <tt>false</tt> from the <tt>supports</tt> method.</p> - -<h3><a name="Realm-Handlingsupported%7B%7BAuthenticationTokens%7D%7D"></a>Handling supported <tt>AuthenticationTokens</tt></h3> - -<p>If a <tt>Realm</tt> <tt>supports</tt> a submitted <tt>AuthenticationToken</tt>, the <tt>Authenticator</tt> will call the Realm's <a class="external-link" href="static/current/apidocs/org/apache/shiro/realm/Realm.html#getAuthenticationInfo(org.apache.shiro.authc.AuthenticationToken)">getAuthenticationInfo(token)</a> method. This effectively represents an authentication attempt with the <tt>Realm's</tt> backing data source. The method, in order:</p> - -<ol><li>Inspects the <tt>token</tt> for the identifying principal (account identifying information)</li><li>Based on the <tt>principal</tt>, looks up corresponding account data in the data source</li><li>Ensures that the token's supplied <tt>credentials</tt> matches those stored in the data store</li><li>If the credentials match, an <a class="external-link" href="static/current/apidocs/org/apache/shiro/authc/AuthenticationInfo.html">AuthenticationInfo</a> instance is returned that encapsulates the account data in a format Shiro understands</li><li>If the credentials DO NOT match, an <a class="external-link" href="static/current/apidocs/org/apache/shiro/authc/AuthenticationException.html">AuthenticationException</a> is thrown</li></ol> - - -<p>This is the highest-level workflow for all Realm <tt>getAuthenticationInfo</tt> implementations. Realms are free to do whatever they want during this method, such as record the attempt in an audit log, update data records, or anything else that makes sense for the authentication attempt for that data store.</p> - -<p>The only thing required is that, if the credentials match for the given principal(s), that a non-null <tt>AuthenticationInfo</tt> instance is returned that represents Subject account information from that data source.</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>Save Time</b><br clear="none">Implementing <tt><a class="external-link" href="static/current/apidocs/org/apache/shiro/realm/Realm.html">Realm</a></tt> interface directly might be time consuming and error prone. Most people choose to subclass the <a class="external-link" href="static/current/apidocs/org/apache/shiro/realm/AuthorizingRealm.html">AuthorizingRealm</a> abstract class instead of starting from scratch. This class implements common authentication and authorization workflow to save you time and effort.</td></tr></table></div> - -<h3><a name="Realm-CredentialsMatching"></a>Credentials Matching</h3> - -<p>In the above realm authentication workflow, a Realm has to verify that the <a href="subject.html" title="Subject">Subject</a>'s submitted credentials (e.g. password) must match the credentials stored in the data store. If they match, authentication is considered successful, and the system has verified the end-user's identity.</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>Realm Credentials Matching</b><br clear="none">It is each Realm's responsibility to match submitted credentials with those stored in the Realm's backing data store, and not the <tt>Authenticator's</tt> responsibility. Each <tt>Realm</tt> has intimate knowledge of credentials format and storage and can perform detailed credentials matching, whereas the <tt>Authenticator</tt> is a generic workflow component.</td></tr></table></div> - -<p>The credentials matching process is nearly identical in all applications and usually only differs by the data compared. To ensure this process is pluggable and customizable if necessary, the <a class="external-link" href="static/current/apidocs/org/apache/shiro/realm/AuthenticatingRealm.html">AuthenticatingRealm</a> and its subclasses support the concept of a <a class="external-link" href="static/current/apidocs/org/apache/shiro/authc/credential/CredentialsMatcher.html">CredentialsMatcher</a> to perform the credentials comparison.</p> - -<p>After discovering account data, it and the submitted <tt>AuthenticationToken</tt> are presented to a <tt>CredentialsMatcher</tt> to see if what was submitted matches what is stored in the data store. </p> - -<p>Shiro has some <tt>CredentialsMatcher</tt> implementations to get you started out of the box, such as the <a class="external-link" href="static/current/apidocs/org/apache/shiro/authc/credential/SimpleCredentialsMatcher.html">SimpleCredentialsMatcher</a> and <a class="external-link" href="static/current/apidocs/org/apache/shiro/authc/credential/HashedCredentialsMatcher.html">HashedCredentialsMatcher</a> implementations, but if you wanted to configure a custom implementation for custom matching logic, you could do so directly:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -Realm myRealm = <span class="code-keyword">new</span> com.company.shiro.realm.MyRealm(); -CredentialsMatcher customMatcher = <span class="code-keyword">new</span> com.company.shiro.realm.CustomCredentialsMatcher(); -myRealm.setCredentialsMatcher(customMatcher); -</pre> -</div></div> - -<p>Or, if using Shiro's INI <a href="configuration.html" title="Configuration">configuration</a>:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -[main] -... -customMatcher = com.company.shiro.realm.CustomCredentialsMatcher -myRealm = com.company.shiro.realm.MyRealm -myRealm.credentialsMatcher = $customMatcher -... -</pre> -</div></div> - - -<h4><a name="Realm-SimpleEqualityCheck"></a>Simple Equality Check</h4> - -<p>All of Shiro's out-of-the-box <tt>Realm</tt> implementations default to using a <a class="external-link" href="static/current/apidocs/org/apache/shiro/authc/credential/SimpleCredentialsMatcher.html">SimpleCredentialsMatcher</a>. The <tt>SimpleCredentialsMatcher</tt> performs a plain direct equality check of the stored account credentials with what was submitted in the <tt>AuthenticationToken</tt>.</p> - -<p>For example, if a <a class="external-link" href="static/current/apidocs/org/apache/shiro/authc/UsernamePasswordToken.html">UsernamePasswordToken</a> was submitted, the <tt>SimpleCredentialsMatcher</tt> verifies that the password submitted is exactly equal to the password stored in the database.</p> - -<p>The <tt>SimpleCredentialsMatcher</tt> performs direct equality comparisons for more than just Strings though. It can work with most common byte sources, such as Strings, character arrays, byte arrays, Files and InputStreams. See its JavaDoc for more.</p> - -<h4><a name="Realm-HashingCredentials"></a>Hashing Credentials</h4> - -<p>Instead of storing credentials in their raw form and performing raw/plain comparisons, a much more secure way of storing end-user's credentials (e.g. passwords) is to one-way hash them first before storing them in the data store. </p> - -<p>This ensures that end-users' credentials are never stored in their raw form and that no one can know the original/raw value. This is a much more secure mechanism than plain-text or raw comparisons, and all security-conscious applications should favor this approach over non-hashed storage.</p> - -<p>To support these preferred cryptographic hashing strategies, Shiro provides <a class="external-link" href="static/current/apidocs/org/apache/shiro/authc/credential/HashedCredentialsMatcher.html">HashedCredentialsMatcher</a> implementations to be configured on realms instead of the aforementioned <tt>SimpleCredentialsMatcher</tt>.</p> - -<p>Hashing credentials and the benefits of salting and multiple hash iterations are outside the scope of this <tt>Realm</tt> documentation, but definitely read the <a class="external-link" href="static/current/apidocs/org/apache/shiro/authc/credential/HashedCredentialsMatcher.html">HashedCredentialsMatcher JavaDoc</a> which covers these principles in detail.</p> - -<h5><a name="Realm-HashingandCorrespondingMatchers"></a>Hashing and Corresponding Matchers</h5> - -<p>So how do you configure a Shiro-enabled application to do this easily?</p> - -<p>Shiro provides multiple <tt>HashedCredentialsMatcher</tt> subclass implementations. You must configure the specific implementation on your realm to match the hashing algorithm you use to hash your users' credentials.</p> - -<p>For example, let's say your application uses username/password pairs for authentication. And due to the benefits of hashing credentials described above, let's say you want to one-way hash a user's password using the <a class="external-link" href="http://en.wikipedia.org/wiki/SHA_hash_functions"; rel="nofollow">SHA-256</a> algorithm when you create a user account. You would hash the user's entered plain-text password and save that value:</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.crypto.hash.Sha256Hash; -<span class="code-keyword">import</span> org.apache.shiro.crypto.RandomNumberGenerator; -<span class="code-keyword">import</span> org.apache.shiro.crypto.SecureRandomNumberGenerator; -... - -<span class="code-comment">//We'll use a Random <span class="code-object">Number</span> Generator to generate salts. This -</span><span class="code-comment">//is much more secure than using a username as a salt or not -</span><span class="code-comment">//having a salt at all. Shiro makes <span class="code-keyword">this</span> easy. -</span><span class="code-comment">// -</span><span class="code-comment">//Note that a normal app would reference an attribute rather -</span><span class="code-comment">//than create a <span class="code-keyword">new</span> RNG every time: -</span>RandomNumberGenerator rng = <span class="code-keyword">new</span> SecureRandomNumberGenerator(); -<span class="code-object">Object</span> salt = rng.nextBytes(); - -<span class="code-comment">//Now hash the plain-text password with the random salt and multiple -</span><span class="code-comment">//iterations and then Base64-encode the value (requires less space than Hex): -</span><span class="code-object">String</span> hashedPasswordBase64 = <span class="code-keyword">new</span> Sha256Hash(plainTextPassword, salt, 1024).toBase64(); - -User user = <span class="code-keyword">new</span> User(username, hashedPasswordBase64); -<span class="code-comment">//save the salt with the <span class="code-keyword">new</span> account. The HashedCredentialsMatcher -</span><span class="code-comment">//will need it later when handling login attempts: -</span>user.setPasswordSalt(salt); -userDAO.create(user); -</pre> -</div></div> - -<p>Since you're <tt>SHA-256</tt> hashing your user's passwords, you need to tell Shiro to use the appropriate <tt>HashedCredentialsMatcher</tt> to match your hashing preferences. In this example, we create a random salt and perform 1024 hash iterations for strong security (see the <tt>HashedCredentialsMatcher</tt> JavaDoc for why). Here is the Shiro INI configuration to make this work:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -[main] -... -credentialsMatcher = org.apache.shiro.authc.credential.Sha256CredentialsMatcher -# base64 encoding, not hex in <span class="code-keyword">this</span> example: -credentialsMatcher.storedCredentialsHexEncoded = <span class="code-keyword">false</span> -credentialsMatcher.hashIterations = 1024 -# This next property is only needed in Shiro 1.0. Remove it in 1.1 and later: -credentialsMatcher.hashSalted = <span class="code-keyword">true</span> - -... -myRealm = com.company..... -myRealm.credentialsMatcher = $credentialsMatcher -... -</pre> -</div></div> - -<h6><a name="Realm-%7B%7BSaltedAuthenticationInfo%7D%7D"></a><tt>SaltedAuthenticationInfo</tt></h6> - -<p>The last thing to do to ensure this works is that your <tt>Realm</tt> implementation must return a <a class="external-link" href="static/current/apidocs/org/apache/shiro/authc/SaltedAuthenticationInfo.html">SaltedAuthenticationInfo</a> instance instead of a normal <tt>AuthenticationInfo</tt> one. The <tt>SaltedAuthenticationInfo</tt> interface ensures that the salt that you used when you created the user account (e.g. the <tt>user.setPasswordSalt(salt);</tt> call above) can be referenced by the <tt>HashedCredentialsMatcher</tt>.</p> - -<p>The <tt>HashedCredentialsMatcher</tt> needs the salt in order to perform the same hashing technique on the submitted <tt>AuthenticationToken</tt> to see if the token matches what you saved in the data store. So if you use salting for user passwords (and you should!!!), ensure your <tt>Realm</tt> implementation represents that by returning <tt>SaltedAuthenticationInfo</tt> instances.</p> - -<h3><a name="Realm-DisablingAuthentication"></a>Disabling Authentication</h3> - -<p>If for some reason, you don't want a Realm to perform authentication for a data source (maybe because you only want the Realm to perform authorization), you can disable a Realm's support for authentication entirely by always returning <tt>false</tt> from the Realm's <tt>supports</tt> method. Then your realm will never be consulted during an authentication attempt. </p> - -<p>Of course at least one configured <tt>Realm</tt> needs to be able to support AuthenticationTokens if you want to authenticate Subjects. </p> - -<h2><a name="Realm-RealmAuthorization"></a>Realm Authorization</h2> -<p>TBD</p> - -<h2><a name="Realm-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
![https://cwiki.apache.org/confluence/images/icons/emoticons/check.gif"](https://cwiki.apache.org/confluence/images/icons/emoticons/check.gif"){kind=link}
![https://cwiki.apache.org/confluence/images/icons/emoticons/information.gif"](https://cwiki.apache.org/confluence/images/icons/emoticons/information.gif"){kind=link}
![https://cwiki.apache.org/confluence/images/icons/emoticons/warning.gif"](https://cwiki.apache.org/confluence/images/icons/emoticons/warning.gif"){kind=link}
![https://cwiki.apache.org/confluence/images/icons/emoticons/forbidden.gif"](https://cwiki.apache.org/confluence/images/icons/emoticons/forbidden.gif"){kind=link}