com.ibm.cloud.objectstorage.services.s3.internal.crypto

Class CipherLite

java.lang.Object

com.ibm.cloud.objectstorage.services.s3.internal.crypto.CipherLite

Direct Known Subclasses:

GCMCipherLite

public class CipherLite
extends Object

Functions like a Cipher but provides only a subset of all the interface methods of Cipher. This class is intended to be used in lieu of the underlying Cipher directly whenever applicable. For example, this class makes it easy to generate an inverse cipher, or to create an "auxiliary" cipher for use with get-range or multi-part upload operations. A subclass may also support the mark and reset operations to enable parts of a plaintext to be re-processed which is useful for error recovery typical when network transmission is involved.

However a cipher lite, unlike a Cipher, can only be used once, and cannot be reused after the CipherLite.doFinal() methods have been invoked. In other words, it is NOT true that, upon finishing, the doFinal method will reset the cipher lite object to the state it was in when first constructed.

Author:

Hanson Char

See Also:

GCMCipherLite

Field Summary

Fields

Modifier and Type	Field and Description
static CipherLite	Null A no-op implementation.

Method Summary

Modifier and Type	Method and Description
CipherLite	createAuxiliary(long startingBytePos) Returns an auxiliary CipherLite for partial plaintext re-encryption (or re-decryption) purposes.
CipherLite	createInverse() Returns the inverse of the current CipherLite.
CipherLite	createUsingIV(byte[] iv) Creates a new instance of CipherLite from the current one, but using the given IV.
byte[]	doFinal() Finishes a multiple-part encryption or decryption operation, depending on how the underlying cipher was initialized.
byte[]	doFinal(byte[] input) Encrypts or decrypts data in a single-part operation, or finishes a multiple-part operation.
byte[]	doFinal(byte[] input, int inputOffset, int inputLen) Encrypts or decrypts data in a single-part operation, or finishes a multiple-part operation.
int	getBlockSize() Returns the block size (in bytes).
Cipher	getCipher() This method is provided only for testing purposes.
String	getCipherAlgorithm() Returns the algorithm name of the underlying cipher.
Provider	getCipherProvider() Returns the provider of the underlying cipher.
ContentCryptoScheme	getContentCryptoScheme()
byte[]	getIV() Returns the initialization vector (IV) in a new buffer.
String	getSecretKeyAlgorithm() Returns the standard algorithm name for the secret key.
long	mark() Marks the current position in this cipher lite.
boolean	markSupported() Tests if this cipher lite supports the mark and reset methods.
CipherLite	recreate() Recreates a new instance of CipherLite from the current one.
void	reset() Repositions this cipher lite to the position at the time the mark method was last called.
byte[]	update(byte[] input, int inputOffset, int inputLen) Continues a multiple-part encryption or decryption operation (depending on how the underlying cipher was initialized), processing another data part.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

Null

public static final CipherLite Null

A no-op implementation.

Method Detail

recreate

public CipherLite recreate()

Recreates a new instance of CipherLite from the current one.

createUsingIV

public CipherLite createUsingIV(byte[] iv)

Creates a new instance of CipherLite from the current one, but using the given IV.

createAuxiliary

public CipherLite createAuxiliary(long startingBytePos)
                           throws InvalidKeyException,
                                  NoSuchAlgorithmException,
                                  NoSuchProviderException,
                                  NoSuchPaddingException,
                                  InvalidAlgorithmParameterException

Returns an auxiliary CipherLite for partial plaintext re-encryption (or re-decryption) purposes.

Parameters:

startingBytePos - the starting byte position of the plaintext. Must be a multiple of the cipher block size.

Throws:

InvalidKeyException

NoSuchAlgorithmException

NoSuchProviderException

NoSuchPaddingException

InvalidAlgorithmParameterException

createInverse

public CipherLite createInverse()
                         throws InvalidKeyException,
                                NoSuchAlgorithmException,
                                NoSuchProviderException,
                                NoSuchPaddingException,
                                InvalidAlgorithmParameterException

Returns the inverse of the current CipherLite.

Throws:

InvalidKeyException

NoSuchAlgorithmException

NoSuchProviderException

NoSuchPaddingException

InvalidAlgorithmParameterException

doFinal

public byte[] doFinal()
               throws IllegalBlockSizeException,
                      BadPaddingException

Finishes a multiple-part encryption or decryption operation, depending on how the underlying cipher was initialized.

Input data that may have been buffered during a previous update operation is processed, with padding (if requested) being applied. If an AEAD mode such as GCM/CCM is being used, the authentication tag is appended in the case of encryption, or verified in the case of decryption. The result is stored in a new buffer.

Note: if any exception is thrown, a new instance of this cipher lite object may need to be constructed before it can be used again. be reconstructed before it can be used again.

