ptolemy.actor.lib.security
Class CipherActor

java.lang.Object
  ptolemy.kernel.util.NamedObj
      ptolemy.kernel.InstantiableNamedObj
          ptolemy.kernel.Entity
              ptolemy.kernel.ComponentEntity
                  ptolemy.actor.AtomicActor
                      ptolemy.actor.TypedAtomicActor
                          ptolemy.actor.lib.security.CryptographyActor
                              ptolemy.actor.lib.security.CipherActor

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, Actor, Executable, FiringsRecordable, Initializable, TypedActor, Changeable, Debuggable, DebugListener, Derivable, Instantiable, ModelErrorHandler, MoMLExportable, Moveable, Nameable

Direct Known Subclasses:

SymmetricDecryption, SymmetricEncryption

public abstract class CipherActor
extends CryptographyActor

A base class for actors that encrypt and decrypt data.

Cipher actors are any actors which perform encryption or decryption based on the Java Cryptography Extension (JCE). See the CryptographyActor documentation for resources about JCA and JCE.

Actors extending this class take in an unsigned byte array at the input, process the data based on the algorithm parameter and send a unsigned byte array to the output. The algorithms that may be implemented are limited to those that are implemented by "providers" following the JCE specifications and installed in the machine being run. The mode and padding of the algorithm can also be specified in the mode and padding parameters. In case a provider specific instance of an algorithm is needed, the provider may also be specified in the provider parameter. The keySize parameter allows implementations of algorithms using various key sizes.

Concrete actors derived from this base class must implement the CryptographyActor._process(byte[]) method. The initialize() method of this actor sets _cipher to the value of javax.crypt.Cipher.getInstance() with an argument that is created from the values of the algorithm, padding and keySize parameters. Derived classes should call _cipher.init() with the value of the key in their fire() method. The_process() method in a derived class usually calls _cipher.doFinal().

Since:

Ptolemy II 4.0

Version:

$Id: CipherActor.java 57040 2010-01-27 20:52:32Z cxh $

Author:

Christopher Hylands Brooks, Contributor: Rakesh Reddy

See Also:

Serialized Form

Accepted Rating:

Yellow (cxh)

Proposed Rating:

Green (cxh)

Nested Class Summary

Nested classes/interfaces inherited from class ptolemy.kernel.Entity

Entity.ContainedObjectsIterator

Field Summary

protected javax.crypto.Cipher	_cipher The cipher that will be used to process the data.
protected java.lang.String	_mode The mode to be used to process the data.
protected java.lang.String	_padding The padding scheme to be used process the data.
protected boolean	_updateCipherNeeded Set to true if one of the parameters changed and we need to call _updateCipher().
StringParameter	mode The mode component when the Cipher is instantiated.
StringParameter	padding The padding scheme used by the cipher during encryption.

Fields inherited from class ptolemy.actor.lib.security.CryptographyActor

_algorithm, _keySize, _provider, algorithm, input, keySize, output, provider

Fields inherited from class ptolemy.actor.AtomicActor

_actorFiringListeners, _initializables, _notifyingActorFiring, _stopRequested

Fields inherited from class ptolemy.kernel.util.NamedObj

_changeListeners, _changeLock, _changeRequests, _debugging, _debugListeners, _elementName, _isPersistent, _verbose, _workspace, ATTRIBUTES, CLASSNAME, COMPLETE, CONTENTS, DEEP, FULLNAME, LINKS

Fields inherited from interface ptolemy.actor.Executable

COMPLETED, NOT_READY, STOP_ITERATING

Constructor Summary

CipherActor(CompositeEntity container, java.lang.String name)
Construct an actor with the given container and name.

Method Summary

protected void	_updateCipher() The value of _cipher is updated by calling javax.crypt.Cipher.getInstance() with an argument that is created from the values of the _algorithm, _mode and _padding.
void	attributeChanged(Attribute attribute) Override the base class to reinitialize the state if the the mode, or paddingparameter is changed.
void	fire() Update _cipher if an attribute has changed and then invoke super.fire() to transform the input data.
void	initialize() Retrieve the values of the parameters and set up javax.crypto.Cipher.

