--- /dev/null
+---
+title: "MCollective » Deploy » Middleware » ActiveMQ Keystores"
+subtitle: "Setting Up Keystores For ActiveMQ"
+layout: default
+---
+
+[tls]: ./activemq.html#tls-credentials
+
+Since ActiveMQ runs on the JVM, [configuring it to use TLS encryption/authentication][tls] requires a pair of Java keystores; it can't just use the normal PEM format certificates and keys used by Puppet and MCollective.
+
+Java keystores require some non-obvious steps to set up, so this guide provides full instructions, including both a [manual method](#manually-creating-keystores) and a [Puppet method](#creating-keystores-with-puppet).
+
+
+## Step 0: Obtain Certificates and Keys
+
+ActiveMQ needs the following credentials:
+
+* A copy of the site's CA certificate
+* A certificate signed by the site's CA
+* A private key to match its certificate
+
+These can come from anywhere, but the CA has to match the one used by MCollective.
+
+The easiest approach is to re-use your site's Puppet cert infrastructure, since it's already everywhere and has tools for issuing and signing arbitrary certificates.
+
+As ever, remember to **protect the private key.**
+
+### Option A: Re-Use the Node's Puppet Agent Certificate
+
+On your ActiveMQ server:
+
+* Locate the ssldir by running `sudo puppet agent --configprint ssldir`.
+* Copy the following files to your working directory, making sure to give unique names to the cert and private key:
+ * `<ssldir>/certs/ca.pem`
+ * `<ssldir>/certs/<node name>.pem`
+ * `<ssldir>/private_keys/<node name>.pem`
+
+### Option B: Get a New Certificate from the Puppet CA
+
+On your CA puppet master:
+
+* Run `sudo puppet cert generate activemq.example.com`, substituting some name for your ActiveMQ server. Unlike with a puppet master, the cert's common name can be anything; it doesn't have to be the node's hostname or FQDN.
+* Locate the ssldir by running `sudo puppet master --configprint ssldir`.
+* Retrieve the following files and copy them to a working directory on your ActiveMQ server, making sure to give unique names to the cert and private key:
+ * `<ssldir>/certs/ca.pem`
+ * `<ssldir>/certs/activemq.example.com.pem`
+ * `<ssldir>/private_keys/activemq.example.com.pem`
+
+### Option C: Do Whatever You Want
+
+If you have some other CA infrastructure, you can use that instead.
+
+You can now:
+
+* [Manually create the keystores](#manually-creating-keystores)
+* [Use Puppet to create the keystores](#creating-keystores-with-puppet)
+
+## Manually Creating Keystores
+
+We need a **"truststore"** and a **"keystore."** We also need a **password** for each. (You can use the same password for both stores.)
+
+Remember the password(s) for later, because it needs to [go in the activemq.xml file][tls].
+
+### Step 1: Truststore
+
+> **Note:** The truststore is only required for CA-verified TLS. If you are using anonymous TLS, you may skip it.
+
+The truststore determines which certificates are allowed to connect to ActiveMQ. If you import a CA cert into it, ActiveMQ will trust any certificate signed by that CA.
+
+> You could also _not_ import a CA, and instead import every individual certificate you want to allow. If you do that, you're on your own, but the commands should be similar.
+
+In the working directory with your PEM-format credentials, run the following command. Replace `ca.pem` with whatever you named your copy of the CA cert, and use the password when requested.
+
+{% highlight console %}
+$ sudo keytool -import -alias "My CA" -file ca.pem -keystore truststore.jks
+Enter keystore password:
+Re-enter new password:
+.
+.
+.
+Trust this certificate? [no]: y
+Certificate was added to keystore
+{% endhighlight %}
+
+The truststore is now done.
+
+If you want, you can compare fingerprints:
+
+{% highlight console %}
+$ sudo keytool -list -keystore truststore.jks
+Enter keystore password:
+
+Keystore type: JKS
+Keystore provider: SUN
+
+Your keystore contains 1 entry
+
+my ca, Mar 30, 2012, trustedCertEntry,
+Certificate fingerprint (MD5): 99:D3:28:6B:37:13:7A:A2:B8:73:75:4A:31:78:0B:68
+
+$ sudo openssl x509 -in ca.pem -fingerprint -md5
+MD5 Fingerprint=99:D3:28:6B:37:13:7A:A2:B8:73:75:4A:31:78:0B:68
+{% endhighlight %}
+
+
+### Step 2: Keystore
+
+The keystore contains the ActiveMQ broker's certificate and private key, which it uses to identify itself to the applications that connect to it.
+
+In the working directory with your PEM-format credentials, run the following commands. Substitute the names of your key and certificate files where necessary, and the common name of your ActiveMQ server's certificate for `activemq.example.com`.
+
+These commands use both an "export/source" password and a "destination" password. The export/source password is never used again after this series of commands.
+
+{% highlight console %}
+$ sudo cat activemq_private.pem activemq_cert.pem > temp.pem
+$ sudo openssl pkcs12 -export -in temp.pem -out activemq.p12 -name activemq.example.com
+Enter Export Password:
+Verifying - Enter Export Password:
+$sudo keytool -importkeystore -destkeystore keystore.jks -srckeystore activemq.p12 -srcstoretype PKCS12 -alias activemq.example.com
+Enter destination keystore password:
+Re-enter new password:
+Enter source keystore password:
+{% endhighlight %}
+
+The keystore is now done.
+
+If you want, you can compare fingerprints:
+
+{% highlight console %}
+$ sudo keytool -list -keystore keystore.jks
+Enter keystore password:
+
+Keystore type: JKS
+Keystore provider: SUN
+
+Your keystore contains 1 entry
+
+activemq.example.com, Mar 30, 2012, PrivateKeyEntry,
+Certificate fingerprint (MD5): 7E:2A:B4:4D:1E:6D:D1:70:A9:E7:20:0D:9D:41:F3:B9
+
+$ sudo openssl x509 -in activemq_cert.pem -fingerprint -md5
+MD5 Fingerprint=7E:2A:B4:4D:1E:6D:D1:70:A9:E7:20:0D:9D:41:F3:B9
+{% endhighlight %}
+
+### Step 3: Finish
+
+Move the keystore and truststore to ActiveMQ's config directory. Make sure they are owned by the ActiveMQ user and unreadable to any other users. [Configure ActiveMQ to use them in its `sslContext`.][tls] **Double-check** that you've made activemq.xml world-unreadable, since it now contains sensitive credentials.
+
+## Creating Keystores with Puppet
+
+If you're managing your ActiveMQ server with Puppet anyway, you can use the [puppetlabs/java_ks module](http://forge.puppetlabs.com/puppetlabs/java_ks) to handle the format conversion.
+
+This approach is more work for a single permanent ActiveMQ server, but less work if you intend to deploy multiple ActiveMQ servers or eventually change the credentials.
+
+### Step 1: Install the `java_ks` Module
+
+On your puppet master, run `sudo puppet module install puppetlabs/java_ks`.
+
+### Step 2: Create a Puppet Class
+
+The class to manage the keystores should do the following:
+
+* Make sure the PEM cert and key files are present and protected.
+* Declare a pair of `java_ks` resources.
+* Manage the mode and ownership of the keystore files.
+
+The code below is an example, but it will work fine if you put it in a module (example file location in the first comment) and set its parameters when you declare it. The name of the class (and its home module) can be changed as needed.
+
+
+{% highlight ruby %}
+ # /etc/puppet/modules/activemq/manifests/keystores.pp
+ class activemq::keystores (
+ $keystore_password, # required
+
+ # User must put these files in the module, or provide other URLs
+ $ca = 'puppet:///modules/activemq/ca.pem',
+ $cert = 'puppet:///modules/activemq/cert.pem',
+ $private_key = 'puppet:///modules/activemq/private_key.pem',
+
+ $activemq_confdir = '/etc/activemq',
+ $activemq_user = 'activemq',
+ ) {
+
+ # ----- Restart ActiveMQ if the SSL credentials ever change -----
+ # ----- Uncomment if you are fully managing ActiveMQ with Puppet. -----
+
+ # Package['activemq'] -> Class[$title]
+ # Java_ks['activemq_cert:keystore'] ~> Service['activemq']
+ # Java_ks['activemq_ca:truststore'] ~> Service['activemq']
+
+
+ # ----- Manage PEM files -----
+
+ File {
+ owner => root,
+ group => root,
+ mode => 0600,
+ }
+ file {"${activemq_confdir}/ssl_credentials":
+ ensure => directory,
+ mode => 0700,
+ }
+ file {"${activemq_confdir}/ssl_credentials/activemq_certificate.pem":
+ ensure => file,
+ source => $cert,
+ }
+ file {"${activemq_confdir}/ssl_credentials/activemq_private.pem":
+ ensure => file,
+ source => $private_key,
+ }
+ file {"${activemq_confdir}/ssl_credentials/ca.pem":
+ ensure => file,
+ source => $ca,
+ }
+
+
+ # ----- Manage Keystore Contents -----
+
+ # Each keystore should have a dependency on the PEM files it relies on.
+
+ # Truststore with copy of CA cert
+ java_ks { 'activemq_ca:truststore':
+ ensure => latest,
+ certificate => "${activemq_confdir}/ssl_credentials/ca.pem",
+ target => "${activemq_confdir}/truststore.jks",
+ password => $keystore_password,
+ trustcacerts => true,
+ require => File["${activemq_confdir}/ssl_credentials/ca.pem"],
+ }
+
+ # Keystore with ActiveMQ cert and private key
+ java_ks { 'activemq_cert:keystore':
+ ensure => latest,
+ certificate => "${activemq_confdir}/ssl_credentials/activemq_certificate.pem",
+ private_key => "${activemq_confdir}/ssl_credentials/activemq_private.pem",
+ target => "${activemq_confdir}/keystore.jks",
+ password => $keystore_password,
+ require => [
+ File["${activemq_confdir}/ssl_credentials/activemq_private.pem"],
+ File["${activemq_confdir}/ssl_credentials/activemq_certificate.pem"]
+ ],
+ }
+
+
+ # ----- Manage Keystore Files -----
+
+ # Permissions only.
+ # No ensure, source, or content.
+
+ file {"${activemq_confdir}/keystore.jks":
+ owner => $activemq_user,
+ group => $activemq_user,
+ mode => 0600,
+ require => Java_ks['activemq_cert:keystore'],
+ }
+ file {"${activemq_confdir}/truststore.jks":
+ owner => $activemq_user,
+ group => $activemq_user,
+ mode => 0600,
+ require => Java_ks['activemq_ca:truststore'],
+ }
+
+ }
+{% endhighlight %}
+
+
+### Step 3: Assign the Class to the ActiveMQ Server
+
+...using your standard Puppet site tools.
+
+### Step 4: Finish
+
+[Configure ActiveMQ to use the keystores in its `sslContext`][tls], probably with the Puppet template you're using to manage activemq.xml. **Double-check** that you've made activemq.xml world-unreadable, since it now contains sensitive credentials.
Code Review / packages / precise / mcollective.git / blobdiff