ptolemy.actor.lib.security
Class KeyStoreActor

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.KeyStoreActor

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:

KeyReader, KeyWriter

public class KeyStoreActor
extends TypedAtomicActor

A baseclass for actors that read or write keystores.

Keystores are ways to manage keys and certificates. A keystore file can be created by using the keytool executable that comes with Java, or, if the createFileOrURLIfNecessary parameter is true, then a keystore will be created for you. To create a simple keystore by hand that contains a private key and a public key signed with a self signed certificate, run:

 cd $PTII
 make ptKeystore
 

which will create a keystore with a store password of this.is.the.storePassword,change.it and key password of of this.is.the.keyPassword,change.it.
The alias of the certificate will be claudius

A keystore may have at most one type, which describes the format of the keystore. If a keyStore file exists, then the keyStoreType parameter is set to the type of the preexisting keyStore. Changing the keyStoreType of a preexisting keystore to a different type is likely to throw an exception when the keyStore is opened. If a keyStore file does not exist, then when it is created it will be created with the type from the keyStoreType parameter.

The keytool creates keystores that have a type of "JKS". To view the keystore type, run keytool -keystore keystoreFile-list.

The SecretKey actor outputs a key that must read in with a keystore type of "JCEKS", so if this actor is being used with a SecretKey actor, then the type should be set to "JCEKS".

Derived classes should add input or output ports as necessary. Derived classes should call _loadKeyStore() so that _keyStore is properly initialized before accessing _keyStore themselves.

How to exchange data securely with a remote part

http://java.sun.com/docs/books/tutorial/security1.2/toolfilex/index.html discusses how to exchange files using signatures, keytool and jarsigner. In Ptolemy II, we use actors derived from the KeyStoreActor.

Steps for the Sender

1. Generate keys using keytool, which is included in the JDK

    keytool -genkey -alias claudius -keystore $PTII/ptKeystore -keypass myKeyPassword -storepass myStorePassword
    

   You will be prompted for information about yourself.
2. Optional: Generate a Certificate Signing Request (CSR), send it to your vendor and import the response. Since we are using a self signed certificate, this step is option.
3. Export the certificate

    keytool -alias claudius -export -keystore $PTII/ptKeystore -keypass myKeyPassword -storepass myStorePassword -file claudius.cer -rfc
    

4. Send the output file (claudius.cer) to the recipient
5. Create a Ptolemy model that uses the PrivateKeyReader actor to read $PTII/ptKeystore with the appropriate passwords and sign your data. See the left side of $PTII/ptolemy/actor/lib/security/test/auto/Signature.xml for an example model.

Steps for the Receiver

1. Receive the public key from the sender and import it into your keystore

    cxh@cooley 91% keytool -import -alias claudius -keystore $PTII/receivedKeystore -file claudius.cer
    Enter keystore password:  foobar
    Owner: CN=Claudius Ptolemaus, OU=Your Project, O=Your University, L=Your Town, ST=Your State, C=US
    Issuer: CN=Claudius Ptolemaus, OU=Your Project, O=Your University, L=Your Town, ST=Your State, C=US
    Serial number: 3fa9b2c5
    Valid from: Wed Nov 05 18:32:37 PST 2003 until: Tue Feb 03 18:32:37 PST 2004
    Certificate fingerprints:
    MD5:  D7:43:A0:C0:39:49:A8:80:69:EA:11:91:17:CE:E5:E3
    SHA1: C1:3B:9A:92:35:4F:7F:A5:23:AB:57:28:D6:67:ED:43:AB:EA:A9:2B
    Trust this certificate? [no]:  yes
    Certificate was added to keystore
    cxh@cooley 92%
    

