org.apache.shiro.crypto
Interface CipherService

All Known Implementing Classes:
AbstractSymmetricCipherService, AesCipherService, BlowfishCipherService, DefaultBlockCipherService, JcaCipherService

public interface CipherService

A CipherService uses a cryptographic algorithm called a Cipher to convert an original input source using a key to an uninterpretable format. The resulting encrypted output is only able to be converted back to original form with a key as well. CipherServices can perform both encryption and decryption.

Cipher Basics

For what is known as Symmetric Ciphers, the Key used to encrypt the source is the same as (or trivially similar to) the Key used to decrypt it.

For Asymmetric Ciphers, the encryption Key is not the same as the decryption Key. The most common type of Asymmetric Ciphers are based on what is called public/private key pairs:

A private key is known only to a single party, and as its name implies, is supposed be kept very private and secure. A public 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.

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.

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 Key and there is no potential for discovery since that Key is never shared with anyone.

CipherServices vs JDK Ciphers

Shiro CipherServices essentially do the same things as JDK Ciphers, 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 CipherService provides, rather than having to manage the lower-level intricacies of the JDK's Cipher API. Here are a few reasons why most people prefer CipherServices:

Since:
1.0
See Also:
BlowfishCipherService, AesCipherService

Method Summary
 ByteSource decrypt(byte[] encrypted, byte[] decryptionKey)
          Decrypts encrypted data via the specified cipher key and returns the original (pre-encrypted) data.
 void decrypt(InputStream in, OutputStream out, byte[] decryptionKey)
          Receives encrypted data from the given InputStream, decrypts it, and sends the resulting decrypted data to the given OutputStream.
 ByteSource encrypt(byte[] raw, byte[] encryptionKey)
          Encrypts data via the specified cipher key.
 void encrypt(InputStream in, OutputStream out, byte[] encryptionKey)
          Receives the data from the given InputStream, encrypts it, and sends the resulting encrypted data to the given OutputStream.
 

Method Detail

decrypt

ByteSource decrypt(byte[] encrypted,
                   byte[] decryptionKey)
                   throws CryptoException
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.

Parameters:
encrypted - the previously encrypted data to decrypt
decryptionKey - the cipher key used during decryption.
Returns:
a byte source representing the original form of the specified encrypted data.
Throws:
CryptoException - if there is an error during decryption

decrypt

void decrypt(InputStream in,
             OutputStream out,
             byte[] decryptionKey)
             throws CryptoException
Receives encrypted data from the given InputStream, decrypts it, and sends the resulting decrypted data to the given OutputStream.

NOTE: This method does NOT flush or close either stream prior to returning - the caller must do so when they are finished with the streams. For example:

 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 }
     }
 }
 

Parameters:
in - the stream supplying the data to decrypt
out - the stream to send the decrypted data
decryptionKey - the cipher key to use for decryption
Throws:
CryptoException - if there is any problem during decryption.

encrypt

ByteSource encrypt(byte[] raw,
                   byte[] encryptionKey)
                   throws CryptoException
Encrypts data via the specified cipher key. Note that the key must be in a format understood by the CipherService implementation.

Parameters:
raw - the data to encrypt
encryptionKey - the cipher key used during encryption.
Returns:
a byte source with the encrypted representation of the specified raw data.
Throws:
CryptoException - if there is an error during encryption

encrypt

void encrypt(InputStream in,
             OutputStream out,
             byte[] encryptionKey)
             throws CryptoException
Receives the data from the given InputStream, encrypts it, and sends the resulting encrypted data to the given OutputStream.

NOTE: This method does NOT flush or close either stream prior to returning - the caller must do so when they are finished with the streams. For example:

 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 }
     }
 }
 

Parameters:
in - the stream supplying the data to encrypt
out - the stream to send the encrypted data
encryptionKey - the cipher key to use for encryption
Throws:
CryptoException - if there is any problem during encryption.


Copyright © 2004-2012 The Apache Software Foundation. All Rights Reserved.