JCAPISymmetricCipherDynamic (Pheox JCAPI)

Package

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

com.pheox.jcapi
Class JCAPISymmetricCipherDynamic

java.lang.Object
  javax.crypto.CipherSpi
      com.pheox.jcapi.JCAPISymmetricCipherDynamic

Direct Known Subclasses:: JCAPISymmetricCipherDynamic.AES, JCAPISymmetricCipherDynamic.DES, JCAPISymmetricCipherDynamic.RC2, JCAPISymmetricCipherDynamic.RC4, JCAPISymmetricCipherDynamic.TripleDES

public class JCAPISymmetricCipherDynamic
extends javax.crypto.CipherSpi
extends javax.crypto.CipherSpi

This is the base class for all symmetric ciphers supported in JCAPI. Currently, the following symmetric ciphers are supported:

AES - See class JCAPISymmetricCipherDynamic.AES
Triple DES - See class JCAPISymmetricCipherDynamic.TripleDES
DES - See class JCAPISymmetricCipherDynamic.DES
RC2 - See class JCAPISymmetricCipherDynamic.RC2
RC4 - See class JCAPISymmetricCipherDynamic.RC4

This class is also used by JCAPICryptoFactory when the programmer wants to create a customized version of a symmetric cipher, for more information please see method JCAPICryptoFactory.createCipherInstance(JCAPICSPAlgorithm).

Note: only the classes available in JCAPI shall inherit, or instantiate this class.

This class contains the base logic about symmetric ciphers since most of them do work very similar e.g. it manages block sizes, cipher modes, padding schemes etc that are common for most ciphers. Some hard coded solutions have been implemented since some ciphers require unique settings and parameters e.g. the RC2 algorithm needs an effective key length to be set. So, even though this class is very generic, it can't support all symmetric ciphers that exist due to special details required by them.

Even though this class handles the generic operations for all JCAPI supported symmetric ciphers, each operation is delegated further on to MS CAPI which then lets the chosen CSP execute them i.e. all cryptographic operations including encryption, decryption, padding etc are performed the native MS CAPI CSP implementation.

To learn more about how this class can be used, please look at the following example programs that can be found in JCAPI's examples directory, by default located in C:\<application data directory>\JCAPI\examples:

cipher\Cipher3DES.java
cipher\CipherAES128.java
cipher\CipherAES192.java
cipher\CipherAES256.java
cipher\CipherDES.java
cipher\CipherRC2.java
cipher\CipherRC4.java
cipher\WrapSymmetricKey.java
cryptofactory\cipher\DynamicCipher3DES.java
cryptofactory\cipher\DynamicCipherAES.java
cryptofactory\cipher\DynamicCipherDES.java
cryptofactory\cipher\DynamicCipherRC2.java
cryptofactory\cipher\DynamicCipherRC4.java

Since:: 2.0

Nested Class Summary
`static class`	`JCAPISymmetricCipherDynamic.AES` The AES (Advanced Encryption Standard) symmetric cipher class.
`static class`	`JCAPISymmetricCipherDynamic.DES` The DES (Data Encryption Standard) symmetric cipher class.
`static class`	`JCAPISymmetricCipherDynamic.RC2` The RC2 (Rivest Cipher 2) symmetric cipher class.
`static class`	`JCAPISymmetricCipherDynamic.RC4` The RC4 (Rivest Cipher 4) symmetric stream cipher class.
`static class`	`JCAPISymmetricCipherDynamic.TripleDES` The Triple DES (Data Encryption Standard) symmetric cipher class.

