blob: 7cdd51ceeb467e95c3c7863747aabb177d7db99c [file] [log] [blame]
<!DOCTYPE HTML>
<!-- NewPage -->
<html lang="en">
<head>
<!-- Generated by javadoc -->
<title>CipherService (Apache Shiro 1.9.1 API)</title>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<link rel="stylesheet" type="text/css" href="../../../../stylesheet.css" title="Style">
<link rel="stylesheet" type="text/css" href="../../../../jquery/jquery-ui.css" title="Style">
<script type="text/javascript" src="../../../../script.js"></script>
<script type="text/javascript" src="../../../../jquery/jszip/dist/jszip.min.js"></script>
<script type="text/javascript" src="../../../../jquery/jszip-utils/dist/jszip-utils.min.js"></script>
<!--[if IE]>
<script type="text/javascript" src="../../../../jquery/jszip-utils/dist/jszip-utils-ie.min.js"></script>
<![endif]-->
<script type="text/javascript" src="../../../../jquery/jquery-3.5.1.js"></script>
<script type="text/javascript" src="../../../../jquery/jquery-ui.js"></script>
</head>
<body>
<script type="text/javascript"><!--
try {
if (location.href.indexOf('is-external=true') == -1) {
parent.document.title="CipherService (Apache Shiro 1.9.1 API)";
}
}
catch(err) {
}
//-->
var data = {"i0":6,"i1":6,"i2":6,"i3":6};
var tabs = {65535:["t0","All Methods"],2:["t2","Instance Methods"],4:["t3","Abstract Methods"]};
var altColor = "altColor";
var rowColor = "rowColor";
var tableTab = "tableTab";
var activeTableTab = "activeTableTab";
var pathtoroot = "../../../../";
var useModuleDirectories = true;
loadScripts(document, 'script');</script>
<noscript>
<div>JavaScript is disabled on your browser.</div>
</noscript>
<header role="banner">
<nav role="navigation">
<div class="fixedNav"><!-- Matomo --> <script> var _paq = window._paq = window._paq || []; /* tracker methods like "setCustomDimension" should be called before "trackPageView" */ /* We explicitly disable cookie tracking to avoid privacy issues */ _paq.push(['disableCookies']); _paq.push(['trackPageView']); _paq.push(['enableLinkTracking']); (function() { var u="//matomo.privacy.apache.org/"; _paq.push(['setTrackerUrl', u+'matomo.php']); _paq.push(['setSiteId', '2']); var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0]; g.async=true; g.src=u+'matomo.js'; s.parentNode.insertBefore(g,s); })(); </script> <!-- End Matomo Code -->
<!-- ========= START OF TOP NAVBAR ======= -->
<div class="topNav"><a id="navbar.top">
<!-- -->
</a>
<div class="skipNav"><a href="#skip.navbar.top" title="Skip navigation links">Skip navigation links</a></div>
<a id="navbar.top.firstrow">
<!-- -->
</a>
<ul class="navList" title="Navigation">
<li><a href="../../../../index.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" id="allclasses_navbar_top">
<li><a href="../../../../allclasses.html">All&nbsp;Classes</a></li>
</ul>
<ul class="navListSearch">
<li><label for="search">SEARCH:</label>
<input type="text" id="search" value="search" disabled="disabled">
<input type="reset" id="reset" value="reset" disabled="disabled">
</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>
<noscript>
<div>JavaScript is disabled on your browser.</div>
</noscript>
</div>
<div>
<ul class="subNavList">
<li>Summary:&nbsp;</li>
<li>Nested&nbsp;|&nbsp;</li>
<li>Field&nbsp;|&nbsp;</li>
<li>Constr&nbsp;|&nbsp;</li>
<li><a href="#method.summary">Method</a></li>
</ul>
<ul class="subNavList">
<li>Detail:&nbsp;</li>
<li>Field&nbsp;|&nbsp;</li>
<li>Constr&nbsp;|&nbsp;</li>
<li><a href="#method.detail">Method</a></li>
</ul>
</div>
<a id="skip.navbar.top">
<!-- -->
</a></div>
<!-- ========= END OF TOP NAVBAR ========= -->
</div>
<div class="navPadding">&nbsp;</div>
<script type="text/javascript"><!--
$('.navPadding').css('padding-top', $('.fixedNav').css("height"));
//-->
</script>
</nav>
</header>
<!-- ======== START OF CLASS DATA ======== -->
<main role="main">
<div class="header">
<div class="subTitle"><span class="packageLabelInType">Package</span>&nbsp;<a href="package-summary.html">org.apache.shiro.crypto</a></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><code><a href="AbstractSymmetricCipherService.html" title="class in org.apache.shiro.crypto">AbstractSymmetricCipherService</a></code>, <code><a href="AesCipherService.html" title="class in org.apache.shiro.crypto">AesCipherService</a></code>, <code><a href="BlowfishCipherService.html" title="class in org.apache.shiro.crypto">BlowfishCipherService</a></code>, <code><a href="DefaultBlockCipherService.html" title="class in org.apache.shiro.crypto">DefaultBlockCipherService</a></code>, <code><a href="JcaCipherService.html" title="class in org.apache.shiro.crypto">JcaCipherService</a></code></dd>
</dl>
<hr>
<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="https://docs.oracle.com/javase/8/docs/api/javax/crypto/Cipher.html?is-external=true" title="class or interface in javax.crypto" class="externalLink"><code>Cipher</code></a>s</h2>
Shiro <code>CipherService</code>s essentially do the same things as JDK <a href="https://docs.oracle.com/javase/8/docs/api/javax/crypto/Cipher.html?is-external=true" title="class or interface in javax.crypto" class="externalLink"><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="simpleTagLabel">Since:</span></dt>
<dd>1.0</dd>
<dt><span class="seeLabel">See Also:</span></dt>
<dd><a href="BlowfishCipherService.html" title="class in org.apache.shiro.crypto"><code>BlowfishCipherService</code></a>,
<a href="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 =========== -->
<section role="region">
<ul class="blockList">
<li class="blockList"><a id="method.summary">
<!-- -->
</a>
<h3>Method Summary</h3>
<table class="memberSummary">
<caption><span id="t0" class="activeTableTab"><span>All Methods</span><span class="tabEnd">&nbsp;</span></span><span id="t2" class="tableTab"><span><a href="javascript:show(2);">Instance Methods</a></span><span class="tabEnd">&nbsp;</span></span><span id="t3" class="tableTab"><span><a href="javascript:show(4);">Abstract Methods</a></span><span class="tabEnd">&nbsp;</span></span></caption>
<tr>
<th class="colFirst" scope="col">Modifier and Type</th>
<th class="colSecond" scope="col">Method</th>
<th class="colLast" scope="col">Description</th>
</tr>
<tr id="i0" class="altColor">
<td class="colFirst"><code><a href="../util/ByteSource.html" title="interface in org.apache.shiro.util">ByteSource</a></code></td>
<th class="colSecond" scope="row"><code><span class="memberNameLink"><a href="#decrypt(byte%5B%5D,byte%5B%5D)">decrypt</a></span>&#8203;(byte[]&nbsp;encrypted,
byte[]&nbsp;decryptionKey)</code></th>
<td class="colLast">
<div class="block">Decrypts encrypted data via the specified cipher key and returns the original (pre-encrypted) data.</div>
</td>
</tr>
<tr id="i1" class="rowColor">
<td class="colFirst"><code>void</code></td>
<th class="colSecond" scope="row"><code><span class="memberNameLink"><a href="#decrypt(java.io.InputStream,java.io.OutputStream,byte%5B%5D)">decrypt</a></span>&#8203;(<a href="https://docs.oracle.com/javase/8/docs/api/java/io/InputStream.html?is-external=true" title="class or interface in java.io" class="externalLink">InputStream</a>&nbsp;in,
<a href="https://docs.oracle.com/javase/8/docs/api/java/io/OutputStream.html?is-external=true" title="class or interface in java.io" class="externalLink">OutputStream</a>&nbsp;out,
byte[]&nbsp;decryptionKey)</code></th>
<td class="colLast">
<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 id="i2" class="altColor">
<td class="colFirst"><code><a href="../util/ByteSource.html" title="interface in org.apache.shiro.util">ByteSource</a></code></td>
<th class="colSecond" scope="row"><code><span class="memberNameLink"><a href="#encrypt(byte%5B%5D,byte%5B%5D)">encrypt</a></span>&#8203;(byte[]&nbsp;raw,
byte[]&nbsp;encryptionKey)</code></th>
<td class="colLast">
<div class="block">Encrypts data via the specified cipher key.</div>
</td>
</tr>
<tr id="i3" class="rowColor">
<td class="colFirst"><code>void</code></td>
<th class="colSecond" scope="row"><code><span class="memberNameLink"><a href="#encrypt(java.io.InputStream,java.io.OutputStream,byte%5B%5D)">encrypt</a></span>&#8203;(<a href="https://docs.oracle.com/javase/8/docs/api/java/io/InputStream.html?is-external=true" title="class or interface in java.io" class="externalLink">InputStream</a>&nbsp;in,
<a href="https://docs.oracle.com/javase/8/docs/api/java/io/OutputStream.html?is-external=true" title="class or interface in java.io" class="externalLink">OutputStream</a>&nbsp;out,
byte[]&nbsp;encryptionKey)</code></th>
<td class="colLast">
<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>
</section>
</li>
</ul>
</div>
<div class="details">
<ul class="blockList">
<li class="blockList">
<!-- ============ METHOD DETAIL ========== -->
<section role="region">
<ul class="blockList">
<li class="blockList"><a id="method.detail">
<!-- -->
</a>
<h3>Method Detail</h3>
<a id="decrypt(byte[],byte[])">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>decrypt</h4>
<pre class="methodSignature"><a href="../util/ByteSource.html" title="interface in org.apache.shiro.util">ByteSource</a>&nbsp;<a href="../../../../src-html/org/apache/shiro/crypto/CipherService.html#line.98">decrypt</a>&#8203;(byte[]&nbsp;encrypted,
byte[]&nbsp;decryptionKey)
throws <a href="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="paramLabel">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="returnLabel">Returns:</span></dt>
<dd>a byte source representing the original form of the specified encrypted data.</dd>
<dt><span class="throwsLabel">Throws:</span></dt>
<dd><code><a href="CryptoException.html" title="class in org.apache.shiro.crypto">CryptoException</a></code> - if there is an error during decryption</dd>
</dl>
</li>
</ul>
<a id="decrypt(java.io.InputStream,java.io.OutputStream,byte[])">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>decrypt</h4>
<pre class="methodSignature">void&nbsp;<a href="../../../../src-html/org/apache/shiro/crypto/CipherService.html#line.130">decrypt</a>&#8203;(<a href="https://docs.oracle.com/javase/8/docs/api/java/io/InputStream.html?is-external=true" title="class or interface in java.io" class="externalLink">InputStream</a>&nbsp;in,
<a href="https://docs.oracle.com/javase/8/docs/api/java/io/OutputStream.html?is-external=true" title="class or interface in java.io" class="externalLink">OutputStream</a>&nbsp;out,
byte[]&nbsp;decryptionKey)
throws <a href="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="paramLabel">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="throwsLabel">Throws:</span></dt>
<dd><code><a href="CryptoException.html" title="class in org.apache.shiro.crypto">CryptoException</a></code> - if there is any problem during decryption.</dd>
</dl>
</li>
</ul>
<a id="encrypt(byte[],byte[])">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>encrypt</h4>
<pre class="methodSignature"><a href="../util/ByteSource.html" title="interface in org.apache.shiro.util">ByteSource</a>&nbsp;<a href="../../../../src-html/org/apache/shiro/crypto/CipherService.html#line.141">encrypt</a>&#8203;(byte[]&nbsp;raw,
byte[]&nbsp;encryptionKey)
throws <a href="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="paramLabel">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="returnLabel">Returns:</span></dt>
<dd>a byte source with the encrypted representation of the specified raw data.</dd>
<dt><span class="throwsLabel">Throws:</span></dt>
<dd><code><a href="CryptoException.html" title="class in org.apache.shiro.crypto">CryptoException</a></code> - if there is an error during encryption</dd>
</dl>
</li>
</ul>
<a id="encrypt(java.io.InputStream,java.io.OutputStream,byte[])">
<!-- -->
</a>
<ul class="blockListLast">
<li class="blockList">
<h4>encrypt</h4>
<pre class="methodSignature">void&nbsp;<a href="../../../../src-html/org/apache/shiro/crypto/CipherService.html#line.173">encrypt</a>&#8203;(<a href="https://docs.oracle.com/javase/8/docs/api/java/io/InputStream.html?is-external=true" title="class or interface in java.io" class="externalLink">InputStream</a>&nbsp;in,
<a href="https://docs.oracle.com/javase/8/docs/api/java/io/OutputStream.html?is-external=true" title="class or interface in java.io" class="externalLink">OutputStream</a>&nbsp;out,
byte[]&nbsp;encryptionKey)
throws <a href="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="paramLabel">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="throwsLabel">Throws:</span></dt>
<dd><code><a href="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>
</section>
</li>
</ul>
</div>
</div>
</main>
<!-- ========= END OF CLASS DATA ========= -->
<footer role="contentinfo">
<nav role="navigation">
<!-- ======= START OF BOTTOM NAVBAR ====== -->
<div class="bottomNav"><a id="navbar.bottom">
<!-- -->
</a>
<div class="skipNav"><a href="#skip.navbar.bottom" title="Skip navigation links">Skip navigation links</a></div>
<a id="navbar.bottom.firstrow">
<!-- -->
</a>
<ul class="navList" title="Navigation">
<li><a href="../../../../index.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" id="allclasses_navbar_bottom">
<li><a href="../../../../allclasses.html">All&nbsp;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>
<noscript>
<div>JavaScript is disabled on your browser.</div>
</noscript>
</div>
<div>
<ul class="subNavList">
<li>Summary:&nbsp;</li>
<li>Nested&nbsp;|&nbsp;</li>
<li>Field&nbsp;|&nbsp;</li>
<li>Constr&nbsp;|&nbsp;</li>
<li><a href="#method.summary">Method</a></li>
</ul>
<ul class="subNavList">
<li>Detail:&nbsp;</li>
<li>Field&nbsp;|&nbsp;</li>
<li>Constr&nbsp;|&nbsp;</li>
<li><a href="#method.detail">Method</a></li>
</ul>
</div>
<a id="skip.navbar.bottom">
<!-- -->
</a></div>
<!-- ======== END OF BOTTOM NAVBAR ======= -->
</nav>
<p class="legalCopy"><small>Copyright &#169; 2004&#x2013;2022 <a href="https://www.apache.org/">The Apache Software Foundation</a>. All rights reserved.</small></p>
</footer>
</body>
</html>