KeyStoreActor
ptolemy.actor.lib.security.KeyStoreActor

A baseclass for actors that read or write keystores. <p>Keystores are ways to manage keys and certificates. A keystore file can be created by using the <code>keytool</code> executable that comes with Java, or, if the <i>createFileOrURLIfNecessary</i> 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: <pre> cd $PTII make ptKeystore </pre> which will create a keystore with a store password of <code>this.is.the.storePassword,change.it</code> and key password of of <code>this.is.the.keyPassword,change.it</code>. <br>The alias of the certificate will be <code>claudius</code> <p>A keystore may have at most one type, which describes the format of the keystore. If a keyStore file exists, then the <i>keyStoreType</i> parameter is set to the type of the preexisting keyStore. Changing the <i>keyStoreType</i> 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 <i>keyStoreType</i> parameter. <p>The <code>keytool</code> creates keystores that have a type of "JKS". To view the keystore type, run <code>keytool -keystore <i>keystoreFile</i>-list</code>. <p>The <a href="../../../../ptolemy/actor/lib/security/SecretKey.xml">ptolemy.actor.lib.security.SecretKey</a> 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". <p>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. <h3>How to exchange data securely with a remote part</h3> <a href="http://java.sun.com/docs/books/tutorial/security1.2/toolfilex/index.html" target="_top">http://java.sun.com/docs/books/tutorial/security1.2/toolfilex/index.html</a> discusses how to exchange files using signatures, keytool and jarsigner. In Ptolemy II, we use actors derived from the KeyStoreActor. <h4>Steps for the Sender</h4> <ol> <li>Generate keys using keytool, which is included in the JDK <pre> keytool -genkey -alias claudius -keystore $PTII/ptKeystore -keypass myKeyPassword -storepass myStorePassword </pre> You will be prompted for information about yourself. <li>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. <li> Export the certificate <pre> keytool -alias claudius -export -keystore $PTII/ptKeystore -keypass myKeyPassword -storepass myStorePassword -file claudius.cer -rfc </pre> <li> Send the output file (claudius.cer) to the recipient <li>Create a Ptolemy model that uses the <a href="../../../../ptolemy/actor/lib/security/PrivateKeyReader.xml">ptolemy.actor.lib.security.PrivateKeyReader</a> 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. </ol> <h4>Steps for the Receiver</h4> <ol> <li>Receive the public key from the sender and import it into your keystore <pre> 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% </pre> <li>Verify the signature by calling up the sender and comparing the fingerprints on the phone. The send can view the fingerprints with <pre> 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% </pre> If the Certificate fingerprints match, then the file has not been modified in transit. <li> The receiver should then create a model that uses the <a href="../../../../ptolemy/actor/lib/security/PublicKeyReader.xml">ptolemy.actor.lib.security.PublicKeyReader</a> actor with the appropriate passwords. See the right side of $PTII/ptolemy/actor/lib/security/test/auto/Signature.xml for an example model. </ol> <p>For more information about keystores, see <a href="http://java.sun.com/docs/books/tutorial/security1.2/summary/tools.html" target="_top">Security Tools Summary</a> and <br><a href="http://java.sun.com/j2se/1.4.2/docs/tooldocs/windows/keytool.html" target="_top">Keytool</a>.

Author(s): Christopher Hylands Brooks
Version:$Id: KeyStoreActor.doc.html,v 1.1 2006/02/22 18:41:22 mangal Exp $
Pt.Proposed Rating:Yellow (cxh)
Pt.Accepted Rating:Red (cxh)




alias
The alias of the certificate that we are looking for. The default alias is the String "claudius"
createFileOrURLIfNecessary
If true, then create the keystore named by <i>fileOrURL</i> if the <i>fileOrURL</i> does not exist. The default value is true.
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 <i>createFileOrURLIfNecessary</i> to true.
keyStoreType
The type of the keystore. See <a href="http://java.sun.com/j2se/1.4.2/docs/guide/security/CryptoSpec.html#AppA" target="_top"> Java Cryptography Architecture API Specification &amp; Reference</a> for information about keystore types. The initial value is the string returned by java.security.KeyStore.getDefaultType(). <p>Note that secret keys generated by the <a href="../../../../ptolemy/actor/lib/security/SecretKey.xml">ptolemy.actor.lib.security.SecretKey</a> actor should be saved in a keystore of type "JCEKS".
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
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
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.