Method Summary
`protected byte[]`	`engineDoFinal(byte[] input, int inputOffset, int inputLen)` Encrypts or decrypts data in a single-part operation, or finishes a multiple-part operation.
`protected int`	`engineDoFinal(byte[] input, int inputOffset, int inputLen, byte[] output, int outputOffset)` Encrypts or decrypts data in a single-part operation, or finishes a multiple-part operation.
`protected int`	`engineGetBlockSize()` Returns the block size (in bytes).
`protected byte[]`	`engineGetIV()` Returns the initialization vector.
`protected int`	`engineGetKeySize(java.security.Key key)` Returns the key size of the given key object in bits.
`protected int`	`engineGetOutputSize(int inputLen)` Returns the length in bytes that an output buffer would need to be in order to hold the result of the next `update` or `doFinal` operation, given the input length `inputLen` (in bytes).
`protected java.security.AlgorithmParameters`	`engineGetParameters()` Returns the parameters used with this cipher.
`protected void`	`engineInit(int opmode, java.security.Key key, java.security.spec.AlgorithmParameterSpec params, java.security.SecureRandom random)` The cipher is initialized for one of the following four operations: encryption, decryption, key wrapping or key unwrapping, depending on the value of `opmode`.
`protected void`	`engineInit(int opmode, java.security.Key key, java.security.AlgorithmParameters params, java.security.SecureRandom random)` The cipher is initialized for one of the following four operations: encryption, decryption, key wrapping or key unwrapping, depending on the value of `opmode`.
`protected void`	`engineInit(int opmode, java.security.Key key, java.security.SecureRandom random)` The cipher is initialized for one of the following four operations: encryption, decryption, key wrapping or key unwrapping, depending on the value of `opmode`.
`protected void`	`engineSetMode(java.lang.String mode)` Sets the mode of this cipher.
`protected void`	`engineSetPadding(java.lang.String padding)` Sets the padding mechanism of this cipher.
`protected java.security.Key`	`engineUnwrap(byte[] wrappedKey, java.lang.String wrappedKeyAlgorithm, int wrappedKeyType)` Unwraps (decrypts) a previously wrapped key.
`protected byte[]`	`engineUpdate(byte[] input, int inputOffset, int inputLen)` Continues a multiple-part encryption or decryption operation (depending on how this cipher was initialized), processing another data part.
`protected int`	`engineUpdate(byte[] input, int inputOffset, int inputLen, byte[] output, int outputOffset)` Continues a multiple-part encryption or decryption operation (depending on how this cipher was initialized), processing another data part.
`protected byte[]`	`engineWrap(java.security.Key key)` Wraps (encrypts) a key.

Methods inherited from class javax.crypto.CipherSpi
`engineDoFinal, engineUpdate`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Method Detail

engineDoFinal

protected byte[] engineDoFinal(byte[] input,
                               int inputOffset,
                               int inputLen)
                        throws javax.crypto.IllegalBlockSizeException,
                               javax.crypto.BadPaddingException

Encrypts or decrypts data in a single-part operation, or finishes a multiple-part operation. The data is encrypted or decrypted, depending on how this cipher was initialized.

