Package ptolemy.actor.lib.security

Class KeyStoreActor

  • All Implemented Interfaces:
    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".

    See http://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html for possible values.

    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://download.oracle.com/javase/tutorial/security/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.

    Since:
    Ptolemy II 4.0
    Version:
    $Id$
    Author:
    Christopher Hylands Brooks
    Pt.AcceptedRating:
    Red (cxh)
    Pt.ProposedRating:
    Yellow (cxh)

    • 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

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