Methods inherited from class ptolemy.actor.lib.security.CryptographyActor

_process

Methods inherited from class ptolemy.actor.TypedAtomicActor

_addPort, _fireAt, _fireAt, attributeTypeChanged, clone, newPort, typeConstraintList, typeConstraints

Methods inherited from class ptolemy.actor.AtomicActor

_actorFiring, _actorFiring, addActorFiringListener, addInitializable, clone, connectionsChanged, createReceivers, declareDelayDependency, getCausalityInterface, getDirector, getExecutiveDirector, getManager, inputPortList, isFireFunctional, isStrict, iterate, newReceiver, outputPortList, postfire, prefire, preinitialize, pruneDependencies, recordFiring, removeActorFiringListener, removeDependency, removeInitializable, setContainer, stop, stopFire, terminate, wrapup

Methods inherited from class ptolemy.kernel.ComponentEntity

_adjustDeferrals, _checkContainer, _getContainedObject, _propagateExistence, getContainer, instantiate, isAtomic, isOpaque, moveDown, moveToFirst, moveToIndex, moveToLast, moveUp, propagateExistence, setName

Methods inherited from class ptolemy.kernel.Entity

_description, _exportMoMLContents, _removePort, _validateSettables, connectedPortList, connectedPorts, containedObjectsIterator, getAttribute, getPort, getPorts, linkedRelationList, linkedRelations, portList, removeAllPorts, setClassDefinition, uniqueName

Methods inherited from class ptolemy.kernel.InstantiableNamedObj

_setParent, exportMoML, getChildren, getElementName, getParent, getPrototypeList, isClassDefinition, isWithinClassDefinition

Methods inherited from class ptolemy.kernel.util.NamedObj

_addAttribute, _adjustOverride, _attachText, _cloneFixAttributeFields, _debug, _debug, _debug, _debug, _debug, _getIndentPrefix, _isMoMLSuppressed, _markContentsDerived, _propagateValue, _recordDecoratedAttributes, _removeAttribute, _splitName, _stripNumericSuffix, addChangeListener, addDebugListener, attributeList, attributeList, deepContains, depthInHierarchy, description, description, event, executeChangeRequests, exportMoML, exportMoML, exportMoML, exportMoML, exportMoMLPlain, getAttribute, getAttributes, getChangeListeners, getClassName, getDecoratorAttribute, getDecoratorAttributes, getDerivedLevel, getDerivedList, getDisplayName, getFullName, getModelErrorHandler, getName, getName, getSource, handleModelError, isDeferringChangeRequests, isOverridden, isPersistent, lazyContainedObjectsIterator, message, propagateValue, propagateValues, removeChangeListener, removeDebugListener, requestChange, setClassName, setDeferringChangeRequests, setDerivedLevel, setDisplayName, setModelErrorHandler, setPersistent, setSource, sortContainedObjects, toplevel, toString, validateSettables, workspace

Methods inherited from class java.lang.Object

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

Methods inherited from interface ptolemy.actor.Actor

createReceivers, getCausalityInterface, getDirector, getExecutiveDirector, getManager, inputPortList, newReceiver, outputPortList

Methods inherited from interface ptolemy.actor.Executable

isFireFunctional, isStrict, iterate, postfire, prefire, stop, stopFire, terminate

Methods inherited from interface ptolemy.actor.Initializable

addInitializable, preinitialize, removeInitializable, wrapup

Methods inherited from interface ptolemy.kernel.util.Nameable

description, getContainer, getDisplayName, getFullName, getName, getName, setName

Methods inherited from interface ptolemy.kernel.util.Derivable

getDerivedLevel, getDerivedList, propagateValue

Field Detail

mode

public StringParameter mode

The mode component when the Cipher is instantiated. Algorithms can be run in several different modes. The mode is specified as a string. Names for modes and modes implemented vary based on the provider. Possible values include

(The empty string)

Use the default setting for the algorithm.

NONE

No mode, meaning that the algorithm does not use a mode.

CBC

Cipher Block Chaining Mode, as defined in FIPS PUB 81. CBC is usually the mode that is used.

CFB

Cipher Feedback Mode, as defined in FIPS PUB 81.

