java-cryptography-guide.html

<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&amp;pubid=ra-4d66ef016022c3bd">Share</a>
<span class="addthis_separator">|</span>
<a class="addthis_button_preferred_1"></a>
<a class="addthis_button_preferred_2"></a>
<a class="addthis_button_preferred_3"></a>
<a class="addthis_button_preferred_4"></a>
</div>
<script type="text/javascript">var addthis_config = {"data_track_clickback":true};</script>
<script type="text/javascript" src="http://s7.addthis.com/js/250/addthis_widget.js#pubid=ra-4d66ef016022c3bd"></script>


<p><br clear="none" class="atl-forced-newline">
Cryptography is the 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(&#8220;foo&#8221;).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>