001    /*
002     * Licensed to the Apache Software Foundation (ASF) under one
003     * or more contributor license agreements.  See the NOTICE file
004     * distributed with this work for additional information
005     * regarding copyright ownership.  The ASF licenses this file
006     * to you under the Apache License, Version 2.0 (the
007     * "License"); you may not use this file except in compliance
008     * with the License.  You may obtain a copy of the License at
009     *
010     *     http://www.apache.org/licenses/LICENSE-2.0
011     *
012     * Unless required by applicable law or agreed to in writing,
013     * software distributed under the License is distributed on an
014     * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015     * KIND, either express or implied.  See the License for the
016     * specific language governing permissions and limitations
017     * under the License.
018     */
019    package org.apache.shiro.crypto;
020    
021    import org.apache.shiro.util.ByteSource;
022    
023    import java.io.InputStream;
024    import java.io.OutputStream;
025    
026    /**
027     * A {@code CipherService} uses a cryptographic algorithm called a
028     * <a href="http://en.wikipedia.org/wiki/Cipher">Cipher</a> to convert an original input source using a {@code key} to
029     * an uninterpretable format.  The resulting encrypted output is only able to be converted back to original form with
030     * a {@code key} as well.  {@code CipherService}s can perform both encryption and decryption.
031     * <h2>Cipher Basics</h2>
032     * For what is known as <em>Symmetric</em> {@code Cipher}s, the {@code Key} used to encrypt the source is the same
033     * as (or trivially similar to) the {@code Key} used to decrypt it.
034     * <p/>
035     * For <em>Asymmetric</em> {@code Cipher}s, the encryption {@code Key} is not the same as the decryption {@code Key}.
036     * The most common type of Asymmetric Ciphers are based on what is called public/private key pairs:
037     * <p/>
038     * A <em>private</em> key is known only to a single party, and as its name implies, is supposed be kept very private
039     * and secure.  A <em>public</em> key that is associated with the private key can be disseminated freely to anyone.
040     * Then data encrypted by the public key can only be decrypted by the private key and vice versa, but neither party
041     * need share their private key with anyone else.  By not sharing a private key, you can guarantee no 3rd party can
042     * intercept the key and therefore use it to decrypt a message.
043     * <p/>
044     * This asymmetric key technology was created as a
045     * more secure alternative to symmetric ciphers that sometimes suffer from man-in-the-middle attacks since, for
046     * data shared between two parties, the same Key must also be shared and may be compromised.
047     * <p/>
048     * Note that a symmetric cipher is perfectly fine to use if you just want to encode data in a format no one else
049     * can understand and you never give away the key.  Shiro uses a symmetric cipher when creating certain
050     * HTTP Cookies for example - because it is often undesirable to have user's identity stored in a plain-text cookie,
051     * that identity can be converted via a symmetric cipher.  Since the the same exact Shiro application will receive
052     * the cookie, it can decrypt it via the same {@code Key} and there is no potential for discovery since that Key
053     * is never shared with anyone.
054     * <h2>{@code CipherService}s vs JDK {@link javax.crypto.Cipher Cipher}s</h2>
055     * Shiro {@code CipherService}s essentially do the same things as JDK {@link javax.crypto.Cipher Cipher}s, but in
056     * simpler and easier-to-use ways for most application developers.  When thinking about encrypting and decrypting data
057     * in an application, most app developers want what a {@code CipherService} provides, rather than having to manage the
058     * lower-level intricacies of the JDK's {@code Cipher} API.  Here are a few reasons why most people prefer
059     * {@code CipherService}s:
060     * <ul>
061     * <li><b>Stateless Methods</b> - {@code CipherService} method calls do not retain state between method invocations.
062     * JDK {@code Cipher} instances do retain state across invocations, requiring its end-users to manage the instance
063     * and its state themselves.</li>
064     * <li><b>Thread Safety</b> - {@code CipherService} instances are thread-safe inherently because no state is
065     * retained across method invocations.  JDK {@code Cipher} instances retain state and cannot be used by multiple
066     * threads concurrently.</li>
067     * <li><b>Single Operation</b> - {@code CipherService} method calls are single operation methods: encryption or
068     * decryption in their entirety are done as a single method call.  This is ideal for the large majority of developer
069     * needs where you have something unencrypted and just want it decrypted (or vice versa) in a single method call.  In
070     * contrast, JDK {@code Cipher} instances can support encrypting/decrypting data in chunks over time (because it
071     * retains state), but this often introduces API clutter and confusion for most application developers.</li>
072     * <li><b>Type Safe</b> - There are {@code CipherService} implementations for different Cipher algorithms
073     * ({@code AesCipherService}, {@code BlowfishCipherService}, etc).  There is only one JDK {@code Cipher} class to
074     * represent all cipher algorithms/instances.
075     * <li><b>Simple Construction</b> - Because {@code CipherService} instances are type-safe, instantiating and using
076     * one is often as simple as calling the default constructor, for example, <code>new AesCipherService();</code>.  The
077     * JDK {@code Cipher} class however requires using a procedural factory method with String arguments to indicate how
078     * the instance should be created.  The String arguments themselves are somewhat cryptic and hard to
079     * understand unless you're a security expert.  Shiro hides these details from you, but allows you to configure them
080     * if you want.</li>
081     * </ul>
082     *
083     * @see BlowfishCipherService
084     * @see AesCipherService
085     * @since 1.0
086     */
087    public interface CipherService {
088    
089        /**
090         * Decrypts encrypted data via the specified cipher key and returns the original (pre-encrypted) data.
091         * Note that the key must be in a format understood by the CipherService implementation.
092         *
093         * @param encrypted     the previously encrypted data to decrypt
094         * @param decryptionKey the cipher key used during decryption.
095         * @return a byte source representing the original form of the specified encrypted data.
096         * @throws CryptoException if there is an error during decryption
097         */
098        ByteSource decrypt(byte[] encrypted, byte[] decryptionKey) throws CryptoException;
099    
100        /**
101         * Receives encrypted data from the given {@code InputStream}, decrypts it, and sends the resulting decrypted data
102         * to the given {@code OutputStream}.
103         * <p/>
104         * <b>NOTE:</b> This method <em>does NOT</em> flush or close either stream prior to returning - the caller must
105         * do so when they are finished with the streams.  For example:
106         * <pre>
107         * try {
108         *     InputStream in = ...
109         *     OutputStream out = ...
110         *     cipherService.decrypt(in, out, decryptionKey);
111         * } finally {
112         *     if (in != null) {
113         *         try {
114         *             in.close();
115         *         } catch (IOException ioe1) { ... log, trigger event, etc }
116         *     }
117         *     if (out != null) {
118         *         try {
119         *             out.close();
120         *         } catch (IOException ioe2) { ... log, trigger event, etc }
121         *     }
122         * }
123         * </pre>
124         *
125         * @param in            the stream supplying the data to decrypt
126         * @param out           the stream to send the decrypted data
127         * @param decryptionKey the cipher key to use for decryption
128         * @throws CryptoException if there is any problem during decryption.
129         */
130        void decrypt(InputStream in, OutputStream out, byte[] decryptionKey) throws CryptoException;
131    
132        /**
133         * Encrypts data via the specified cipher key.  Note that the key must be in a format understood by
134         * the {@code CipherService} implementation.
135         *
136         * @param raw           the data to encrypt
137         * @param encryptionKey the cipher key used during encryption.
138         * @return a byte source with the encrypted representation of the specified raw data.
139         * @throws CryptoException if there is an error during encryption
140         */
141        ByteSource encrypt(byte[] raw, byte[] encryptionKey) throws CryptoException;
142    
143        /**
144         * Receives the data from the given {@code InputStream}, encrypts it, and sends the resulting encrypted data to the
145         * given {@code OutputStream}.
146         * <p/>
147         * <b>NOTE:</b> This method <em>does NOT</em> flush or close either stream prior to returning - the caller must
148         * do so when they are finished with the streams.  For example:
149         * <pre>
150         * try {
151         *     InputStream in = ...
152         *     OutputStream out = ...
153         *     cipherService.encrypt(in, out, encryptionKey);
154         * } finally {
155         *     if (in != null) {
156         *         try {
157         *             in.close();
158         *         } catch (IOException ioe1) { ... log, trigger event, etc }
159         *     }
160         *     if (out != null) {
161         *         try {
162         *             out.close();
163         *         } catch (IOException ioe2) { ... log, trigger event, etc }
164         *     }
165         * }
166         * </pre>
167         *
168         * @param in            the stream supplying the data to encrypt
169         * @param out           the stream to send the encrypted data
170         * @param encryptionKey the cipher key to use for encryption
171         * @throws CryptoException if there is any problem during encryption.
172         */
173        void encrypt(InputStream in, OutputStream out, byte[] encryptionKey) throws CryptoException;
174    
175    }