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