The first inputLen bytes in the input buffer, starting at inputOffset inclusive, and any input bytes that may have been buffered previous update operation, are processed, with padding being applied (if it's a block cipher). The result is stored in a new buffer.

Important! This method will reset the instance when it has completed, or if an exception occurs; meaning that you have to call one of the engineInit methods provided by this class before you can use the instance again.

Specified by:: engineDoFinal in class javax.crypto.CipherSpi

Parameters:: input - the input buffer.; inputOffset - the offset in input where the input starts.; inputLen - the input length.
Returns:: the new buffer with the result.
Throws:: javax.crypto.IllegalBlockSizeException - if no padding has been requested (only in encryption mode), and the total input length of the data processed by this cipher is not a multiple of block size.; javax.crypto.BadPaddingException - if this cipher is in decryption mode, and (un)padding has been requested, but the decrypted data is not bounded by the appropriate padding bytes.; JCAPIJNIRuntimeException - if an unexpected error occur inside MS CAPI.
Since:: 2.0

engineDoFinal

protected int engineDoFinal(byte[] input,
                            int inputOffset,
                            int inputLen,
                            byte[] output,
                            int outputOffset)
                     throws javax.crypto.IllegalBlockSizeException,
                            javax.crypto.ShortBufferException,
                            javax.crypto.BadPaddingException

Encrypts or decrypts data in a single-part operation, or finishes a multiple-part operation. The data is encrypted or decrypted, depending on how this cipher was initialized.

The first inputLen bytes in the input buffer, starting at inputOffset inclusive, and any input bytes that may have been buffered during a previous update operation, are processed, with padding (if requested) being applied. The result is stored in the output buffer, starting at outputOffset inclusive.

If the output buffer is too small to hold the result, a ShortBufferException is thrown.

Specified by:: engineDoFinal in class javax.crypto.CipherSpi

Parameters:: input - the input buffer.; inputOffset - the offset in input where the input starts.; inputLen - the input length.; output - the buffer for the result.; outputOffset - the offset in output where the result is stored.
Returns:: the number of bytes stored in output.
Throws:: javax.crypto.IllegalBlockSizeException - if no padding has been requested (only in encryption mode), and the total input length of the data processed by this cipher is not a multiple of block size.; javax.crypto.ShortBufferException - if the given output buffer is too small to hold the result.; javax.crypto.BadPaddingException - if this cipher is in decryption mode, and (un)padding has been requested, but the decrypted data is not bounded by the appropriate padding bytes.; JCAPIJNIRuntimeException - if an unexpected error occur inside MS CAPI.
Since:: 2.0

engineGetBlockSize

protected int engineGetBlockSize()

Returns the block size (in bytes).

If the symmetric algorithm is not block based i.e. a stream cipher, then value zero is returned.

Specified by:: engineGetBlockSize in class javax.crypto.CipherSpi

Returns:: the block size (in bytes).
Since:: 2.0

engineGetIV

protected byte[] engineGetIV()

Returns the initialization vector. If the algorithm do not use initialization vectors, then null is returned.

Specified by:: engineGetIV in class javax.crypto.CipherSpi

Returns:: the initialization vector, or null if no such vector exist for the algorithm.
Since:: 2.0

engineGetKeySize

protected int engineGetKeySize(java.security.Key key)
                        throws java.security.InvalidKeyException

Returns the key size of the given key object in bits.

Overrides:: engineGetKeySize in class javax.crypto.CipherSpi

Parameters:: key - the key object.
Returns:: the key size of the given key object.
Throws:: java.security.InvalidKeyException - if the parameter key object is not an instance of javax.crypto.SecretKey.
Since:: 2.0

engineGetOutputSize

protected int engineGetOutputSize(int inputLen)

Returns the length in bytes that an output buffer would need to be in order to hold the result of the next update or doFinal operation, given the input length inputLen (in bytes).

Specified by:: engineGetOutputSize in class javax.crypto.CipherSpi

Parameters:: inputLen - the input length (in bytes).
Returns:: the required output buffer size (in bytes).
Since:: 2.0

engineGetParameters

protected java.security.AlgorithmParameters engineGetParameters()

Returns the parameters used with this cipher.

The returned parameters may be the same that were used to initialize this cipher, or may contain a combination of default and random parameter values used by the underlying cipher implementation if this cipher requires algorithm parameters but was not initialized with any.

Currently, only javax.crypto.spec.IvParameterSpec and javax.crypto.spec.RC2ParameterSpec instances are supported by this method.

Specified by:: engineGetParameters in class javax.crypto.CipherSpi

Returns:: the parameters used with this cipher, or null if none has been used.
Since:: 2.0

engineInit

protected void engineInit(int opmode,
                          java.security.Key key,
                          java.security.spec.AlgorithmParameterSpec params,
                          java.security.SecureRandom random)
                   throws java.security.InvalidKeyException

The cipher is initialized for one of the following four operations: encryption, decryption, key wrapping or key unwrapping, depending on the value of opmode.

This cipher implementation accepts only keys of type javax.crypto.SecretKey. Keys of any other types will result in a InvalidKeyException being thrown.

If this cipher requires any algorithm parameters and params is null, then this implementation will generate the required parameters itself if it is being initialized for encryption or key wrapping. The generated parameters can be retrieved using engineGetParameters() or engineGetIV() (if the parameter is an IV).

If this cipher (including its underlying feedback or padding scheme) requires any random bytes (e.g., for parameter generation), it will get them from random.

Specified by:: engineInit in class javax.crypto.CipherSpi

Parameters:: opmode - the operation mode of this cipher (this is one of the following: javax.crypto.ENCRYPT_MODE, javax.crypto.DECRYPT_MODE, javax.crypto.WRAP_MODE or javax.crypto.UNWRAP_MODE).; key - the SecretKey key object.; params - the algorithm parameters. Currently, only IvParameterSpec and RC2ParameterSpec are supported by JCAPI.; random - the source of randomness.
Throws:: java.security.InvalidKeyException - if the given key is inappropriate for initializing this cipher e.g. the key is too big, or an unsupported key algorithm.; JCAPIJNIRuntimeException - if an unexpected error occur inside MS CAPI.
Since:: 2.0

engineInit

protected void engineInit(int opmode,
                          java.security.Key key,
                          java.security.AlgorithmParameters params,
                          java.security.SecureRandom random)
                   throws java.security.InvalidKeyException

The cipher is initialized for one of the following four operations: encryption, decryption, key wrapping or key unwrapping, depending on the value of opmode.

This cipher implementation accepts only keys of type javax.crypto.SecretKey. Keys of any other types will result in a InvalidKeyException being thrown.

If this cipher (including its underlying feedback or padding scheme) requires any random bytes (e.g., for parameter generation), it will get them from random.

Specified by:: engineInit in class javax.crypto.CipherSpi

Parameters:: opmode - the operation mode of this cipher (this is one of the following: ENCRYPT_MODE, DECRYPT_MODE, WRAP_MODE or UNWRAP_MODE).; key - the SecretKey key object.; params - the algorithm parameters. Currently, only IvParameterSpec and RC2ParameterSpec can only be retrieved from params by this implementation.; random - the source of randomness.
Throws:: java.security.InvalidKeyException - if the given key is inappropriate for initializing this cipher; JCAPIJNIRuntimeException - if an unexpected error occur inside MS CAPI.
Since:: 2.0

engineInit

protected void engineInit(int opmode,
                          java.security.Key key,
                          java.security.SecureRandom random)
                   throws java.security.InvalidKeyException

The cipher is initialized for one of the following four operations: encryption, decryption, key wrapping or key unwrapping, depending on the value of opmode.

This cipher implementation accepts only keys of type javax.crypto.SecretKey. Keys of any other types will result in a InvalidKeyException being thrown.

If this cipher (including its underlying feedback or padding scheme) requires any random bytes (e.g., for parameter generation), it will get them from random.

Specified by:: engineInit in class javax.crypto.CipherSpi

Parameters:: opmode - the operation mode of this cipher (this is one of the following: ENCRYPT_MODE, DECRYPT_MODE, WRAP_MODE or UNWRAP_MODE).; key - the key object.; random - the source of randomness.
Throws:: java.security.InvalidKeyException - if the given key is inappropriate for initializing this cipher e.g. the key is too big, or an unsupported key algorithm.; JCAPIJNIRuntimeException - if an unexpected error occur inside MS CAPI.
Since:: 2.0

engineSetMode

protected void engineSetMode(java.lang.String mode)
                      throws java.security.NoSuchAlgorithmException

Sets the mode of this cipher.

The following modes are known by JCAPI:

ECB
CBC
OFB
CFB
CTS

Note: even though these modes are known by JCAPI, it doesn't mean that all of them are supported by all MS CAPI CSPs.

Specified by:: engineSetMode in class javax.crypto.CipherSpi

Parameters:: mode - the cipher mode.
Throws:: java.security.NoSuchAlgorithmException - if given mode is not known by JCAPI.
Since:: 2.0

engineSetPadding

protected void engineSetPadding(java.lang.String padding)
                         throws javax.crypto.NoSuchPaddingException

Sets the padding mechanism of this cipher.

The following strings are accepted (case insensitive):

PKCS1
PKCS#1
PKCS1Padding
RandomPadding
ZeroPadding

Specified by:: engineSetPadding in class javax.crypto.CipherSpi

Parameters:: padding - the padding mechanism.
Throws:: javax.crypto.NoSuchPaddingException - if the requested padding mechanism does not exist.
Since:: 2.0

engineUnwrap

protected java.security.Key engineUnwrap(byte[] wrappedKey,
                                         java.lang.String wrappedKeyAlgorithm,
                                         int wrappedKeyType)
                                  throws java.security.NoSuchAlgorithmException,
                                         java.security.InvalidKeyException

Unwraps (decrypts) a previously wrapped key.

The wrapped key can be of type javax.crypto.Cipher.SECRET_KEY, javax.crypto.Cipher.PUBLIC_KEY, or javax.crypto.Cipher.PRIVATE_KEY.

If the wrapped key is of type javax.crypto.Cipher.SECRET_KEY, then it will be rebuilt as a SecretKeySpec instance.

If the wrapped key is of type javax.crypto.Cipher.PUBLIC_KEY, then it will be rebuilt as a X509EncodedKeySpec instance.

If the wrapped key is of type javax.crypto.Cipher.PRIVATE_KEY, then it will be rebuilt as a PKCS8EncodedKeySpec instance.

Overrides:: engineUnwrap in class javax.crypto.CipherSpi

Parameters:: wrappedKey - the wrapped secret key to be unwrapped.; wrappedKeyAlgorithm - the algorithm associated with the wrapped key.; wrappedKeyType - the type of the wrapped key. It must be either javax.crypto.Cipher.SECRET_KEY, javax.crypto.Cipher.PUBLIC_KEY, or javax.crypto.Cipher.PRIVATE_KEY.
Returns:: the unwrapped key.
Throws:: java.security.NoSuchAlgorithmException - if the key of type wrappedKeyType for the wrappedKeyAlgorithm cannot be created.; java.security.InvalidKeyException - if wrappedKey does not represent a wrapped key of type wrappedKeyType for the wrappedKeyAlgorithm.; JCAPIJNIRuntimeException - if an unexpected error occur inside MS CAPI.
Since:: 2.0

engineUpdate

protected byte[] engineUpdate(byte[] input,
                              int inputOffset,
                              int inputLen)

Continues a multiple-part encryption or decryption operation (depending on how this cipher was initialized), processing another data part.

The first inputLen bytes in the input buffer, starting at inputOffset inclusive, are processed, and the result is stored in a new buffer.

Important! This method will reset the cipher instance if an exception occurs; meaning that you have to call one of the engineInit methods provided by this class before you can use the cipher instance again.

Specified by:: engineUpdate in class javax.crypto.CipherSpi

Parameters:: input - the input buffer.; inputOffset - the offset in input where the input starts.; inputLen - the input length.
Returns:: the new buffer with the result, or null if the underlying cipher is a block cipher and the input data is too short to result in a new block.
Throws:: JCAPIJNIRuntimeException - if an unexpected error occur inside MS CAPI.
Since:: 2.0

engineUpdate

protected int engineUpdate(byte[] input,
                           int inputOffset,
                           int inputLen,
                           byte[] output,
                           int outputOffset)
                    throws javax.crypto.ShortBufferException

Continues a multiple-part encryption or decryption operation (depending on how this cipher was initialized), processing another data part.

The first inputLen bytes in the input buffer, starting at inputOffset inclusive, are processed, and the result is stored in the output buffer, starting at outputOffset inclusive.

If the output buffer is too small to hold the result, a ShortBufferException is thrown.

Specified by:: engineUpdate in class javax.crypto.CipherSpi

Parameters:: input - the input buffer.; inputOffset - the offset in input where the input starts.; inputLen - the input length.; output - the buffer for the result.; outputOffset - the offset in output where the result is stored.
Returns:: the number of bytes stored in output.
Throws:: JCAPIJNIRuntimeException - if an unexpected error occur inside MS CAPI.; javax.crypto.ShortBufferException
Since:: 2.0

engineWrap

protected byte[] engineWrap(java.security.Key key)
                     throws javax.crypto.IllegalBlockSizeException,
                            java.security.InvalidKeyException

Wraps (encrypts) a key.

This class support wrapping of keys of instance SecretKey, PrivateKey, and PublicKey.
It uses the Key.getEncoded() method of the key instance to get its raw key material to be wrapped.

Overrides:: engineWrap in class javax.crypto.CipherSpi

Parameters:: key - the key to be wrapped.
Returns:: the wrapped key.
Throws:: javax.crypto.IllegalBlockSizeException - if padding fails.; java.security.InvalidKeyException - if key is not an instance of SecretKey, PrivateKey, or PublicKey.; JCAPIJNIRuntimeException - if an unexpected error occur inside MS CAPI.
Since:: 2.0

Package

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

com.pheox.jcapi Class JCAPISymmetricCipherDynamic

engineDoFinal

engineDoFinal

engineGetBlockSize

engineGetIV

engineGetKeySize

engineGetOutputSize

engineGetParameters

engineInit

engineInit

engineInit

engineSetMode

engineSetPadding

engineUnwrap

engineUpdate

engineUpdate

engineWrap

com.pheox.jcapi
Class JCAPISymmetricCipherDynamic