2. Verify the signature by calling up the sender and comparing the fingerprints on the phone. The send can view the fingerprints with

    cxh@cooley 93% keytool -printcert -file claudius.cer
    Owner: CN=Claudius Ptolemaus, OU=Your Project, O=Your University, L=Your Town, ST=Your State, C=US
    Issuer: CN=Claudius Ptolemaus, OU=Your Project, O=Your University, L=Your Town, ST=Your State, C=US
    Serial number: 3fa9b2c5
    Valid from: Wed Nov 05 18:32:37 PST 2003 until: Tue Feb 03 18:32:37 PST 2004
    Certificate fingerprints:
    MD5:  D7:43:A0:C0:39:49:A8:80:69:EA:11:91:17:CE:E5:E3
    SHA1: C1:3B:9A:92:35:4F:7F:A5:23:AB:57:28:D6:67:ED:43:AB:EA:A9:2B
    cxh@cooley 94%
    

   If the Certificate fingerprints match, then the file has not been modified in transit.
3. The receiver should then create a model that uses the PublicKeyReader actor with the appropriate passwords. See the right side of $PTII/ptolemy/actor/lib/security/test/auto/Signature.xml for an example model.

For more information about keystores, see Security Tools Summary and
Keytool.

Since:

Ptolemy II 4.0

Version:

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

Author:

Christopher Hylands Brooks

See Also:

Serialized Form

Accepted Rating:

Red (cxh)

Proposed Rating:

Yellow (cxh)

Nested Class Summary

private class

KeyStoreActor._StreamReaderThread

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

Entity.ContainedObjectsIterator

Field Summary

protected java.lang.String	_alias The alias of the Certificate that we are looking for.
private KeyStoreActor._StreamReaderThread	_errorGobbler
private boolean	_initializeKeyStoreNeeded
protected java.lang.String	_keyPassword The password for the key.
protected java.security.KeyStore	_keyStore The KeyStore itself.
private static int	_keystoreStreamReaderThreadCount
protected java.lang.String	_keyStoreType The keyStore type.
protected boolean	_loadKeyStoreNeeded Set to true if fileOrURL has changed and the keyStore needs to be read in again and the aliases updated.
private KeyStoreActor._StreamReaderThread	_outputGobbler
private java.lang.Process	_process
protected java.lang.String	_provider The provider to be used for a provider specific implementation.
private boolean	_stopFireRequested
protected java.lang.String	_storePassword The password for the keyStore.
StringParameter	alias The alias of the certificate that we are looking for.
Parameter	createFileOrURLIfNecessary If true, then create the keystore named by fileOrURL if the fileOrURL does not exist.
FileParameter	fileOrURL The file name or URL from which to read.
PortParameter	keyPassword The password to the Key.
StringParameter	keyStoreType The type of the keystore.
StringParameter	provider Specify a provider for the given algorithm.
PortParameter	storePassword The password to the KeyStore.

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

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

Method Summary

private void	_exec(java.lang.String command)
protected void	_initializeKeyStore() If necessary, initialize the _keyStore by calling KeyStore.getInstance().
protected void	_loadKeyStore() If necessary, load the _keyStore and update the choice of aliases.
private void	_terminateProcess()
void	attributeChanged(Attribute attribute) If the specified attribute is URL, then close the current file (if there is one) and open the new one.
void	createKeystore(java.lang.String keystoreFilename) Create the keystore file.
protected java.lang.String	fileOrURLDescription() Return descriptive information about fileOrURL.
void	fire() Load the keystore for use by derived classes.
void	stopFire() Override the base class to stop waiting for input data.
void	wrapup() Terminate the subprocess.

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, initialize, inputPortList, isFireFunctional, isStrict, iterate, newReceiver, outputPortList, postfire, prefire, preinitialize, pruneDependencies, recordFiring, removeActorFiringListener, removeDependency, removeInitializable, setContainer, stop, terminate

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, terminate

Methods inherited from interface ptolemy.actor.Initializable

addInitializable, initialize, preinitialize, removeInitializable

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

alias

public StringParameter alias

The alias of the certificate that we are looking for. The default alias is the String "ptolemy"

createFileOrURLIfNecessary

public Parameter createFileOrURLIfNecessary

If true, then create the keystore named by fileOrURL if the fileOrURL does not exist. The default value is true.

fileOrURL

public FileParameter fileOrURL

The file name or URL from which to read. This is a string with any form accepted by FileParameter. The initial default is "$PTII/ptKeystore". To create the initial default keystore, run "cd $PTII; make ptKeystore" or set the createFileOrURLIfNecessary to true.