ECB

Electronic Codebook Mode, as defined in: The National Institute of Standards and Technology (NIST) Federal Information Processing Standard (FIPS) PUB 81, "DES Modes of Operation," U.S. Department of Commerce, Dec 1980. ECM is best for encrypting small pieces of data. If possible, use CBC instead.

OFB

Output Feedback Mode, as defined in FIPS PUB 81.

PCBC

Propagating Cipher Block Chaining, as defined by Kerberos V4.

The initial default is the empty string, which indicates that the default setting for the algorithm should be used.

See the Java Cryptography Extension (JCE) Reference Guide for details.

padding

public StringParameter padding

The padding scheme used by the cipher during encryption. In cryptography, padding is used to handle situations where the input data must be an exact multiple of the block size for the algorithm http://www.di-mgt.com.au/cryptopad.html#whennopadding says:

Block cipher algorithms like DES and Blowfish in Electronic Code Book (ECB) and Cipher Block Chaining (CBC) mode require their input to be an exact multiple of the block size. If the plaintext to be encrypted is not an exact multiple, you need to pad before encrypting by adding a padding string. When decrypting, the receiving party needs to know how to remove the padding, if any.

The padding is specified as a string. Names for parameter and parameters implemented vary based on the provider. Possible values include

(The empty string)

Use the default setting for the algorithm.

NoPadding

No padding (do not use padding).

OAEPWithdigestAndmgfPadding

Optimal Asymmetric Encryption Padding scheme defined in PKCS #1, where digest should be replaced by the message digest and mgf by the mask generation function. Example: OAEPWithMD5AndMGF1Padding.

PKCS5Padding

The padding scheme described in: RSA Laboratories, "PKCS #5: Password-Based Encryption Standard," version 1.5, November 1993.

SSL3Padding

The padding scheme defined in the SSL Protocol Version 3.0, November 18, 1996, section 5.2.3.2 (CBC block cipher):

The initial default is the empty string, which indicates that the default setting for the algorithm should be used.

See the Java Cryptography Extension (JCE) Reference Guide for details.

_cipher

protected javax.crypto.Cipher _cipher

The cipher that will be used to process the data.

_mode

protected java.lang.String _mode

The mode to be used to process the data.

_padding

protected java.lang.String _padding

The padding scheme to be used process the data.

_updateCipherNeeded

protected boolean _updateCipherNeeded

Set to true if one of the parameters changed and we need to call _updateCipher().

Constructor Detail

CipherActor

public CipherActor(CompositeEntity container,
                   java.lang.String name)
            throws NameDuplicationException,
                   IllegalActionException

Construct an actor with the given container and name.

Parameters:

container - The container.

name - The name of this actor.

Throws:

IllegalActionException - If the actor cannot be contained by the proposed container.

NameDuplicationException - If the container already has an actor with this name.

Method Detail

attributeChanged

public void attributeChanged(Attribute attribute)
                      throws IllegalActionException

Override the base class to reinitialize the state if the the mode, or paddingparameter is changed.

Overrides:

attributeChanged in class CryptographyActor

Parameters:

attribute - The attribute that changed.

Throws:

IllegalActionException - Not thrown in this base class.

fire

public void fire()
          throws IllegalActionException

Update _cipher if an attribute has changed and then invoke super.fire() to transform the input data.

Specified by:

fire in interface Executable

Overrides:

fire in class CryptographyActor

Throws:

IllegalActionException - If thrown by the base class or if there is a problem processing the data.

initialize

public void initialize()
                throws IllegalActionException

Retrieve the values of the parameters and set up javax.crypto.Cipher.

Specified by:

initialize in interface Initializable

Overrides:

initialize in class AtomicActor

Throws:

IllegalActionException - If the algorithm cannot be found, the padding scheme is illegal for the the given algorithm or if the specified provider does not exist.

_updateCipher

protected void _updateCipher()
                      throws IllegalActionException

The value of _cipher is updated by calling javax.crypt.Cipher.getInstance() with an argument that is created from the values of the _algorithm, _mode and _padding.

Throws:

IllegalActionException - if the _cipher cannot be initialized.