Returns:

the new buffer with the result

Throws:

IllegalStateException - if this cipher is in a wrong state (e.g., has not been initialized)

IllegalBlockSizeException - if this cipher is a block cipher, 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; or if this encryption algorithm is unable to process the input data provided.

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

AEADBadTagException - if this cipher is decrypting in an AEAD mode (such as GCM/CCM), and the received authentication tag does not match the calculated value

doFinal

public byte[] doFinal(byte[] input)
               throws IllegalBlockSizeException,
                      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 the underlying cipher was initialized.

The bytes in the input buffer, and any input bytes that may have been buffered during a previous update operation, are processed, with padding (if requested) being applied. If an AEAD mode such as GCM/CCM is being used, the authentication tag is appended in the case of encryption, or verified in the case of decryption. The result is stored in a new buffer.

Note: if any exception is thrown, a new instance of this cipher lite object may need to be constructed before it can be used again.

Parameters:

input - the input buffer

Returns:

the new buffer with the result

Throws:

IllegalStateException - if this cipher is in a wrong state (e.g., has not been initialized)

IllegalBlockSizeException - if this cipher is a block cipher, 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; or if this encryption algorithm is unable to process the input data provided.

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; or if this cipher is decrypting in an AEAD mode (such as GCM/CCM), and the received authentication tag does not match the calculated value

doFinal

public byte[] doFinal(byte[] input,
                      int inputOffset,
                      int inputLen)
               throws IllegalBlockSizeException,
                      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 the underlying 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. If an AEAD mode such as GCM/CCM is being used, the authentication tag is appended in the case of encryption, or verified in the case of decryption. The result is stored in a new buffer.

Note: if any exception is thrown, a new instance of this cipher lite object may need to be constructed before it can be used again.

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:

IllegalStateException - if this cipher is in a wrong state (e.g., has not been initialized)

IllegalBlockSizeException - if this cipher is a block cipher, 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; or if this encryption algorithm is unable to process the input data provided.

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; or if this cipher is decrypting in an AEAD mode (such as GCM/CCM), and the received authentication tag does not match the calculated value

update

public byte[] update(byte[] input,
                     int inputOffset,
                     int inputLen)

Continues a multiple-part encryption or decryption operation (depending on how the underlying 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.

If inputLen is zero, this method returns null.

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:

IllegalStateException - if the underlying cipher is in a wrong state (e.g., has not been initialized)

getCipherAlgorithm

public final String getCipherAlgorithm()

Returns the algorithm name of the underlying cipher.

getCipherProvider

public final Provider getCipherProvider()

Returns the provider of the underlying cipher.

getSecretKeyAlgorithm

public final String getSecretKeyAlgorithm()

Returns the standard algorithm name for the secret key. For example, "DSA" would indicate that this key is a DSA key. See Appendix A in the Java Cryptography Architecture API Specification & Reference for information about standard algorithm names.

getCipher

public final Cipher getCipher()

This method is provided only for testing purposes. The CipherLite is intended to be used in lieu of the underlying Cipher.

getContentCryptoScheme

public final ContentCryptoScheme getContentCryptoScheme()

getIV

public final byte[] getIV()

Returns the initialization vector (IV) in a new buffer.

This is useful in the case where a random IV was created, or in the context of password-based encryption or decryption, where the IV is derived from a user-supplied password.

Returns:

the initialization vector in a new buffer, or null if the underlying algorithm does not use an IV, or if the IV has not yet been set.

getBlockSize

public final int getBlockSize()

Returns the block size (in bytes).

Returns:

the block size (in bytes), or 0 if the underlying algorithm is not a block cipher

markSupported

public boolean markSupported()

Tests if this cipher lite supports the mark and reset methods. Returns false by default, but subclass may override.

mark

public long mark()

Marks the current position in this cipher lite. A subsequent call to the reset method repositions this cipher lite at the last marked position so that subsequent crypto operations will be logically performed in an idempotent manner as if the cipher has been rewinded back to the marked position.

The general contract of mark is that, if the method markSupported returns true, the cipher lite somehow remembers the internal state after the call to mark and stands ready to restore to the internal state so that it would be able to produce the same output given the same input again if and whenever the method reset is called.

Returns:

the current position marked or -1 if mark/reset is not supported.

reset

public void reset()

Repositions this cipher lite to the position at the time the mark method was last called.

The general contract of reset is:

• If the method markSupported returns true, then the cipher lite is reset to the internal state since the most recent call to mark (or since the start of the input data, if mark has not been called), so that subsequent callers of the udpate or doFinal method would produce the same output given the same input data identical to the input data after the mark method was last called..
• If the method markSupported returns false, then the call to reset may throw an IllegalStateException.