JcaCipherService

Abstract {@code CipherService} implementation utilizing Java's JCA APIs. <h2>Auto-generated Initialization Vectors</h2> Shiro does something by default for all of its {@code CipherService} implementations that the JCA {@link javax.crypto.Cipher Cipher} does not do: by default, <a href="http://en.wikipedia.org/wiki/Initialization_vector">initialization vector</a>s are automatically randomly generated and prepended to encrypted data before returning from the {@code encrypt} methods. That is, the returned byte array or {@code OutputStream} is actually a concatenation of an initialization vector byte array plus the actual encrypted data byte array. The {@code decrypt} methods in turn know to read this prepended initialization vector before decrypting the real data that follows. <p/> This is highly desirable because initialization vectors guarantee that, for a key and any plaintext, the encrypted output will always be different <em>even if you call {@code encrypt} multiple times with the exact same arguments</em>. This is essential in cryptography to ensure that data patterns cannot be identified across multiple input sources that are the same or similar. <p/> You can turn off this behavior by setting the {@link #setGenerateInitializationVectors(bool) generateInitializationVectors} property to {@code false}, but it is highly recommended that you do not do this unless you have a very good reason to do so, since you would be losing a critical security feature. <h3>Initialization Vector Size</h3> This implementation defaults the {@link #setInitializationVectorSize(int) initializationVectorSize} attribute to {@code 128} bits, a fairly common size. Initialization vector sizes are very algorithm specific however, so subclass implementations will often override this value in their constructor if necessary. <p/> Also note that {@code initializationVectorSize} values are specified in the number of bits (not bytes!) to match common references in most cryptography documentation. In practice though, initialization vectors are always specified as a byte array, so ensure that if you set this property, that the value is a multiple of {@code 8} to ensure that the IV can be correctly represented as a byte array (the {@link #setInitializationVectorSize(int) setInitializationVectorSize} mutator method enforces this).

@since 1.0

abstract

class JcaCipherService : CipherService {

this(string algorithmName);

string getAlgorithmName();

int getKeySize();

void setKeySize(int keySize);

bool isGenerateInitializationVectors();

void setGenerateInitializationVectors(bool generateInitializationVectors);

int getInitializationVectorSize();

void setInitializationVectorSize(int initializationVectorSize);

bool isGenerateInitializationVectors(bool streaming);

int getStreamingBufferSize();

void setStreamingBufferSize(int streamingBufferSize);

byte[] generateInitializationVector(bool streaming);

ByteSource encrypt(byte[] plaintext, byte[] key);

ByteSource decrypt(byte[] ciphertext, byte[] key);

}

Constructors

this this(string algorithmName): Creates a new {@code JcaCipherService} instance which will use the specified cipher {@code algorithmName} for all encryption, decryption, and key operations. Also, the following defaults are set: <ul> <li>{@link #setKeySize keySize} = 128 bits</li> <li>{@link #setInitializationVectorSize(int) initializationVectorSize} = 128 bits</li> <li>{@link #setStreamingBufferSize(int) streamingBufferSize} = 512 bytes</li> </ul>

Members

Functions

decrypt ByteSource decrypt(byte[] ciphertext, byte[] key): Undocumented in source. Be warned that the author may not have intended to support it.
encrypt ByteSource encrypt(byte[] plaintext, byte[] key): Undocumented in source. Be warned that the author may not have intended to support it.
generateInitializationVector byte[] generateInitializationVector(bool streaming): Undocumented in source. Be warned that the author may not have intended to support it.
getAlgorithmName string getAlgorithmName(): Returns the cipher algorithm name that will be used for all encryption, decryption, and key operations (for example, 'AES', 'Blowfish', 'RSA', 'DSA', 'TripleDES', etc).
getInitializationVectorSize int getInitializationVectorSize(): Returns the algorithm-specific size in bits of generated initialization vectors.
getKeySize int getKeySize(): Returns the size in bits (not bytes) of generated cipher keys.
getStreamingBufferSize int getStreamingBufferSize(): Returns the size in bytes of the internal buffer used to transfer data from one stream to another during stream operations ({@link #encrypt(java.io.InputStream, java.io.OutputStream, byte[])} and {@link #decrypt(java.io.InputStream, java.io.OutputStream, byte[])}). <p/> Default size is {@code 512} bytes.
isGenerateInitializationVectors bool isGenerateInitializationVectors(): Undocumented in source. Be warned that the author may not have intended to support it.
isGenerateInitializationVectors bool isGenerateInitializationVectors(bool streaming): Undocumented in source. Be warned that the author may not have intended to support it.
setGenerateInitializationVectors void setGenerateInitializationVectors(bool generateInitializationVectors): Undocumented in source. Be warned that the author may not have intended to support it.
setInitializationVectorSize void setInitializationVectorSize(int initializationVectorSize): Sets the algorithm-specific initialization vector size in bits (not bytes!) to be used when generating initialization vectors. The value must be a multiple of {@code 8} to ensure that the IV can be represented as a byte array.
setKeySize void setKeySize(int keySize): Sets the size in bits (not bytes) of generated cipher keys.
setStreamingBufferSize void setStreamingBufferSize(int streamingBufferSize): Sets the size in bytes of the internal buffer used to transfer data from one stream to another during stream operations ({@link #encrypt(java.io.InputStream, java.io.OutputStream, byte[])} and {@link #decrypt(java.io.InputStream, java.io.OutputStream, byte[])}). <p/> Default size is {@code 512} bytes.

Inherited Members

From CipherService

decrypt ByteSource decrypt(byte[] encrypted, byte[] decryptionKey): 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.
encrypt ByteSource encrypt(byte[] raw, byte[] encryptionKey): Encrypts data via the specified cipher key. Note that the key must be in a format understood by the {@code CipherService} implementation.