See Also:

FileParameter

keyStoreType

public StringParameter keyStoreType

The type of the keystore. See Java Cryptography Architecture API Specification & Reference for information about keystore types. The initial value is the string returned by java.security.KeyStore.getDefaultType().

Note that secret keys generated by the SecretKey actor should be saved in a keystore of type "JCEKS".

keyPassword

public PortParameter keyPassword

The password to the Key. The default password is "this.is.the.keyPassword,change.it". If the port is left unconnected, then the parameter value will be used.

provider

public StringParameter provider

Specify a provider for the given algorithm. The default value is "SystemDefault" which allows the system to choose the provider based on the JCE architecture.

storePassword

public PortParameter storePassword

The password to the KeyStore. The default password is "this.is.the.storePassword,change.it". If the port is left unconnected, then the parameter value will be used.

_alias

protected java.lang.String _alias

The alias of the Certificate that we are looking for.

_keyPassword

protected java.lang.String _keyPassword

The password for the key.

_keyStore

protected java.security.KeyStore _keyStore

The KeyStore itself.

_keyStoreType

protected java.lang.String _keyStoreType

The keyStore type.

_provider

protected java.lang.String _provider

The provider to be used for a provider specific implementation.

_storePassword

protected java.lang.String _storePassword

The password for the keyStore.

_loadKeyStoreNeeded

protected boolean _loadKeyStoreNeeded

Set to true if fileOrURL has changed and the keyStore needs to be read in again and the aliases updated.

_errorGobbler

private KeyStoreActor._StreamReaderThread _errorGobbler

_keystoreStreamReaderThreadCount

private static int _keystoreStreamReaderThreadCount

_initializeKeyStoreNeeded

private boolean _initializeKeyStoreNeeded

_outputGobbler

private KeyStoreActor._StreamReaderThread _outputGobbler

_process

private java.lang.Process _process

_stopFireRequested

private boolean _stopFireRequested

Constructor Detail

KeyStoreActor

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

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

If the specified attribute is URL, then close the current file (if there is one) and open the new one.

Overrides:

attributeChanged in class NamedObj

Parameters:

attribute - The attribute that has changed.

Throws:

IllegalActionException - If the specified attribute is URL and the file cannot be opened.

createKeystore

public void createKeystore(java.lang.String keystoreFilename)
                    throws IllegalActionException

Create the keystore file.

Parameters:

keystoreFilename - The name of the keystore file.

Throws:

IllegalActionException - If there is a problem creating the keystore.

fire

public void fire()
          throws IllegalActionException

Load the keystore for use by derived classes.

Specified by:

fire in interface Executable

Overrides:

fire in class AtomicActor

Throws:

IllegalActionException - Not thrown in this base class.

stopFire

public void stopFire()

Override the base class to stop waiting for input data.

Specified by:

stopFire in interface Executable

Overrides:

stopFire in class AtomicActor

wrapup

public void wrapup()
            throws IllegalActionException

Terminate the subprocess. This method is invoked exactly once per execution of an application. None of the other action methods should be be invoked after it.

Specified by:

wrapup in interface Initializable

Overrides:

wrapup in class AtomicActor

Throws:

IllegalActionException - Not thrown in this base class.

_initializeKeyStore

protected void _initializeKeyStore()
                            throws IllegalActionException

If necessary, initialize the _keyStore by calling KeyStore.getInstance().

Throws:

IllegalActionException - If KeyStore.getInstance() throws an exception.

_loadKeyStore

protected void _loadKeyStore()
                      throws IllegalActionException

If necessary, load the _keyStore and update the choice of aliases.

Throws:

IllegalActionException - If there is a problem creating a new keystore or loading a preexisting keystore.

fileOrURLDescription

protected java.lang.String fileOrURLDescription()

Return descriptive information about fileOrURL.

Returns:

The description.

_exec

private void _exec(java.lang.String command)
            throws IllegalActionException

Throws:

IllegalActionException

_terminateProcess

private void _terminateProcess()