| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> |
| <!-- NewPage --> |
| <html lang="en"> |
| <head> |
| <!-- Generated by javadoc (version 1.7.0_25) on Wed May 25 23:25:54 EDT 2016 --> |
| <meta http-equiv="Content-Type" content="text/html" charset="UTF-8"> |
| <title>CipherService (Apache Shiro 1.2.5 API)</title> |
| <meta name="date" content="2016-05-25"> |
| <link rel="stylesheet" type="text/css" href="../../../../stylesheet.css" title="Style"> |
| </head> |
| <body> |
| <script type="text/javascript"><!-- |
| if (location.href.indexOf('is-external=true') == -1) { |
| parent.document.title="CipherService (Apache Shiro 1.2.5 API)"; |
| } |
| //--> |
| </script> |
| <noscript> |
| <div>JavaScript is disabled on your browser.</div> |
| </noscript> |
| |
| <!-- ========= START OF TOP NAVBAR ======= --> |
| <div class="topNav"><a name="navbar_top"> |
| <!-- --> |
| </a><a href="#skip-navbar_top" title="Skip navigation links"></a><a name="navbar_top_firstrow"> |
| <!-- --> |
| </a> |
| <ul class="navList" title="Navigation"> |
| <li><a href="../../../../overview-summary.html">Overview</a></li> |
| <li><a href="package-summary.html">Package</a></li> |
| <li class="navBarCell1Rev">Class</li> |
| <li><a href="class-use/CipherService.html">Use</a></li> |
| <li><a href="package-tree.html">Tree</a></li> |
| <li><a href="../../../../deprecated-list.html">Deprecated</a></li> |
| <li><a href="../../../../index-all.html">Index</a></li> |
| <li><a href="../../../../help-doc.html">Help</a></li> |
| </ul> |
| </div> |
| <div class="subNav"> |
| <ul class="navList"> |
| <li><a href="../../../../org/apache/shiro/crypto/BlowfishCipherService.html" title="class in org.apache.shiro.crypto"><span class="strong">Prev Class</span></a></li> |
| <li><a href="../../../../org/apache/shiro/crypto/CryptoException.html" title="class in org.apache.shiro.crypto"><span class="strong">Next Class</span></a></li> |
| </ul> |
| <ul class="navList"> |
| <li><a href="../../../../index.html?org/apache/shiro/crypto/CipherService.html" target="_top">Frames</a></li> |
| <li><a href="CipherService.html" target="_top">No Frames</a></li> |
| </ul> |
| <ul class="navList" id="allclasses_navbar_top"> |
| <li><a href="../../../../allclasses-noframe.html">All Classes</a></li> |
| </ul> |
| <div> |
| <script type="text/javascript"><!-- |
| allClassesLink = document.getElementById("allclasses_navbar_top"); |
| if(window==top) { |
| allClassesLink.style.display = "block"; |
| } |
| else { |
| allClassesLink.style.display = "none"; |
| } |
| //--> |
| </script> |
| </div> |
| <div> |
| <ul class="subNavList"> |
| <li>Summary: </li> |
| <li>Nested | </li> |
| <li>Field | </li> |
| <li>Constr | </li> |
| <li><a href="#method_summary">Method</a></li> |
| </ul> |
| <ul class="subNavList"> |
| <li>Detail: </li> |
| <li>Field | </li> |
| <li>Constr | </li> |
| <li><a href="#method_detail">Method</a></li> |
| </ul> |
| </div> |
| <a name="skip-navbar_top"> |
| <!-- --> |
| </a></div> |
| <!-- ========= END OF TOP NAVBAR ========= --> |
| <!-- ======== START OF CLASS DATA ======== --> |
| <div class="header"> |
| <div class="subTitle">org.apache.shiro.crypto</div> |
| <h2 title="Interface CipherService" class="title">Interface CipherService</h2> |
| </div> |
| <div class="contentContainer"> |
| <div class="description"> |
| <ul class="blockList"> |
| <li class="blockList"> |
| <dl> |
| <dt>All Known Implementing Classes:</dt> |
| <dd><a href="../../../../org/apache/shiro/crypto/AbstractSymmetricCipherService.html" title="class in org.apache.shiro.crypto">AbstractSymmetricCipherService</a>, <a href="../../../../org/apache/shiro/crypto/AesCipherService.html" title="class in org.apache.shiro.crypto">AesCipherService</a>, <a href="../../../../org/apache/shiro/crypto/BlowfishCipherService.html" title="class in org.apache.shiro.crypto">BlowfishCipherService</a>, <a href="../../../../org/apache/shiro/crypto/DefaultBlockCipherService.html" title="class in org.apache.shiro.crypto">DefaultBlockCipherService</a>, <a href="../../../../org/apache/shiro/crypto/JcaCipherService.html" title="class in org.apache.shiro.crypto">JcaCipherService</a></dd> |
| </dl> |
| <hr> |
| <br> |
| <pre>public interface <a href="../../../../src-html/org/apache/shiro/crypto/CipherService.html#line.87">CipherService</a></pre> |
| <div class="block">A <code>CipherService</code> uses a cryptographic algorithm called a |
| <a href="http://en.wikipedia.org/wiki/Cipher">Cipher</a> to convert an original input source using a <code>key</code> to |
| an uninterpretable format. The resulting encrypted output is only able to be converted back to original form with |
| a <code>key</code> as well. <code>CipherService</code>s can perform both encryption and decryption. |
| <h2>Cipher Basics</h2> |
| For what is known as <em>Symmetric</em> <code>Cipher</code>s, the <code>Key</code> used to encrypt the source is the same |
| as (or trivially similar to) the <code>Key</code> used to decrypt it. |
| <p/> |
| For <em>Asymmetric</em> <code>Cipher</code>s, the encryption <code>Key</code> is not the same as the decryption <code>Key</code>. |
| The most common type of Asymmetric Ciphers are based on what is called public/private key pairs: |
| <p/> |
| A <em>private</em> key is known only to a single party, and as its name implies, is supposed be kept very private |
| and secure. A <em>public</em> key that is associated with the private key can be disseminated freely to anyone. |
| Then data encrypted by the public key can only be decrypted by the private key and vice versa, but neither party |
| need share their private key with anyone else. By not sharing a private key, you can guarantee no 3rd party can |
| intercept the key and therefore use it to decrypt a message. |
| <p/> |
| This asymmetric key technology was created as a |
| more secure alternative to symmetric ciphers that sometimes suffer from man-in-the-middle attacks since, for |
| data shared between two parties, the same Key must also be shared and may be compromised. |
| <p/> |
| Note that a symmetric cipher is perfectly fine to use if you just want to encode data in a format no one else |
| can understand and you never give away the key. Shiro uses a symmetric cipher when creating certain |
| HTTP Cookies for example - because it is often undesirable to have user's identity stored in a plain-text cookie, |
| that identity can be converted via a symmetric cipher. Since the the same exact Shiro application will receive |
| the cookie, it can decrypt it via the same <code>Key</code> and there is no potential for discovery since that Key |
| is never shared with anyone. |
| <h2><code>CipherService</code>s vs JDK <a href="http://java.sun.com/javase/6/docs/api/javax/crypto/Cipher.html?is-external=true" title="class or interface in javax.crypto"><code>Cipher</code></a>s</h2> |
| Shiro <code>CipherService</code>s essentially do the same things as JDK <a href="http://java.sun.com/javase/6/docs/api/javax/crypto/Cipher.html?is-external=true" title="class or interface in javax.crypto"><code>Cipher</code></a>s, but in |
| simpler and easier-to-use ways for most application developers. When thinking about encrypting and decrypting data |
| in an application, most app developers want what a <code>CipherService</code> provides, rather than having to manage the |
| lower-level intricacies of the JDK's <code>Cipher</code> API. Here are a few reasons why most people prefer |
| <code>CipherService</code>s: |
| <ul> |
| <li><b>Stateless Methods</b> - <code>CipherService</code> method calls do not retain state between method invocations. |
| JDK <code>Cipher</code> instances do retain state across invocations, requiring its end-users to manage the instance |
| and its state themselves.</li> |
| <li><b>Thread Safety</b> - <code>CipherService</code> instances are thread-safe inherently because no state is |
| retained across method invocations. JDK <code>Cipher</code> instances retain state and cannot be used by multiple |
| threads concurrently.</li> |
| <li><b>Single Operation</b> - <code>CipherService</code> method calls are single operation methods: encryption or |
| decryption in their entirety are done as a single method call. This is ideal for the large majority of developer |
| needs where you have something unencrypted and just want it decrypted (or vice versa) in a single method call. In |
| contrast, JDK <code>Cipher</code> instances can support encrypting/decrypting data in chunks over time (because it |
| retains state), but this often introduces API clutter and confusion for most application developers.</li> |
| <li><b>Type Safe</b> - There are <code>CipherService</code> implementations for different Cipher algorithms |
| (<code>AesCipherService</code>, <code>BlowfishCipherService</code>, etc). There is only one JDK <code>Cipher</code> class to |
| represent all cipher algorithms/instances. |
| <li><b>Simple Construction</b> - Because <code>CipherService</code> instances are type-safe, instantiating and using |
| one is often as simple as calling the default constructor, for example, <code>new AesCipherService();</code>. The |
| JDK <code>Cipher</code> class however requires using a procedural factory method with String arguments to indicate how |
| the instance should be created. The String arguments themselves are somewhat cryptic and hard to |
| understand unless you're a security expert. Shiro hides these details from you, but allows you to configure them |
| if you want.</li> |
| </ul></div> |
| <dl><dt><span class="strong">Since:</span></dt> |
| <dd>1.0</dd> |
| <dt><span class="strong">See Also:</span></dt><dd><a href="../../../../org/apache/shiro/crypto/BlowfishCipherService.html" title="class in org.apache.shiro.crypto"><code>BlowfishCipherService</code></a>, |
| <a href="../../../../org/apache/shiro/crypto/AesCipherService.html" title="class in org.apache.shiro.crypto"><code>AesCipherService</code></a></dd></dl> |
| </li> |
| </ul> |
| </div> |
| <div class="summary"> |
| <ul class="blockList"> |
| <li class="blockList"> |
| <!-- ========== METHOD SUMMARY =========== --> |
| <ul class="blockList"> |
| <li class="blockList"><a name="method_summary"> |
| <!-- --> |
| </a> |
| <h3>Method Summary</h3> |
| <table class="overviewSummary" border="0" cellpadding="3" cellspacing="0" summary="Method Summary table, listing methods, and an explanation"> |
| <caption><span>Methods</span><span class="tabEnd"> </span></caption> |
| <tr> |
| <th class="colFirst" scope="col">Modifier and Type</th> |
| <th class="colLast" scope="col">Method and Description</th> |
| </tr> |
| <tr class="altColor"> |
| <td class="colFirst"><code><a href="../../../../org/apache/shiro/util/ByteSource.html" title="interface in org.apache.shiro.util">ByteSource</a></code></td> |
| <td class="colLast"><code><strong><a href="../../../../org/apache/shiro/crypto/CipherService.html#decrypt(byte[], byte[])">decrypt</a></strong>(byte[] encrypted, |
| byte[] decryptionKey)</code> |
| <div class="block">Decrypts encrypted data via the specified cipher key and returns the original (pre-encrypted) data.</div> |
| </td> |
| </tr> |
| <tr class="rowColor"> |
| <td class="colFirst"><code>void</code></td> |
| <td class="colLast"><code><strong><a href="../../../../org/apache/shiro/crypto/CipherService.html#decrypt(java.io.InputStream, java.io.OutputStream, byte[])">decrypt</a></strong>(<a href="http://java.sun.com/javase/6/docs/api/java/io/InputStream.html?is-external=true" title="class or interface in java.io">InputStream</a> in, |
| <a href="http://java.sun.com/javase/6/docs/api/java/io/OutputStream.html?is-external=true" title="class or interface in java.io">OutputStream</a> out, |
| byte[] decryptionKey)</code> |
| <div class="block">Receives encrypted data from the given <code>InputStream</code>, decrypts it, and sends the resulting decrypted data |
| to the given <code>OutputStream</code>.</div> |
| </td> |
| </tr> |
| <tr class="altColor"> |
| <td class="colFirst"><code><a href="../../../../org/apache/shiro/util/ByteSource.html" title="interface in org.apache.shiro.util">ByteSource</a></code></td> |
| <td class="colLast"><code><strong><a href="../../../../org/apache/shiro/crypto/CipherService.html#encrypt(byte[], byte[])">encrypt</a></strong>(byte[] raw, |
| byte[] encryptionKey)</code> |
| <div class="block">Encrypts data via the specified cipher key.</div> |
| </td> |
| </tr> |
| <tr class="rowColor"> |
| <td class="colFirst"><code>void</code></td> |
| <td class="colLast"><code><strong><a href="../../../../org/apache/shiro/crypto/CipherService.html#encrypt(java.io.InputStream, java.io.OutputStream, byte[])">encrypt</a></strong>(<a href="http://java.sun.com/javase/6/docs/api/java/io/InputStream.html?is-external=true" title="class or interface in java.io">InputStream</a> in, |
| <a href="http://java.sun.com/javase/6/docs/api/java/io/OutputStream.html?is-external=true" title="class or interface in java.io">OutputStream</a> out, |
| byte[] encryptionKey)</code> |
| <div class="block">Receives the data from the given <code>InputStream</code>, encrypts it, and sends the resulting encrypted data to the |
| given <code>OutputStream</code>.</div> |
| </td> |
| </tr> |
| </table> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| </div> |
| <div class="details"> |
| <ul class="blockList"> |
| <li class="blockList"> |
| <!-- ============ METHOD DETAIL ========== --> |
| <ul class="blockList"> |
| <li class="blockList"><a name="method_detail"> |
| <!-- --> |
| </a> |
| <h3>Method Detail</h3> |
| <a name="decrypt(byte[], byte[])"> |
| <!-- --> |
| </a> |
| <ul class="blockList"> |
| <li class="blockList"> |
| <h4>decrypt</h4> |
| <pre><a href="../../../../org/apache/shiro/util/ByteSource.html" title="interface in org.apache.shiro.util">ByteSource</a> <a href="../../../../src-html/org/apache/shiro/crypto/CipherService.html#line.98">decrypt</a>(byte[] encrypted, |
| byte[] decryptionKey) |
| throws <a href="../../../../org/apache/shiro/crypto/CryptoException.html" title="class in org.apache.shiro.crypto">CryptoException</a></pre> |
| <div class="block">Decrypts encrypted data via the specified cipher key and returns the original (pre-encrypted) data. |
| Note that the key must be in a format understood by the CipherService implementation.</div> |
| <dl><dt><span class="strong">Parameters:</span></dt><dd><code>encrypted</code> - the previously encrypted data to decrypt</dd><dd><code>decryptionKey</code> - the cipher key used during decryption.</dd> |
| <dt><span class="strong">Returns:</span></dt><dd>a byte source representing the original form of the specified encrypted data.</dd> |
| <dt><span class="strong">Throws:</span></dt> |
| <dd><code><a href="../../../../org/apache/shiro/crypto/CryptoException.html" title="class in org.apache.shiro.crypto">CryptoException</a></code> - if there is an error during decryption</dd></dl> |
| </li> |
| </ul> |
| <a name="decrypt(java.io.InputStream, java.io.OutputStream, byte[])"> |
| <!-- --> |
| </a> |
| <ul class="blockList"> |
| <li class="blockList"> |
| <h4>decrypt</h4> |
| <pre>void <a href="../../../../src-html/org/apache/shiro/crypto/CipherService.html#line.130">decrypt</a>(<a href="http://java.sun.com/javase/6/docs/api/java/io/InputStream.html?is-external=true" title="class or interface in java.io">InputStream</a> in, |
| <a href="http://java.sun.com/javase/6/docs/api/java/io/OutputStream.html?is-external=true" title="class or interface in java.io">OutputStream</a> out, |
| byte[] decryptionKey) |
| throws <a href="../../../../org/apache/shiro/crypto/CryptoException.html" title="class in org.apache.shiro.crypto">CryptoException</a></pre> |
| <div class="block">Receives encrypted data from the given <code>InputStream</code>, decrypts it, and sends the resulting decrypted data |
| to the given <code>OutputStream</code>. |
| <p/> |
| <b>NOTE:</b> This method <em>does NOT</em> flush or close either stream prior to returning - the caller must |
| do so when they are finished with the streams. For example: |
| <pre> |
| try { |
| InputStream in = ... |
| OutputStream out = ... |
| cipherService.decrypt(in, out, decryptionKey); |
| } finally { |
| if (in != null) { |
| try { |
| in.close(); |
| } catch (IOException ioe1) { ... log, trigger event, etc } |
| } |
| if (out != null) { |
| try { |
| out.close(); |
| } catch (IOException ioe2) { ... log, trigger event, etc } |
| } |
| } |
| </pre></div> |
| <dl><dt><span class="strong">Parameters:</span></dt><dd><code>in</code> - the stream supplying the data to decrypt</dd><dd><code>out</code> - the stream to send the decrypted data</dd><dd><code>decryptionKey</code> - the cipher key to use for decryption</dd> |
| <dt><span class="strong">Throws:</span></dt> |
| <dd><code><a href="../../../../org/apache/shiro/crypto/CryptoException.html" title="class in org.apache.shiro.crypto">CryptoException</a></code> - if there is any problem during decryption.</dd></dl> |
| </li> |
| </ul> |
| <a name="encrypt(byte[], byte[])"> |
| <!-- --> |
| </a> |
| <ul class="blockList"> |
| <li class="blockList"> |
| <h4>encrypt</h4> |
| <pre><a href="../../../../org/apache/shiro/util/ByteSource.html" title="interface in org.apache.shiro.util">ByteSource</a> <a href="../../../../src-html/org/apache/shiro/crypto/CipherService.html#line.141">encrypt</a>(byte[] raw, |
| byte[] encryptionKey) |
| throws <a href="../../../../org/apache/shiro/crypto/CryptoException.html" title="class in org.apache.shiro.crypto">CryptoException</a></pre> |
| <div class="block">Encrypts data via the specified cipher key. Note that the key must be in a format understood by |
| the <code>CipherService</code> implementation.</div> |
| <dl><dt><span class="strong">Parameters:</span></dt><dd><code>raw</code> - the data to encrypt</dd><dd><code>encryptionKey</code> - the cipher key used during encryption.</dd> |
| <dt><span class="strong">Returns:</span></dt><dd>a byte source with the encrypted representation of the specified raw data.</dd> |
| <dt><span class="strong">Throws:</span></dt> |
| <dd><code><a href="../../../../org/apache/shiro/crypto/CryptoException.html" title="class in org.apache.shiro.crypto">CryptoException</a></code> - if there is an error during encryption</dd></dl> |
| </li> |
| </ul> |
| <a name="encrypt(java.io.InputStream, java.io.OutputStream, byte[])"> |
| <!-- --> |
| </a> |
| <ul class="blockListLast"> |
| <li class="blockList"> |
| <h4>encrypt</h4> |
| <pre>void <a href="../../../../src-html/org/apache/shiro/crypto/CipherService.html#line.173">encrypt</a>(<a href="http://java.sun.com/javase/6/docs/api/java/io/InputStream.html?is-external=true" title="class or interface in java.io">InputStream</a> in, |
| <a href="http://java.sun.com/javase/6/docs/api/java/io/OutputStream.html?is-external=true" title="class or interface in java.io">OutputStream</a> out, |
| byte[] encryptionKey) |
| throws <a href="../../../../org/apache/shiro/crypto/CryptoException.html" title="class in org.apache.shiro.crypto">CryptoException</a></pre> |
| <div class="block">Receives the data from the given <code>InputStream</code>, encrypts it, and sends the resulting encrypted data to the |
| given <code>OutputStream</code>. |
| <p/> |
| <b>NOTE:</b> This method <em>does NOT</em> flush or close either stream prior to returning - the caller must |
| do so when they are finished with the streams. For example: |
| <pre> |
| try { |
| InputStream in = ... |
| OutputStream out = ... |
| cipherService.encrypt(in, out, encryptionKey); |
| } finally { |
| if (in != null) { |
| try { |
| in.close(); |
| } catch (IOException ioe1) { ... log, trigger event, etc } |
| } |
| if (out != null) { |
| try { |
| out.close(); |
| } catch (IOException ioe2) { ... log, trigger event, etc } |
| } |
| } |
| </pre></div> |
| <dl><dt><span class="strong">Parameters:</span></dt><dd><code>in</code> - the stream supplying the data to encrypt</dd><dd><code>out</code> - the stream to send the encrypted data</dd><dd><code>encryptionKey</code> - the cipher key to use for encryption</dd> |
| <dt><span class="strong">Throws:</span></dt> |
| <dd><code><a href="../../../../org/apache/shiro/crypto/CryptoException.html" title="class in org.apache.shiro.crypto">CryptoException</a></code> - if there is any problem during encryption.</dd></dl> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| </div> |
| </div> |
| <!-- ========= END OF CLASS DATA ========= --> |
| <!-- ======= START OF BOTTOM NAVBAR ====== --> |
| <div class="bottomNav"><a name="navbar_bottom"> |
| <!-- --> |
| </a><a href="#skip-navbar_bottom" title="Skip navigation links"></a><a name="navbar_bottom_firstrow"> |
| <!-- --> |
| </a> |
| <ul class="navList" title="Navigation"> |
| <li><a href="../../../../overview-summary.html">Overview</a></li> |
| <li><a href="package-summary.html">Package</a></li> |
| <li class="navBarCell1Rev">Class</li> |
| <li><a href="class-use/CipherService.html">Use</a></li> |
| <li><a href="package-tree.html">Tree</a></li> |
| <li><a href="../../../../deprecated-list.html">Deprecated</a></li> |
| <li><a href="../../../../index-all.html">Index</a></li> |
| <li><a href="../../../../help-doc.html">Help</a></li> |
| </ul> |
| </div> |
| <div class="subNav"> |
| <ul class="navList"> |
| <li><a href="../../../../org/apache/shiro/crypto/BlowfishCipherService.html" title="class in org.apache.shiro.crypto"><span class="strong">Prev Class</span></a></li> |
| <li><a href="../../../../org/apache/shiro/crypto/CryptoException.html" title="class in org.apache.shiro.crypto"><span class="strong">Next Class</span></a></li> |
| </ul> |
| <ul class="navList"> |
| <li><a href="../../../../index.html?org/apache/shiro/crypto/CipherService.html" target="_top">Frames</a></li> |
| <li><a href="CipherService.html" target="_top">No Frames</a></li> |
| </ul> |
| <ul class="navList" id="allclasses_navbar_bottom"> |
| <li><a href="../../../../allclasses-noframe.html">All Classes</a></li> |
| </ul> |
| <div> |
| <script type="text/javascript"><!-- |
| allClassesLink = document.getElementById("allclasses_navbar_bottom"); |
| if(window==top) { |
| allClassesLink.style.display = "block"; |
| } |
| else { |
| allClassesLink.style.display = "none"; |
| } |
| //--> |
| </script> |
| </div> |
| <div> |
| <ul class="subNavList"> |
| <li>Summary: </li> |
| <li>Nested | </li> |
| <li>Field | </li> |
| <li>Constr | </li> |
| <li><a href="#method_summary">Method</a></li> |
| </ul> |
| <ul class="subNavList"> |
| <li>Detail: </li> |
| <li>Field | </li> |
| <li>Constr | </li> |
| <li><a href="#method_detail">Method</a></li> |
| </ul> |
| </div> |
| <a name="skip-navbar_bottom"> |
| <!-- --> |
| </a></div> |
| <!-- ======== END OF BOTTOM NAVBAR ======= --> |
| <p class="legalCopy"><small>Copyright © 2004-2016 <a href="http://www.apache.org/">The Apache Software Foundation</a>. All Rights Reserved.</small></p> |
| </body> |
| </html> |