website/reference/integration/activemq_ssl.md

   1 ---
   2 layout: default
   3 title: ActiveMQ TLS
   4 toc: false
   5 ---
   6
   7 [keystores]: /mcollective/deploy/middleware/activemq_keystores.html
   8 [sslcontext]: /mcollective/deploy/middleware/activemq.html#tls-credentials
   9 [transport]: /mcollective/deploy/middleware/activemq.html#transport-connectors
  10
  11 [activemq_connector]: /mcollective/reference/plugins/connector_activemq.html
  12 [ssl_security]: /mcollective/reference/plugins/security_ssl.html
  13 [aes_security]: /mcollective/reference/plugins/security_aes.html
  14
  15 You can configure MCollective and ActiveMQ to do end-to-end encryption over TLS. This allows you to use MCollective's fast and efficient [SSL security plugin][ssl_security] instead of the slow and hard to configure [AES security plugin][aes_security].
  16
  17 There are two main approaches:
  18
  19 * [CA-verified TLS](#ca-verified-tls) encrypts traffic, and also lets you restrict middleware connections --- only nodes with valid certificates from the site's CA can connect.
  20 * [Anonymous TLS](#anonymous-tls) encrypts messages to prevent casual traffic sniffing, and will prevent the passwords MCollective uses to connect to ActiveMQ from being stolen. However, it doesn't check whether nodes are allowed to connect, so you have to trust your username and password security.
  21
  22 This feature requires:
  23
  24 * MCollective 2.0.0 or newer
  25 * ActiveMQ 5.5.0 or newer
  26 * Stomp gem 1.2.2 or newer
  27 * The [activemq connector][activemq_connector] plugin (included with MCollective 2.0.0 and newer)
  28
  29 ## CA-Verified TLS
  30
  31 **(Recommended For Most Users)**
  32
  33 ### Summary
  34
  35 This approach configures MCollective and ActiveMQ to only accept connections when the peer has a certificate signed by the site's CA.
  36
  37 **Benefits:**
  38
  39 This approach gives extra security, and your MCollective servers will generally already have the credentials they need since you can re-use Puppet certificates.
  40
  41 **Drawbacks:**
  42
  43 You will need to go out of your way to issue keys and certificates to your admin users, which is an extra step when onboarding a new admin.
  44
  45
  46 ### Step 1: Configure ActiveMQ to Use TLS
  47
  48 Do the following steps to get ActiveMQ configured:
  49
  50 * Follow [the ActiveMQ keystores guide][keystores] to create Java keystores for ActiveMQ.
  51 * [Configure activemq.xml's `<sslContext>` element to point at the keystores.][sslcontext]
  52 * [Configure the proper URIs in the broker's transport connectors.][transport]
  53 * Restart ActiveMQ.
  54
  55 At this point, MCollective servers and clients should be unable to connect to ActiveMQ, since they do not yet have credentials configured.
  56
  57 ### Step 2: Configure MCollective Servers
  58
  59 For the MCollective daemon you can use your existing Puppet certificates by editing the _server.cfg_ file:
  60
  61 {% highlight ini %}
  62 connector = activemq
  63 # Optional:
  64 # plugin.activemq.base64 = yes
  65 plugin.activemq.pool.size = 1
  66 plugin.activemq.pool.1.host = stomp.example.com
  67 plugin.activemq.pool.1.port = 61614
  68 plugin.activemq.pool.1.user = mcollective
  69 plugin.activemq.pool.1.password = secret
  70 plugin.activemq.pool.1.ssl = true
  71 plugin.activemq.pool.1.ssl.ca = /var/lib/puppet/ssl/ca/ca_crt.pem
  72 plugin.activemq.pool.1.ssl.key = /var/lib/puppet/ssl/private_keys/<NAME>.pem
  73 plugin.activemq.pool.1.ssl.cert = /var/lib/puppet/ssl/certs/<NAME>.pem
  74 {% endhighlight %}
  75
  76 * Set the correct paths to each node's private key and certificate; they will be named after the node's Puppet certname and located in the ssldir.
  77     * You can locate a node's private key by running `sudo puppet agent --configprint hostprivkey`, the certificate with `sudo puppet agent --configprint hostcert`, and the CA certificate with `sudo puppet agent --configprint localcacert`.
  78 * Set the correct username and password.
  79
  80 ### Step 3: Configure MCollective Clients
  81
  82 Each client will now need a TLS certificate issued by the Puppet CA in order to be able to
  83 connect to the ActiveMQ:
  84
  85 {% highlight bash %}
  86 # puppet cert generate ripienaar
  87 notice: ripienaar has a waiting certificate request
  88 notice: Signed certificate request for ripienaar
  89 notice: Removing file Puppet::SSL::CertificateRequest ripienaar at '/var/lib/puppet/ssl/ca/requests/ripienaar.pem'
  90 notice: Removing file Puppet::SSL::CertificateRequest ripienaar at '/var/lib/puppet/ssl/certificate_requests/ripienaar.pem'
  91 {% endhighlight %}
  92
  93 Copy the certificates to your user:
  94
  95 {% highlight bash %}
  96 # mkdir /home/rip/.mcollective.d
  97 # cp /var/lib/puppet/ssl/ca/ca_crt.pem /home/rip/.mcollective.d/
  98 # cp /var/lib/puppet/ssl/private_keys/ripienaar.pem /home/rip/.mcollective.d/ripienaar-private.pem
  99 # cp /var/lib/puppet/ssl/public_keys/ripienaar.pem /home/rip/.mcollective.d/ripienaar.pem
 100 # cp /var/lib/puppet/ssl/certs/ripienaar.pem /home/rip/.mcollective.d/ripienaar-cert.pem
 101 # chown -R rip:rip /home/rip/.mcollective.d
 102 {% endhighlight %}
 103
 104 You can now configure the mcollective client config in _/home/rip/.mcollective_ to use these:
 105
 106 {% highlight ini %}
 107 connector = activemq
 108 # Optional:
 109 # plugin.activemq.base64 = yes
 110 plugin.activemq.pool.size = 1
 111 plugin.activemq.pool.1.host = stomp.example.com
 112 plugin.activemq.pool.1.port = 61614
 113 plugin.activemq.pool.1.user = ripienaar
 114 plugin.activemq.pool.1.password = secret
 115 plugin.activemq.pool.1.ssl = true
 116 plugin.activemq.pool.1.ssl.ca = /home/rip/.mcollective.d/ca_crt.pem
 117 plugin.activemq.pool.1.ssl.key = /home/rip/.mcollective.d/ripienaar-private.pem
 118 plugin.activemq.pool.1.ssl.cert = /home/rip/.mcollective.d/ripienaar-cert.pem
 119 {% endhighlight %}
 120
 121 If you are using the SSL security plugin, you can use these same files by setting `/home/rip/.mcollective.d/ripienaar.pem` as the public key.
 122
 123 ### Finish: Verify Encryption
 124
 125 If you want to be sure of this, you should now verify with tcpdump or wireshark that the connection and traffic
 126 really is all encrypted.
 127
 128 ### Troubleshooting Common Errors
 129
 130 You will get some obvious errors from this code if any files are missing, but the errors from SSL validation will be pretty
 131 hard to understand.
 132
 133 There are two main scenarios where ActiveMQ will reject an MCollective conneciton:
 134
 135 #### MCollective Uses Wrong CA to Verify ActiveMQ Cert
 136
 137 When the client connects using a CA set in _plugin.activemq.pool.1.ssl.ca_ that does not match the one
 138 in the ActiveMQ _truststore.jks_:
 139
 140 {% highlight console %}
 141 failed: SSL_connect returned=1 errno=0 state=SSLv3 read server certificate B: certificate verify failed
 142 {% endhighlight %}
 143
 144 And in the ActiveMQ log:
 145
 146 {% highlight console %}
 147 Transport failed: javax.net.ssl.SSLHandshakeException: Received fatal alert: unknown_ca
 148 {% endhighlight %}
 149
 150 #### MCollective Certs Aren't Signed by the Right CA
 151
 152 When your client has the correct CA but his certificates are not signed by that CA:
 153
 154 {% highlight console %}
 155 failed: SSL_connect returned=1 errno=0 state=SSLv3 read finished A: sslv3 alert certificate unknown
 156 {% endhighlight %}
 157
 158 And in the ActiveMQ log:
 159
 160 {% highlight console %}
 161 sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target
 162 {% endhighlight %}
 163
 164
 165
 166
 167
 168 ## Anonymous TLS
 169
 170 **(Less Recommended)**
 171
 172 ### Summary
 173
 174 This approach configures MCollective and ActiveMQ to encrypt traffic via TLS, but accept connections from anyone.
 175
 176 **Benefits:**
 177
 178 This approach requires less configuration, especially when adding new admin users.
 179
 180 **Drawbacks:**
 181
 182 This approach has some relative security drawbacks. Depending on your site's security needs, these may not concern you --- since MCollective's application-level security plugins will prevent an attacker from issuing agent commands and owning your servers, attacks like those below would only result in denial of service plus some leakage of inventory data via lower-level discovery protocols.
 183
 184 * Although attackers can't sniff MCollective's ActiveMQ passwords, there's nothing to prevent them from logging in if they steal a password through some other means. (With CA-verified TLS, on the other hand, they would also require a private key and certificate, which provides some additional security depth.)
 185 * An attacker able to run a man-in-the-middle attack at your site could fool your MCollective servers into trusting a malicious ActiveMQ server.
 186
 187
 188 ### Step 1: Configure ActiveMQ to Use Anonymous TLS
 189
 190 * Follow [the ActiveMQ keystores guide][keystores] to create a Java keystore for ActiveMQ. _You can skip the truststore._
 191 * [Configure activemq.xml's `<sslContext>` element to point at the keystore.][sslcontext] _You can skip the `trustStore` and `trustStorePassword` attributes._
 192 * [Configure the proper URIs in the broker's transport connectors][transport], but _leave off the `?needClientAuth=true` portion._
 193 * Restart ActiveMQ.
 194
 195
 196 ### Step 2: Configure MCollective Servers and Clients
 197
 198 Set the following settings in the `server.cfg` and `client.cfg` (or `~/.mcollective`) files:
 199
 200 {% highlight ini %}
 201 connector = activemq
 202 # Optional:
 203 # plugin.activemq.base64 = yes
 204 plugin.activemq.pool.size = 1
 205 plugin.activemq.pool.1.host = stomp.example.com
 206 plugin.activemq.pool.1.port = 61614
 207 plugin.activemq.pool.1.user = mcollective
 208 plugin.activemq.pool.1.password = secret
 209 plugin.activemq.pool.1.ssl = true
 210 plugin.activemq.pool.1.ssl.fallback = true
 211 {% endhighlight %}
 212
 213 The `plugin.activemq.pool.1.ssl.fallback` setting tells the plugin that it is allowed to:
 214
 215 * Connect to an unverified server
 216 * Connect without presenting its own SSL credentials
 217
 218 ...if it is missing any of the `.ca` `.cert` or `.key` settings or cannot find the files they reference. If the settings _are_ present (and point to correct files), MCollective will try to do a verified connection.
 219
 220
 221 ### Finish: Verify Encryption
 222
 223 If you want to be sure of this, you should now verify with tcpdump or wireshark that the connection and traffic
 224 really is all encrypted.