public class DefaultBlockCipherService extends AbstractSymmetricCipherService
AesCipherService
, BlowfishCipherService
, and others are usually better suited for regular use.
However, if you have the need to create a custom block cipher service where no sufficient algorithm-specific subclass
exists in Shiro, this class would be very useful.
DefaultBlockCipherService
s have attributes that can be set individually in
a type-safe manner based on your configuration needs, and Shiro will build the transformation string for you.
The following sections typically document the configuration options for block (byte array)
JcaCipherService.encrypt(byte[], byte[])
and JcaCipherService.decrypt(byte[], byte[])
method invocations. Streaming configuration
for those same attributes are done via mirrored streaming
* attributes, and their purpose is identical, but
they're only used during streaming JcaCipherService.encrypt(java.io.InputStream, java.io.OutputStream, byte[])
and
JcaCipherService.decrypt(java.io.InputStream, java.io.OutputStream, byte[])
methods. See the "Streaming"
section below for more.
blockSize
attribute. If not set, the JCA Provider
default will be used based on the cipher algorithm. Block sizes are usually very algorithm specific, so set this
value only if you know you don't want the JCA Provider's default for the desired algorithm. For example, the
AES algorithm's Rijndael implementation only supports a 128 bit block size and will not work with any other
size.
Also note that the initializationVectorSize
is usually the same as the
blockSize
in block ciphers. If you change either attribute, you should ensure that the other
attribute is correct for the target cipher algorithm.
mode
attribute, which accepts a type-safe
OperationMode
enum instance. This type safety helps avoid typos when specifying the mode and
guarantees that the mode name will be recognized by the underlying JCA Provider.
*If no operation mode is specified, Shiro defaults all of its block CipherService
instances to the
CBC
mode, specifically to support auto-generation of initialization vectors during
encryption. This is different than the JDK's default ECB
mode because ECB
does
not support initialization vectors, which are necessary for strong encryption. See the
JcaCipherService parent class
class JavaDoc for an extensive
explanation on why we do this and why we do not use the Sun ECB
default. You also might also want read
the Wikipedia
section on ECB and look at the encrypted image to see an example of why ECB
should not be used in
security-sensitive environments.
In the rare case that you need to override the default with a mode not represented
by the OperationMode
enum, you may specify the raw mode name string that will be recognized by your JCA
provider via the modeName
attribute. Because this is not type-safe, it is recommended only to
use this attribute if the OperationMode
enum does not represent your desired mode.
NOTE: If you change the mode to one that does not support initialization vectors (such as
ECB
or NONE
), you must turn off auto-generated
initialization vectors by setting generateInitializationVectors
to false
. Abandoning initialization vectors significantly weakens encryption, so think twice before
disabling this feature.
paddingScheme
attribute, which
accepts a type-safe PaddingScheme
enum instance. Like the OperationMode
enum,
this enum offers type safety to help avoid typos and guarantees that the mode will be recongized by the underlying
JCA provider.
*If no padding scheme is specified, this class defaults to the PaddingScheme.PKCS5
scheme, specifically
to be compliant with the default behavior of auto-generating initialization vectors during encryption (see the
JcaCipherService parent class
class JavaDoc for why).
In the rare case that you need to override the default with a scheme not represented by the PaddingScheme
enum, you may specify the raw padding scheme name string that will be recognized by your JCA provider via the
paddingSchemeName
attribute. Because this is not type-safe, it is recommended only to
use this attribute if the PaddingScheme
enum does not represent your desired scheme.
operation mode
with a streaming block size
of 8 bits. This is why the CipherService
interface provides both block and streaming operations.
Because this streaming 8-bit block size rarely changes across block-cipher algorithms, default values have been set
for all three streaming configuration parameters. The defaults are:
streamingBlockSize
= 8
(bits)streamingMode
= CBC
streamingPaddingScheme
= PKCS5
mode
, blockSize
, and paddingScheme
attributes
described above, but they are applied during streaming method invocations only (JcaCipherService.encrypt(java.io.InputStream, java.io.OutputStream, byte[])
and JcaCipherService.decrypt(java.io.InputStream, java.io.OutputStream, byte[])
).BlowfishCipherService
,
AesCipherService
,
Wikipedia: Block Cipher Modes of OperationConstructor and Description |
---|
DefaultBlockCipherService(String algorithmName)
Creates a new
DefaultBlockCipherService using the specified block cipher algorithmName . |
Modifier and Type | Method and Description |
---|---|
protected byte[] |
generateInitializationVector(boolean streaming) |
int |
getBlockSize()
|
String |
getModeName()
|
String |
getPaddingSchemeName()
|
int |
getStreamingBlockSize() |
String |
getStreamingModeName()
Same purpose as the
modeName attribute, but is used instead only for for streaming
operations (JcaCipherService.encrypt(java.io.InputStream, java.io.OutputStream, byte[]) and
JcaCipherService.decrypt(java.io.InputStream, java.io.OutputStream, byte[]) ). |
String |
getStreamingPaddingSchemeName() |
protected String |
getTransformationString(boolean streaming)
Returns the transformation string to use with the
Cipher.getInstance(java.lang.String) call. |
protected boolean |
isGenerateInitializationVectors(boolean streaming)
Overrides the parent implementation to ensure initialization vectors are always generated if streaming is
enabled (block ciphers must use initialization vectors if they are to be used as a stream cipher).
|
void |
setBlockSize(int blockSize)
Sets the block cipher's block size to be used when constructing
Cipher transformation string. |
void |
setMode(OperationMode mode)
Sets the cipher operation mode of operation to be used when constructing the
Cipher transformation string. |
void |
setModeName(String modeName)
Sets the cipher operation mode name to be used when constructing the
Cipher transformation string. |
void |
setPaddingScheme(PaddingScheme paddingScheme)
Sets the padding scheme to be used when constructing the
Cipher transformation string. |
void |
setPaddingSchemeName(String paddingSchemeName)
|
void |
setStreamingBlockSize(int streamingBlockSize) |
void |
setStreamingMode(OperationMode mode)
Sets the transformation string mode to be used for streaming operations only.
|
void |
setStreamingModeName(String streamingModeName)
Sets the transformation string mode name to be used for streaming operations only.
|
void |
setStreamingPaddingScheme(PaddingScheme scheme) |
void |
setStreamingPaddingSchemeName(String streamingPaddingSchemeName) |
generateNewKey, generateNewKey
createParameterSpec, decrypt, decrypt, encrypt, encrypt, ensureSecureRandom, getAlgorithmName, getDefaultSecureRandom, getInitializationVectorSize, getKeySize, getSecureRandom, getStreamingBufferSize, isGenerateInitializationVectors, setGenerateInitializationVectors, setInitializationVectorSize, setKeySize, setSecureRandom, setStreamingBufferSize
public DefaultBlockCipherService(String algorithmName)
DefaultBlockCipherService
using the specified block cipher algorithmName
. Per this
class's JavaDoc, this constructor also sets the following defaults:
All other attributes are null/unset, indicating the JCA Provider defaults will be used.algorithmName
- the block cipher algorithm to use when encrypting and decryptingpublic String getModeName()
Cipher
transformation string or null
if the JCA Provider default mode for
the specified algorithm
should be used.
This attribute is used only when constructing the transformation string for block (byte array)
operations (JcaCipherService.encrypt(byte[], byte[])
and JcaCipherService.decrypt(byte[], byte[])
). The
streamingModeName
attribute is used when the block cipher is used for
streaming operations.
The default value is null
to retain the JCA Provider default.public void setModeName(String modeName)
Cipher
transformation string. A null
value indicates that the JCA Provider
default mode for the specified algorithm
should be used.
This attribute is used only when constructing the transformation string for block (byte array)
operations (JcaCipherService.encrypt(byte[], byte[])
and JcaCipherService.decrypt(byte[], byte[])
). The
streamingModeName
attribute is used when the block cipher is used for
streaming operations.
The default value is null
to retain the JCA Provider default.
NOTE: most standard mode names are represented by the OperationMode
enum. That enum
should be used with the mode
attribute when possible to retain type-safety and reduce the
possibility of errors. This method is better used if the OperationMode
enum does not represent the
necessary mode.modeName
- the cipher operation mode name to be used when constructing
Cipher
transformation string, or null
if the JCA Provider
default mode for the specified algorithm
should be used.setMode(org.apache.shiro.crypto.OperationMode)
public void setMode(OperationMode mode)
Cipher
transformation string. A null
value indicates that the JCA Provider
default mode for the specified algorithm
should be used.
This attribute is used only when constructing the transformation string for block (byte array)
operations (JcaCipherService.encrypt(byte[], byte[])
and JcaCipherService.decrypt(byte[], byte[])
). The
streamingMode
attribute is used when the block cipher is used for
streaming operations.
If the OperationMode
enum cannot represent your desired mode, you can set the name explicitly
via the modeName
attribute directly. However, because OperationMode
represents all
standard JDK mode names already, ensure that your underlying JCA Provider supports the non-standard name first.public String getPaddingSchemeName()
Cipher
transformation string or null
if the JCA Provider default mode for
the specified algorithm
should be used.
This attribute is used only when constructing the transformation string for block (byte array)
operations (JcaCipherService.encrypt(byte[], byte[])
and JcaCipherService.decrypt(byte[], byte[])
). The
streamingPaddingSchemeName
attribute is used when the block cipher is
used for streaming operations.
The default value is null
to retain the JCA Provider default.public void setPaddingSchemeName(String paddingSchemeName)
Cipher
transformation string, or null
if the JCA Provider default mode for
the specified algorithm
should be used.
This attribute is used only when constructing the transformation string for block (byte array)
operations (JcaCipherService.encrypt(byte[], byte[])
and JcaCipherService.decrypt(byte[], byte[])
). The
streamingPaddingSchemeName
attribute is used when the block cipher is
used for streaming operations.
The default value is null
to retain the JCA Provider default.
NOTE: most standard padding schemes are represented by the PaddingScheme
enum.
That enum should be used with the paddingScheme
attribute when possible to retain
type-safety and reduce the possibility of errors. Calling this method however is suitable if the
PaddingScheme
enum does not represent the desired scheme.paddingSchemeName
- the padding scheme name to be used when constructing
Cipher
transformation string, or null
if the JCA
Provider default padding scheme for the specified algorithm
should be used.setPaddingScheme(org.apache.shiro.crypto.PaddingScheme)
public void setPaddingScheme(PaddingScheme paddingScheme)
Cipher
transformation string. A null
value indicates that the JCA Provider
default padding scheme for the specified algorithm
should be used.
This attribute is used only when constructing the transformation string for block (byte array)
operations (JcaCipherService.encrypt(byte[], byte[])
and JcaCipherService.decrypt(byte[], byte[])
). The
streamingPaddingScheme
attribute is used when the block cipher is used for
streaming operations.
If the PaddingScheme
enum does represent your desired scheme, you can set the name explicitly
via the paddingSchemeName
attribute directly. However, because
PaddingScheme
represents all standard JDK scheme names already, ensure that your underlying JCA Provider
supports the non-standard name first.public int getBlockSize()
Cipher
transformation string or 0
if the JCA Provider default block size
for the specified algorithm
should be used.
This attribute is used only when constructing the transformation string for block (byte array)
operations (JcaCipherService.encrypt(byte[], byte[])
and JcaCipherService.decrypt(byte[], byte[])
). The
streamingBlockSize
attribute is used when the block cipher is used for
streaming operations.
The default value is 0
which retains the JCA Provider default.public void setBlockSize(int blockSize)
Cipher
transformation string. 0
indicates that the JCA Provider default
block size for the specified algorithm
should be used.
This attribute is used only when constructing the transformation string for block (byte array)
operations (JcaCipherService.encrypt(byte[], byte[])
and JcaCipherService.decrypt(byte[], byte[])
). The
streamingBlockSize
attribute is used when the block cipher is used for
streaming operations.
The default value is 0
which retains the JCA Provider default.
NOTE: block cipher block sizes are very algorithm-specific. If you change this value, ensure that it
will work with the specified algorithm
.public String getStreamingModeName()
modeName
attribute, but is used instead only for for streaming
operations (JcaCipherService.encrypt(java.io.InputStream, java.io.OutputStream, byte[])
and
JcaCipherService.decrypt(java.io.InputStream, java.io.OutputStream, byte[])
).
Note that unlike the modeName
attribute, the default value of this attribute is not
null
- it is CBC
for reasons described in the class-level JavaDoc in the
Streaming
section.public void setStreamingModeName(String streamingModeName)
CBC
for reasons described in the class-level JavaDoc in the Streaming
section.streamingModeName
- transformation string mode name to be used for streaming operations onlypublic void setStreamingMode(OperationMode mode)
CBC
for reasons described in the class-level JavaDoc in the Streaming
section.mode
- the transformation string mode to be used for streaming operations onlypublic String getStreamingPaddingSchemeName()
public void setStreamingPaddingSchemeName(String streamingPaddingSchemeName)
public void setStreamingPaddingScheme(PaddingScheme scheme)
public int getStreamingBlockSize()
public void setStreamingBlockSize(int streamingBlockSize)
protected String getTransformationString(boolean streaming)
Cipher.getInstance(java.lang.String)
call. If
streaming
is true
, a block-cipher transformation string compatible with streaming operations will
be constructed and cached for re-use later (see the class-level JavaDoc for more on using block ciphers
for streaming). If streaming
is false
a normal block-cipher transformation string will
be constructed and cached for later re-use.getTransformationString
in class JcaCipherService
streaming
- if the transformation string is going to be used for a Cipher performing stream-based encryption or not.protected boolean isGenerateInitializationVectors(boolean streaming)
modeName
is compatible with initialization vectors as well as the result of the configured
generateInitializationVectors
value.isGenerateInitializationVectors
in class JcaCipherService
streaming
- whether or not streaming is being performedtrue
if streaming or a value computed based on if the currently configured mode is compatible
with initialization vectors.protected byte[] generateInitializationVector(boolean streaming)
generateInitializationVector
in class JcaCipherService
Copyright © 2004–2019 The Apache Software Foundation. All rights reserved.