Developer PKI
This page describes how to set up PKI support when developing SolarNode <-> SolarNet secure communication. This guide assumes you have your Eclipse development environment set up as well as the SolarNode and SolarNet environments.
For TLS to work you'll need to use a DNS name, which should be solarnetworkdev.net and added to your system's host file. For example on Unix systems, you can usually add a line to /etc/hosts like this:
127.0.0.1 localhost solarnetworkdev.net
When SolarNodes are registered and then associated with SolarNet, SolarNet is responsible for generating a X.509 certificate for the node, which must be signed by the SolarNet certification authority (CA) certificate. The net.solarnetwork.central.user.pki.dev bundle provides a simple SolarNet PKI service for use during development. Note that this bundle should be used instead of any other central.user.pki.* implementation bundles, so close all others except net.solarnetwork.central.user.pki.dev.
You should launch the SolarNetwork OSGi platform with this bundle deployed, and the first time this bundle is deployed it will create a new self-signed root CA certificate and store it in the /solarnetwork-osgi-target/var/DeveloperCA/ca.jks Java keystore. The password for this keystore is randomly generated and stored in a file named secret in the same directory.
The bundle will also create a new webserver certificate for the solarnetworkdev.net DNS name and store this in a keystore named central.jks. The password for this keystore is dev123. Finally, it will also create a trust keystore named central-trust.jks for use by SolarNode.
After all of these files have been created, you can stop the SolarNetwork OSGi platform in Eclipse and continue configuring your environment.
Copy the central.jks and central-trust.jks file to the /solarnetwork-osgi-target/conf/tls directory. If you move these files instead of copy them, the net.solarnetwork.central.user.pki.dev bundle will create new ones when it next starts up.
If you haven't already created the /solarnetwork-osgi-target/config/tomcat-server.xml file, copy the example file from /solarnetwork-osgi-target/example/config. Then add (or uncomment the example) TLS Connector element, which should look like this:
<Connector port="8683" protocol="HTTP/1.1" SSLEnabled="true"
maxThreads="25" scheme="https" secure="true" sslProtocol="TLS"
keyAlias="central" keystoreType="jks"
keystoreFile="conf/tls/central.jks" keystorePass="dev123"
truststoreFile="conf/tls/central.jks" truststorePass="dev123"
clientAuth="want"/>
Note the port setting, which you'll need to also configure the same value for later on. Also note the keystorePass and truststorePass values. We're using the same file as the key store and trust store, so the passwords will be the same value you used when you created the PKCS#12 file with OpenSSL.
Also in the tomcat-server.xml file, you must modify the Engine and Host elements to use the DNS name you created earlier and is the CN portion of your webserver certificate subject:
<Engine name="Catalina" defaultHost="solarnetworkdev.net">
<Host name="solarnetwork.dev" unpackWARs="false" autoDeploy="false" deployOnStartup="false">
</Engine>
Notice the Engine/@defaultHost attribute and the Host/@name attribute both use our DNS name now. Most likely they would have had localhost used before you change them.
You need to configure some development settings in the /solarnetwork-osgi-target/configurations/services directory.
| File | Description |
|---|---|
| net.solarnetwork.central.in.cfg |
Configure the host as the DNS name you assigned earlier, and the same port that you configured the Tomcat server to use. For example: |
Next you need to update the OSGi runtime in Eclipse so the node uses the central-trust.jks file as its trust store, enabling it to "trust" the development CA root certificate. Go to Run > Run Configurations... > OSGi Framework > SolarNetwork and select the Arguments tab. Add the following to the VM arguments field:
-Djavax.net.ssl.trustStore=${workspace_loc:solarnetwork-osgi-target}/conf/tls/central-trust.jks
Start up the SolarNetwork OSGi platform in Eclipse, and then use the SolarUser app (/solaruser) to register yourself as a new SolarNet user (if you haven't already). You can use the net.solarnetwork.central.common.mail.mock bundle to have the user registration code logged to the console rather than relying on an actual email to be sent. Once registered, invite a new SolarNode (under the My Nodes section). Copy the invitation code, then go to the SolarNode setup app (/setup). Paste in the invitation and complete the association process. Your new node should setup and get a new certificate and then be ready for general use.
Now click on the Certificates section on the SolarNode app and you should end up with a screen similar to the following:
To test if everything is working as expected, enable some mock data to be collected on the node and then have it uploaded to SolarIn to see that everything works smoothly. For example, deploy these node projects in Eclipse to collect and post some fake PowerDatum data:
net.solarnetwork.node.powernet.solarnetwork.node.power.mocknet.solarnetwork.node.upload.bulkjsonwebpost
Watch the console for messages like
INFO Got Datum to persist: PowerDatum{pvAmps=5.0,pvVolts=18.0,batVolts=12.0,ampHoursToday=12.0,kwHoursToday=0.144}
followed later on by
INFO Bulk uploaded 1 objects to [BulkJsonWebPostUploadService:solarnetworkdev.net]
If you see messages like that, you're good to go!