converted a few more pages to markdown
Project: http://git-wip-us.apache.org/repos/asf/shiro-site/repo Commit: http://git-wip-us.apache.org/repos/asf/shiro-site/commit/9dd8d51b Tree: http://git-wip-us.apache.org/repos/asf/shiro-site/tree/9dd8d51b Diff: http://git-wip-us.apache.org/repos/asf/shiro-site/diff/9dd8d51b Branch: refs/heads/master Commit: 9dd8d51b2addb40688204fab7d91210ab4f1d2f5 Parents: 864e50c Author: Brian Demers <[email protected]> Authored: Fri Oct 21 22:29:01 2016 -0400 Committer: Brian Demers <[email protected]> Committed: Fri Oct 21 22:29:01 2016 -0400 ---------------------------------------------------------------------- cachemanager.md | 1 - sessionmanager.html | 7 -- sessionmanager.html.vtl | 1 + sharing-block-small.html | 5 - sharing-block.html | 10 -- shiroConfluenceAutoExportTemplate.vhtml.txt | 127 ----------------------- site.html | 1 - siteheader.html | 18 ---- team.html | 3 - team.md | 4 + templates/macros/sharing-block.vtl | 12 +++ terminology.html | 85 --------------- terminology.md | 81 +++++++++++++++ tools.html | 1 - tools.md | 1 + what-is-shiro.html | 43 -------- what-is-shiro.md | 66 ++++++++++++ wiki-todos.html | 11 -- wiki-todos.md | 12 +++ 19 files changed, 177 insertions(+), 312 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/shiro-site/blob/9dd8d51b/cachemanager.md ---------------------------------------------------------------------- diff --git a/cachemanager.md b/cachemanager.md index c20a8e1..729939c 100644 --- a/cachemanager.md +++ b/cachemanager.md @@ -39,4 +39,3 @@ Finally note that [`AuthorizingRealm`](static/current/apidocs/org/apache/shiro/r While we hope this documentation helps you with the work you're doing with Apache Shiro, the community is improving and expanding the documentation all the time. If you'd like to help the Shiro project, please consider corrected, expanding, or adding documentation where you see a need. Every little bit of help you provide expands the community and in turn improves Shiro. The easiest way to contribute your documentation is to send it to the <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>. - \ No newline at end of file http://git-wip-us.apache.org/repos/asf/shiro-site/blob/9dd8d51b/sessionmanager.html ---------------------------------------------------------------------- diff --git a/sessionmanager.html b/sessionmanager.html deleted file mode 100644 index 4f40f67..0000000 --- a/sessionmanager.html +++ /dev/null @@ -1,7 +0,0 @@ -<p>TODO</p> - -<h2><a name="SessionManager-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/9dd8d51b/sessionmanager.html.vtl ---------------------------------------------------------------------- diff --git a/sessionmanager.html.vtl b/sessionmanager.html.vtl new file mode 100644 index 0000000..25810a9 --- /dev/null +++ b/sessionmanager.html.vtl @@ -0,0 +1 @@ +#redirect('session-management.html', 'Session Management') \ No newline at end of file http://git-wip-us.apache.org/repos/asf/shiro-site/blob/9dd8d51b/sharing-block-small.html ---------------------------------------------------------------------- diff --git a/sharing-block-small.html b/sharing-block-small.html deleted file mode 100644 index 8f4b498..0000000 --- a/sharing-block-small.html +++ /dev/null @@ -1,5 +0,0 @@ -<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> -</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> http://git-wip-us.apache.org/repos/asf/shiro-site/blob/9dd8d51b/sharing-block.html ---------------------------------------------------------------------- diff --git a/sharing-block.html b/sharing-block.html deleted file mode 100644 index bd12a79..0000000 --- a/sharing-block.html +++ /dev/null @@ -1,10 +0,0 @@ -<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> http://git-wip-us.apache.org/repos/asf/shiro-site/blob/9dd8d51b/shiroConfluenceAutoExportTemplate.vhtml.txt ---------------------------------------------------------------------- diff --git a/shiroConfluenceAutoExportTemplate.vhtml.txt b/shiroConfluenceAutoExportTemplate.vhtml.txt deleted file mode 100644 index 992c8df..0000000 --- a/shiroConfluenceAutoExportTemplate.vhtml.txt +++ /dev/null @@ -1,127 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd";> -<!-- - Licensed to the Apache Software Foundation (ASF) under one or more - contributor license agreements. See the NOTICE file distributed with - this work for additional information regarding copyright ownership. - The ASF licenses this file to You under the Apache License, Version 2.0 - (the "License"); you may not use this file except in compliance with - the License. You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. ---> -## -#set ($assets = "http://incubator.apache.org/shiro/static/assets";) -#set ($images = "http://incubator.apache.org/shiro/static/assets/images";) -#set ($siteroot = "http://incubator.apache.org/shiro/";) -#set ($pageContentHeaderEnabled = false) -#set ($globalHelper = $action.getHelper()) -#set ($renderer = $globalHelper.getWikiStyleRenderer()) -## -#if ( $page.title.equals("Index") ) - #set ($title = "Simple Application Security Framework") -#else - #set ($title = $page.title) -#end -## -<html> -<head> - <meta http-equiv="Content-Type" content="text/html;charset=UTF-8"> - <title>Apache Shiro - $title</title> - <link href="$assets/common_20100327.css" rel="stylesheet" type="text/css"> - <link href="$assets/color_20100327.css" rel="stylesheet" type="text/css"> - <!-- <link rel="shortcut icon" href="$assets/images/shiro-icon_16x16.png"> --> - <link rel="alternate" type="application/rss+xml" title="RSS" - href="http://cwiki.apache.org/shiro/createrssfeed.action?types=blogpost&statuses=created&statuses=modified&spaces=SHIRO&labelString=&rssType=rss2&maxResults=5&timeSpan=99&publicFeed=true&title=Apache+Shiro+News+RSS+Feed";> - - <!-- JQuery inclusion --> - <script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.2.6/jquery.min.js";></script> - <!-- Loading the script for the edit button --> - <script type="text/javascript"> - $(document).ready(function() { - - $("#editZone").hover(function() { - $("#editZoneLink").stop().animate({opacity: 1}, 1000, function() { - $("#editZoneLink").fadeIn(); - }); - }, - function () { - $("#editZoneLink").stop().fadeOut(); - }); - }); - </script> - <!-- END JQuery inclusion --> - -</head> -<body> -<div id="editZone"> - <div id="editZoneLink" style="display: none; height: 60px; width: 60px;"> - <a href="$confluenceUri/pages/editpage.action?pageId=$page.id" title="Edit this page" alt="Edit this page"> - <img style="position: absolute; right:5px; top:5px;" src="$assets/images/edit_20091029.png" - height="52" width="39" border="0"/> - </a> - </div> -</div> -<a name="top"></a> - -<div id="container"> - - <div id="header"> - <div id="subProjectsNavBar"> - </div> - <!-- end subProjectsNavBar --> - </div> - <!-- end header --> - - <div id="content"> - - <div id="leftColumn"> - <div id="navigation"> - #set($child = $pageManager.getPage($page.space.key,"Navigation")) - #set($content = $renderer.convertWikiToXHtml($child.toPageContext(), $child.content).trim()) - #set($content = $content.replaceAll("^<[pP]>|</[pP]>$", "") ) - $content - </div> - <!-- end navigation --> - </div> - <!-- end leftColumn --> - - <div id="rightColumn"> - $body - </div> - <!-- end rightColumn --> - - <div id="endContent"> - </div> - <!-- end endContent --> - - </div> - <!-- end content --> - - <div id="footer">© 2003-2010, <a href="http://www.apache.org";>The Apache Software Foundation</a> - - <a href="$siteroot/privacy-policy.html">Privacy Policy</a> - </div> - <!-- end footer --> -</div> -<!-- end container --> - -<!-- Google Analytics --> -<script type="text/javascript"> - var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl."; : "http://www.";); - document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E")); -</script> -<script type="text/javascript"> - try { - var pageTracker = _gat._getTracker("UA-11551827-1"); - pageTracker._trackPageview(); - } catch(err) { - } -</script> -<!-- END Google Analytics --> -</body> -</html> http://git-wip-us.apache.org/repos/asf/shiro-site/blob/9dd8d51b/site.html ---------------------------------------------------------------------- diff --git a/site.html b/site.html deleted file mode 100644 index 06e11b6..0000000 --- a/site.html +++ /dev/null @@ -1 +0,0 @@ -<ul><li><a href="banner.html" title="Banner">Banner</a></li><li><a href="sharing-block.html" title="Sharing Block">Sharing Block</a></li><li><a href="siteheader.html" title="SiteHeader">SiteHeader</a></li></ul> \ No newline at end of file http://git-wip-us.apache.org/repos/asf/shiro-site/blob/9dd8d51b/siteheader.html ---------------------------------------------------------------------- diff --git a/siteheader.html b/siteheader.html deleted file mode 100644 index 6599598..0000000 --- a/siteheader.html +++ /dev/null @@ -1,18 +0,0 @@ -<a href="http://shiro.apache.org";></a><div id="logo"></div> - <div id="navigation"> - <a href="download.html"> - </a><div class="navigation-button">Get Started</div> - - <a href="documentation.html"> - </a><div class="navigation-button">Get Docs</div> - - <a href="support.html"> - </a><div class="navigation-button">Get Help</div> - - <a href="commercial-support.html"> - </a><div class="navigation-button">Get Support</div> - - </div> - <div id="secondary-navigation"> - <ul><li><a href="documentation.html">Documentation</a></li><li><a href="news.html">News</a></li><li><a href="events.html">Events</a></li><li><a href="http://twitter.com/ApacheShiro/";>Twitter</a></li><li><a href="mailing-lists.html">Mailing lists</a></li><li><a href="contribute.html">Contribute</a></li></ul> - </div> http://git-wip-us.apache.org/repos/asf/shiro-site/blob/9dd8d51b/team.html ---------------------------------------------------------------------- diff --git a/team.html b/team.html deleted file mode 100644 index 9eca1eb..0000000 --- a/team.html +++ /dev/null @@ -1,3 +0,0 @@ -<h1><a name="Team-ApacheShiroTeam"></a>Apache Shiro Team</h1> - -<p>TODO: list dev team members here</p> \ No newline at end of file http://git-wip-us.apache.org/repos/asf/shiro-site/blob/9dd8d51b/team.md ---------------------------------------------------------------------- diff --git a/team.md b/team.md new file mode 100644 index 0000000..a6fe3f6 --- /dev/null +++ b/team.md @@ -0,0 +1,4 @@ +#Apache Shiro Team + +TODO: list dev team members here + http://git-wip-us.apache.org/repos/asf/shiro-site/blob/9dd8d51b/templates/macros/sharing-block.vtl ---------------------------------------------------------------------- diff --git a/templates/macros/sharing-block.vtl b/templates/macros/sharing-block.vtl new file mode 100644 index 0000000..89c6ae7 --- /dev/null +++ b/templates/macros/sharing-block.vtl @@ -0,0 +1,12 @@ +#macro($share) + <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> +#end http://git-wip-us.apache.org/repos/asf/shiro-site/blob/9dd8d51b/terminology.html ---------------------------------------------------------------------- diff --git a/terminology.html b/terminology.html deleted file mode 100644 index 15db476..0000000 --- a/terminology.html +++ /dev/null @@ -1,85 +0,0 @@ -<h1><a name="Terminology-ApacheShiroTerminology"></a>Apache Shiro Terminology</h1> - -<p>Please just take 2 minutes to read and understand this - it is <em>really</em> important. Really. The terms and concepts here are referred to everywhere in the documentation and it will <em>greatly</em> simplify your understanding of Shiro and security in general.</p> - -<p>Security can be really confusing because of the terminology used. We'll make life easier by clarifying some core concepts and you'll see how nicely the Shiro API reflects them:</p> - -<p><a name="Terminology-authentication"></a></p> -<ul><li><b>Authentication</b><br clear="none"> -Authentication is the process of verifying a Subject's identity - essentially proving that someone really is who they say they are. When an authentication attempt is successful the application can trust that the subject is guaranteed to be who the application expects. -<br clear="none" class="atl-forced-newline"> -<br clear="none" class="atl-forced-newline"> -<a name="Terminology-authorization"></a></li><li><b>Authorization</b><br clear="none"> -Authorization, also known as Access Control, is the process of determining if a user/Subject is allowed to do something or not. It is usually accomplished by inspecting and interpreting a Subject's roles and permissions (see below) and then allowing or denying access to a requested resource or function. -<br clear="none" class="atl-forced-newline"> -<br clear="none" class="atl-forced-newline"> -<a name="Terminology-cipher"></a></li><li><b>Cipher</b><br clear="none"> -A cipher is an algorithm for performing encryption or decryption. The algorithm generally relies on a piece of information called a key. And the encryption varies based on the key so decyrption is extremely difficult without it. -<br clear="none" class="atl-forced-newline"> -<br clear="none" class="atl-forced-newline"> -Ciphers come in different variations. Block Ciphers work on blocks of symbols usually of a fixed size while Stream Ciphers work on a continuous stream of symbols. Symmetric Ciphers use the same key for encryption and decryption while Asymmetric Ciphers use different keys. And if a key in an asymmetric cipher cannot be derived from the other, then one can be shared publicly creating public/private key pairs. -<br clear="none" class="atl-forced-newline"> -<br clear="none" class="atl-forced-newline"> -<a name="Terminology-credential"></a></li><li><b>Credential</b><br clear="none"> -A <em>Credential</em> is a piece of information that verifies the identity of a user/Subject. One (or more) credentials are submitted along with Principal(s) during an authentication attempt to verify that the user/Subject submitting them is actually the associated user. Credentials are usually very secret things that only a particular user/Subject would know, such as a password or a PGP key or biometric attribute or similar mechanism. -<br clear="none" class="atl-forced-newline"> -<br clear="none" class="atl-forced-newline"> -The idea is that for a principal, only one person would know the correct credential to 'pair' with that principal. If the current user/Subject provides the correct credential matching the one stored in the system, then the system can assume and trust that the current user/Subject is really who they say they are. The degree of trust increases with more secure credential types (e.g. biometric signature > password). -<br clear="none" class="atl-forced-newline"> -<br clear="none" class="atl-forced-newline"> -<a name="Terminology-cryptography"></a></li><li><b>Cryptography</b><br clear="none"> -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. -<br clear="none" class="atl-forced-newline"> -<br clear="none" class="atl-forced-newline"> -<a name="Terminology-hash"></a></li><li><b>Hash</b><br clear="none"> -A Hash function is a one-way, irreversible conversion of an input source, sometimes called the message, into an encoded hash value, sometimes called the message digest. It is often used for passwords, digital fingerprints, or data with an underlying byte array. -<br clear="none" class="atl-forced-newline"> -<br clear="none" class="atl-forced-newline"> -<a name="Terminology-permission"></a></li><li><b>Permission</b><br clear="none"> -A Permission, at least as Shiro interprets it, is a statement that describes raw functionality in an application and nothing more. Permissions are the lowest-level constructs in security policies. They define only "What" the application can do. They do not describe "Who" is able to perform the actions. A Permission is only a statement of behavior, nothing more. -<br clear="none" class="atl-forced-newline"> -<br clear="none" class="atl-forced-newline"> -Some examples of permissions: - <ul><li>Open a file</li><li>View the '/user/list' web page</li><li>Print documents</li><li>Delete the 'jsmith' user -<br clear="none" class="atl-forced-newline"> -<br clear="none" class="atl-forced-newline"> -<a name="Terminology-principal"></a></li></ul> - </li><li><b>Principal</b><br clear="none"> -A <em>Principal</em> is any identifying attribute of an application user (Subject). An 'identifying attribute' can be anything that makes sense to your application - a username, a surname, a given name, a social security number, a user ID, etc. That's it - nothing crazy. -<br clear="none" class="atl-forced-newline"> -<br clear="none" class="atl-forced-newline"> -Shiro also references something we call a <tt>Subject</tt>'s <em>primary</em> principal. A <em>Primary</em> principal is any principal that uniquely identifies the <tt>Subject</tt> across the entire application. Ideal primary principals are things like a username or a user ID that is a RDBMS user table primary key. There is only one primary principal for users (Subjects) in an application. -<br clear="none" class="atl-forced-newline"> -<br clear="none" class="atl-forced-newline"> -<a name="Terminology-realm"></a></li><li><b>Realm</b><br clear="none"> -A Realm is a component that can access application-specific security data such as users, roles, and permissions. It can be thought of as a security-specific DAO (Data Access Object). The Realm translates this application-specific data into a format that Shiro understands so Shiro can in turn provide a single easy-to-understand Subject programming API no matter how many data sources exist or how application-specific your data might be. -<br clear="none" class="atl-forced-newline"> -<br clear="none" class="atl-forced-newline"> -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 Realm 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. -<br clear="none" class="atl-forced-newline"> -<br clear="none" class="atl-forced-newline"> -<a name="Terminology-role"></a></li><li><b>Role</b><br clear="none"> -The definition of a Role can vary based on who you talk to. In many applications it is nebulous concept at best that people use to implicitly define security policies. Shiro prefers to interpret a Role as simply a named collection of Permissions. That's it - an application unique name aggregating one or more Permission declarations. -<br clear="none" class="atl-forced-newline"> -<br clear="none" class="atl-forced-newline"> -This is a more concrete definition than the implicit one used by many applications. If you choose to have your data model reflect Shiro's assumption, you'll find you will have much more power in controlling security policies. -<br clear="none" class="atl-forced-newline"> -<br clear="none" class="atl-forced-newline"> -<a name="Terminology-session"></a></li><li><b>Session</b><br clear="none"> -A Session is a stateful data context associated with a single user/Subject who interacts with a software system over a period of time. Data can be added/read/removed from the Session while the subject uses the application and the application can use this data later where necessary. Sessions are terminated when the user/Subject logs out of the application or when it times out due to inactivity. -<br clear="none" class="atl-forced-newline"> -<br clear="none" class="atl-forced-newline"> -For those familiar with the HttpSession, a Shiro <tt>Session</tt> serves the same purpose, except Shiro sessions can be used in any environment even if there is no Servlet container or EJB container available. -<br clear="none" class="atl-forced-newline"> -<br clear="none" class="atl-forced-newline"> -<a name="Terminology-subject"></a></li><li><b>Subject</b><br clear="none"> -A <em>Subject</em> is just fancy security term that basically means a security-specific 'view' of an application user. A Subject does not always need to reflect a human being though - it can represent an external process calling your application, or perhaps a daemon system account that executes something intermittently over a period of time (such as a cron job). It is basically a representation of any entity that is doing something with the application. -<br clear="none" class="atl-forced-newline"> -<br clear="none" class="atl-forced-newline"></li></ul> - - -<h2><a name="Terminology-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/9dd8d51b/terminology.md ---------------------------------------------------------------------- diff --git a/terminology.md b/terminology.md new file mode 100644 index 0000000..d26154a --- /dev/null +++ b/terminology.md @@ -0,0 +1,81 @@ +<a name="Terminology-ApacheShiroTerminology"></a> +#Apache Shiro Terminology + +Please just take 2 minutes to read and understand this - it is <em>really</em> important. Really. The terms and concepts here are referred to everywhere in the documentation and it will <em>greatly</em> simplify your understanding of Shiro and security in general. + +Security can be really confusing because of the terminology used. We'll make life easier by clarifying some core concepts and you'll see how nicely the Shiro API reflects them: + +<a name="Terminology-authentication"></a> +* **Authentication** +Authentication is the process of verifying a Subject's identity - essentially proving that someone really is who they say they are. When an authentication attempt is successful the application can trust that the subject is guaranteed to be who the application expects. + +<a name="Terminology-authorization"></a> +* **Authorization** +Authorization, also known as Access Control, is the process of determining if a user/Subject is allowed to do something or not. It is usually accomplished by inspecting and interpreting a Subject's roles and permissions (see below) and then allowing or denying access to a requested resource or function. + +<a name="Terminology-cipher"></a> +* **Cipher** +A cipher is an algorithm for performing encryption or decryption. The algorithm generally relies on a piece of information called a key. And the encryption varies based on the key so decyrption is extremely difficult without it. + + Ciphers come in different variations. Block Ciphers work on blocks of symbols usually of a fixed size while Stream Ciphers work on a continuous stream of symbols. Symmetric Ciphers use the same key for encryption and decryption while Asymmetric Ciphers use different keys. And if a key in an asymmetric cipher cannot be derived from the other, then one can be shared publicly creating public/private key pairs. + +<a name="Terminology-credential"></a> +* **Credential** +A <em>Credential</em> is a piece of information that verifies the identity of a user/Subject. One (or more) credentials are submitted along with Principal(s) during an authentication attempt to verify that the user/Subject submitting them is actually the associated user. Credentials are usually very secret things that only a particular user/Subject would know, such as a password or a PGP key or biometric attribute or similar mechanism. + + The idea is that for a principal, only one person would know the correct credential to 'pair' with that principal. If the current user/Subject provides the correct credential matching the one stored in the system, then the system can assume and trust that the current user/Subject is really who they say they are. The degree of trust increases with more secure credential types (e.g. biometric signature > password). + +<a name="Terminology-cryptography"></a> +* **Cryptography** +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. + +<a name="Terminology-hash"></a> +* **Hash** +A Hash function is a one-way, irreversible conversion of an input source, sometimes called the message, into an encoded hash value, sometimes called the message digest. It is often used for passwords, digital fingerprints, or data with an underlying byte array. + +<a name="Terminology-permission"></a> +* **Permission** +A Permission, at least as Shiro interprets it, is a statement that describes raw functionality in an application and nothing more. Permissions are the lowest-level constructs in security policies. They define only "What" the application can do. They do not describe "Who" is able to perform the actions. A Permission is only a statement of behavior, nothing more. + + Some examples of permissions: + + - Open a file + - View the '/user/list' web page + - Print documents + - Delete the 'jsmith' user + +<a name="Terminology-principal"></a> +* **Principal** +A <em>Principal</em> is any identifying attribute of an application user (Subject). An 'identifying attribute' can be anything that makes sense to your application - a username, a surname, a given name, a social security number, a user ID, etc. That's it - nothing crazy. + + Shiro also references something we call a <tt>Subject</tt>'s <em>primary</em> principal. A <em>Primary</em> principal is any principal that uniquely identifies the <tt>Subject</tt> across the entire application. Ideal primary principals are things like a username or a user ID that is a RDBMS user table primary key. There is only one primary principal for users (Subjects) in an application. + +<a name="Terminology-realm"></a> +* **Realm** +A Realm is a component that can access application-specific security data such as users, roles, and permissions. It can be thought of as a security-specific DAO (Data Access Object). The Realm translates this application-specific data into a format that Shiro understands so Shiro can in turn provide a single easy-to-understand Subject programming API no matter how many data sources exist or how application-specific your data might be. + + 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 Realm 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. + +<a name="Terminology-role"></a> +* **Role** +The definition of a Role can vary based on who you talk to. In many applications it is nebulous concept at best that people use to implicitly define security policies. Shiro prefers to interpret a Role as simply a named collection of Permissions. That's it - an application unique name aggregating one or more Permission declarations. + + This is a more concrete definition than the implicit one used by many applications. If you choose to have your data model reflect Shiro's assumption, you'll find you will have much more power in controlling security policies. + +<a name="Terminology-session"></a> +* **Session** +A Session is a stateful data context associated with a single user/Subject who interacts with a software system over a period of time. Data can be added/read/removed from the Session while the subject uses the application and the application can use this data later where necessary. Sessions are terminated when the user/Subject logs out of the application or when it times out due to inactivity. + + For those familiar with the HttpSession, a Shiro <tt>Session</tt> serves the same purpose, except Shiro sessions can be used in any environment even if there is no Servlet container or EJB container available. + +<a name="Terminology-subject"></a> +* **Subject** +A <em>Subject</em> is just fancy security term that basically means a security-specific 'view' of an application user. A Subject does not always need to reflect a human being though - it can represent an external process calling your application, or perhaps a daemon system account that executes something intermittently over a period of time (such as a cron job). It is basically a representation of any entity that is doing something with the application. + + +<a name="Terminology-Lendahandwithdocumentation"></a> +###Lend a hand with documentation + +While we hope this documentation helps you with the work you're doing with Apache Shiro, the community is improving and expanding the documentation all the time. If you'd like to help the Shiro project, please consider corrected, expanding, or adding documentation where you see a need. Every little bit of help you provide expands the community and in turn improves Shiro. + +The easiest way to contribute your documentation is to send it to the <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>. http://git-wip-us.apache.org/repos/asf/shiro-site/blob/9dd8d51b/tools.html ---------------------------------------------------------------------- diff --git a/tools.html b/tools.html deleted file mode 100644 index a953ed3..0000000 --- a/tools.html +++ /dev/null @@ -1 +0,0 @@ -<p><a href="command-line-hasher.html" title="Command Line Hasher">Command Line Hasher</a></p> \ No newline at end of file http://git-wip-us.apache.org/repos/asf/shiro-site/blob/9dd8d51b/tools.md ---------------------------------------------------------------------- diff --git a/tools.md b/tools.md new file mode 100644 index 0000000..b19d151 --- /dev/null +++ b/tools.md @@ -0,0 +1 @@ +[Command Line Hasher](command-line-hasher.html) \ No newline at end of file http://git-wip-us.apache.org/repos/asf/shiro-site/blob/9dd8d51b/what-is-shiro.html ---------------------------------------------------------------------- diff --git a/what-is-shiro.html b/what-is-shiro.html deleted file mode 100644 index 833a788..0000000 --- a/what-is-shiro.html +++ /dev/null @@ -1,43 +0,0 @@ -<h1><a name="WhatisShiro-WhatisShiro%3F"></a>What is Shiro?</h1> - -<p>Apache Shiro is an application security framework that provides application developers very clean and simple ways of supporting four cornerstones of security in their applications: authentication, authorization, enterprise session management and cryptography.</p> - -<h2><a name="WhatisShiro-MissionStatement"></a>Mission Statement</h2> - -<p>We believe:</p> -<ul><li>Java security should be <em>really easy</em> to understand and use in your own applications.</li><li>Existing Java security mechanisms (like JAAS) are too confusing and fall way short in the area of application-level security.</li><li>Authentication and Authorization functionality should be as pluggable and flexible as possible.</li><li>Authentication and Authorization are only half of a robust security framework. Enterprise Session Management and easy Cryptography services are the the other half.</li><li><b>Session Management should not be tied to web or EJB applications</b>. We believe Sessions are a business-tier concern that should be accessible in any client or server environment.</li><li>Heterogeneous client mediums (HTTP requests, Applets, Java Web Start, C# applications, etc) should be able to participate in the same Session, regardless of the client technology.</li><li>Security code should be eliminated as much as possible in favor of a cleaner declarative security model utilizing JDK 1.5 Annotations or XML, whichever you prefer.</li><li>Last but definitely not least, a security framework should support a <em>dynamic</em>, <em>instance-level</em> security model out-of-the-box (i.e. changing user/group/role/permission assignments <em>during runtime</em>)</li></ul> - - -<p>We will:</p> -<ul><li>Create a security framework that is <em>extremely</em> easy to use and understand. An evaluating developer should grasp all the fundamentals within 10 minutes.</li><li>Employ an interface-driven POJO-based OO design with extreme flexibility, pluggability and customization in mind.</li><li>Develop a production-quality implementation that can be used in any deployment environment, from the simplest Applet to the largest high-availability clustered enterprise applications.</li><li>Foster a positive open-source developer community, listening to suggestions and requests in order to provide the highest quality security framework available for Java.</li></ul> - - -<h2><a name="WhatisShiro-ProjectHistory"></a>Project History</h2> -<p><em>by Les Hazlewood</em></p> - -<p>Apache Shiro, like most useful tools, was created out of necessity. About 20% of clients I worked with needed to support a <em>dynamic</em> security model, where an administrator could assign users to groups and roles, and assign permissions to roles, and change all of this during runtime in a nice gui and/or web page.</p> - -<p>Standard JAAS and EJB security models couldn't cut it - they required static definitions that only programmers could change, requiring the application to re-deployed all over again. And although those 20% of clients required dynamic functionality, there were many more that would have liked that capability, even though it wasn't a pure requirement for their applications. I quickly realized how useful something like this was and tried to see how I could achieve what many people wanted.</p> - -<p>Like most of the Java community, I looked into <a class="external-link" href="http://docs.oracle.com/javase/7/docs/technotes/guides/security/jaas/JAASRefGuide.html"; rel="nofollow">JAAS</a> to see if it could do what I wanted. After all, it was really the only security technology out there widely accessible to Java developers at the time. I did a <em>lot</em> of research, looking for ways that I might be able to coerce JAAS into doing what I wanted. Sometimes it came close. JAAS Authentication could meet my needs with a decent amount of effort, but JAAS Authorization didn't even come close.</p> - -<p>JAAS is tied too heavily tied to virtual machine-level concerns. As an application architect, I usually didn't care one bit about whether or not a <em>Class</em> could execute inside the virtual machine. What I really wanted to control is whether or not the <em>current user</em> could execute a given method, often based on the method's arguments. So, I hobbled a bit, creating some functionality to piggy-back JAAS and custom-coded the rest. The result was only usable on a few applications and wasn't nearly as robust as I wanted.</p> - -<p>Then I came to work on a really great application that pushed the limits of application security. This application was written for government organizations and needed <em>extremely</em> powerful yet flexible security support. The client required the following:</p> -<ul><li>Traditional log-in/log-out functionality, with pluggable back-end support (no big deal)</li><li>Customization of users, roles and permissions <em>during runtime</em> (a big deal)</li><li>The ability to restrict not only what functionality was available to a user, but also what was available <em>on the machine they were using</em> (flexible authorization model).</li><li>The ability to participate in the <em>same session</em> when visiting a web page, when using an embedded Java Applet, or when making a remote EJB call (a very big deal)</li><li>The ability to dynamically change the security model during runtime such that the following would be possible (this is really cool): - <ol><li>A user clicks a button that alters the state of a piece of hardware affecting a _lot_ of people.</li><li>An administrator determines the user is potentially a high-risk employee (disgruntled, unstable, whatever), and changes that user's permissions to prevent them from clicking that button again.</li><li>The very next instant, the same user clicks the same button again to alter the hardware's state (this time perhaps to do something that isn't very nice).</li><li>Because the user's permissions were changed, the second button click fails and shows them a nice error message explaining that they don't have permission for the operation.<br clear="none"> -All of this could happen without requiring the user to log-out and then log back in again to acquire a new set of roles and/or permissions. Security changes had to be <em>instantaneous</em>.</li></ol> - </li></ul> - - -<p>I looked at all of these requirements, and although a little extreme for most applications, I knew that there were a lot of other developers out there that could benefit from a framework that could do all of these things, even if they didn't use them all.</p> - -<p>I knew I would need to use this functionality again in some capacity or another, so I founded Apache Shiro's predecessor project, named 'JSecurity' in 2004 to solve all of these issues. This time though, the project team began to build an incredibly clean Object-Oriented architecture from scratch, keeping change and flexibility in mind. Nearly every facet of Authentication, Authorization, transparent Session Management and Cryptography are customizable and pluggable. After moving to the Apache Software Foundation, we renamed the project to Apache Shiro.</p> - -<p>Perhaps best of all, Apache Shiro is POJO and interface based. You can use it in any pojo container, servlet container, J2EE application server, or standalone application out of the box. And, we currently have some projects in the works to make integration into the most popular containers and servers as easy as possible.</p> - -<p>Well, that's how the JSecurity project and then Apache Shiro was started. We're always looking to improve. Since Shiro is open-source, please think about joining the project or helping out, even if you just offer suggestions. Anything is appreciated!</p> - -<p>Best regards,</p> - -<p>Les Hazlewood</p> \ No newline at end of file http://git-wip-us.apache.org/repos/asf/shiro-site/blob/9dd8d51b/what-is-shiro.md ---------------------------------------------------------------------- diff --git a/what-is-shiro.md b/what-is-shiro.md new file mode 100644 index 0000000..f9feadd --- /dev/null +++ b/what-is-shiro.md @@ -0,0 +1,66 @@ +<a name="WhatisShiro-WhatisShiro%3F"></a> +#What is Shiro? + +Apache Shiro is an application security framework that provides application developers very clean and simple ways of supporting four cornerstones of security in their applications: authentication, authorization, enterprise session management and cryptography. + +<a name="WhatisShiro-MissionStatement"></a> +##Mission Statement + +We believe: + +- Java security should be <em>really easy</em> to understand and use in your own applications. +- Existing Java security mechanisms (like JAAS) are too confusing and fall way short in the area of application-level security. +- Authentication and Authorization functionality should be as pluggable and flexible as possible. +- Authentication and Authorization are only half of a robust security framework. Enterprise Session Management and easy Cryptography services are the the other half. +- <b>Session Management should not be tied to web or EJB applications</b>. We believe Sessions are a business-tier concern that should be accessible in any client or server environment. +- Heterogeneous client mediums (HTTP requests, Applets, Java Web Start, C# applications, etc) should be able to participate in the same Session, regardless of the client technology. +- Security code should be eliminated as much as possible in favor of a cleaner declarative security model utilizing JDK 1.5 Annotations or XML, whichever you prefer. +- Last but definitely not least, a security framework should support a <em>dynamic</em>, <em>instance-level</em> security model out-of-the-box (i.e. changing user/group/role/permission assignments <em>during runtime</em>) + +We will: + +- Create a security framework that is <em>extremely</em> easy to use and understand. An evaluating developer should grasp all the fundamentals within 10 minutes. +- Employ an interface-driven POJO-based OO design with extreme flexibility, pluggability and customization in mind. +- Develop a production-quality implementation that can be used in any deployment environment, from the simplest Applet to the largest high-availability clustered enterprise applications. +- Foster a positive open-source developer community, listening to suggestions and requests in order to provide the highest quality security framework available for Java. + + +<a name="WhatisShiro-ProjectHistory"></a> +##Project History + +<em>by Les Hazlewood</em> + +Apache Shiro, like most useful tools, was created out of necessity. About 20% of clients I worked with needed to support a <em>dynamic</em> security model, where an administrator could assign users to groups and roles, and assign permissions to roles, and change all of this during runtime in a nice gui and/or web page. + +Standard JAAS and EJB security models couldn't cut it - they required static definitions that only programmers could change, requiring the application to re-deployed all over again. And although those 20% of clients required dynamic functionality, there were many more that would have liked that capability, even though it wasn't a pure requirement for their applications. I quickly realized how useful something like this was and tried to see how I could achieve what many people wanted. + +Like most of the Java community, I looked into [JAAS](http://docs.oracle.com/javase/7/docs/technotes/guides/security/jaas/JAASRefGuide.html) to see if it could do what I wanted. After all, it was really the only security technology out there widely accessible to Java developers at the time. I did a <em>lot</em> of research, looking for ways that I might be able to coerce JAAS into doing what I wanted. Sometimes it came close. JAAS Authentication could meet my needs with a decent amount of effort, but JAAS Authorization didn't even come close. + +JAAS is tied too heavily tied to virtual machine-level concerns. As an application architect, I usually didn't care one bit about whether or not a <em>Class</em> could execute inside the virtual machine. What I really wanted to control is whether or not the <em>current user</em> could execute a given method, often based on the method's arguments. So, I hobbled a bit, creating some functionality to piggy-back JAAS and custom-coded the rest. The result was only usable on a few applications and wasn't nearly as robust as I wanted. + +Then I came to work on a really great application that pushed the limits of application security. This application was written for government organizations and needed <em>extremely</em> powerful yet flexible security support. The client required the following: + +* Traditional log-in/log-out functionality, with pluggable back-end support (no big deal) +* Customization of users, roles and permissions <em>during runtime</em> (a big deal) +* The ability to restrict not only what functionality was available to a user, but also what was available <em>on the machine they were using</em> (flexible authorization model). +* The ability to participate in the <em>same session</em> when visiting a web page, when using an embedded Java Applet, or when making a remote EJB call (a very big deal) +* The ability to dynamically change the security model during runtime such that the following would be possible (this is really cool): + 1. A user clicks a button that alters the state of a piece of hardware affecting a _lot_ of people. + 2. An administrator determines the user is potentially a high-risk employee (disgruntled, unstable, whatever), and changes that user's permissions to prevent them from clicking that button again. + 3. The very next instant, the same user clicks the same button again to alter the hardware's state (this time perhaps to do something that isn't very nice). + 4. Because the user's permissions were changed, the second button click fails and shows them a nice error message explaining that they don't have permission for the operation. +All of this could happen without requiring the user to log-out and then log back in again to acquire a new set of roles and/or permissions. Security changes had to be <em>instantaneous</em>. + + + +I looked at all of these requirements, and although a little extreme for most applications, I knew that there were a lot of other developers out there that could benefit from a framework that could do all of these things, even if they didn't use them all. + +I knew I would need to use this functionality again in some capacity or another, so I founded Apache Shiro's predecessor project, named 'JSecurity' in 2004 to solve all of these issues. This time though, the project team began to build an incredibly clean Object-Oriented architecture from scratch, keeping change and flexibility in mind. Nearly every facet of Authentication, Authorization, transparent Session Management and Cryptography are customizable and pluggable. After moving to the Apache Software Foundation, we renamed the project to Apache Shiro. + +Perhaps best of all, Apache Shiro is POJO and interface based. You can use it in any pojo container, servlet container, J2EE application server, or standalone application out of the box. And, we currently have some projects in the works to make integration into the most popular containers and servers as easy as possible. + +Well, that's how the JSecurity project and then Apache Shiro was started. We're always looking to improve. Since Shiro is open-source, please think about joining the project or helping out, even if you just offer suggestions. Anything is appreciated! + +Best regards, + +Les Hazlewood \ No newline at end of file http://git-wip-us.apache.org/repos/asf/shiro-site/blob/9dd8d51b/wiki-todos.html ---------------------------------------------------------------------- diff --git a/wiki-todos.html b/wiki-todos.html deleted file mode 100644 index 7600799..0000000 --- a/wiki-todos.html +++ /dev/null @@ -1,11 +0,0 @@ -<h1><a name="WikiTodos-WikiTodos"></a>Wiki Todos</h1> -<p>Authentication Guide<br/> -Authorization Guide<br/> -Session Management Guide<br/> -Cryptography Guide</p> - -<p>Terminology Page </p> -<ul><li>Group terminology for easier reading</li><li>Add more terminology where needed</li></ul> - - -<p>Complete Reference Manual</p> \ No newline at end of file http://git-wip-us.apache.org/repos/asf/shiro-site/blob/9dd8d51b/wiki-todos.md ---------------------------------------------------------------------- diff --git a/wiki-todos.md b/wiki-todos.md new file mode 100644 index 0000000..6036bec --- /dev/null +++ b/wiki-todos.md @@ -0,0 +1,12 @@ +<a name="WikiTodos-WikiTodos"></a> +#Wiki Todos + +- Authentication Guide +- Authorization Guide +- Session Management Guide +- Cryptography Guide +- Terminology Page + - Group terminology for easier reading + - Add more terminology where needed + +Complete Reference Manual \ No newline at end of file
