| <div class="wiki-content maincontent"><h3>Setting up the Key and Trust Stores</h3><p>Also see <a shape="rect" href="http://jakarta.apache.org/tomcat/tomcat-5.5-doc/ssl-howto.html">Tomcat's SSL instructions</a> for more info. The following was provided by Colin Kilburn. Thanks Colin!</p><structured-macro ac:macro-id="976b2a51-1506-40ba-ae9d-908d1a5545b2" ac:name="info" ac:schema-version="1"><parameter ac:name="title">ActiveMQ uses dummy credentials by default</parameter><rich-text-body><p>ActiveMQ includes key and trust stores that reference a dummy self signed cert. When you create a broker certificate and stores for your installation, either overwrite the values in the conf directory or delete the existing dummy key and trust stores so they cannot interfere)</p></rich-text-body></structured-macro><ol><li><p>Using keytool, create a certificate for the broker:</p><structured-macro ac:macro-id="91038e3a-caa3-4865-9974-074b6d87c07f" ac:name="code" ac:schema-version="1"><plain-text-body>keytool -genkey -alias broker -keyalg RSA -keystore broker.ks |
| </plain-text-body></structured-macro></li><li><p>Export the broker's certificate so it can be shared with clients:</p><structured-macro ac:macro-id="be4ed62e-85bb-4c7e-b02a-70b697c0d4d9" ac:name="code" ac:schema-version="1"><plain-text-body>keytool -export -alias broker -keystore broker.ks -file broker_cert |
| </plain-text-body></structured-macro></li><li><p>Create a certificate/keystore for the client:</p><structured-macro ac:macro-id="d7265148-3905-4928-a608-30e11f0a2c97" ac:name="code" ac:schema-version="1"><plain-text-body>keytool -genkey -alias client -keyalg RSA -keystore client.ks</plain-text-body></structured-macro></li><li><p>Create a truststore for the client, and import the broker's certificate. This establishes that the client "trusts" the broker:</p><structured-macro ac:macro-id="e573e708-be21-4b0f-a46d-40054c5d3e5e" ac:name="code" ac:schema-version="1"><plain-text-body>keytool -import -alias broker -keystore client.ts -file broker_cert</plain-text-body></structured-macro></li></ol><h3>Starting the Broker</h3><h4>Using the javax.net.ssl.* System Properties</h4><p>Before starting the broker's VM set the ACTIVEMQ_SSL_OPTS environment variable so that it knows to use the broker keystore.  (note that in previous versions of ActiveMQ this property was called SSL_OPTS in some scripts.  As of v5.12.0 all scripts use ACTIVEMQ_SSL_OPTS)</p><structured-macro ac:macro-id="1b53f6c7-66f1-4df8-9aaa-371607cd3e5c" ac:name="code" ac:schema-version="1"><plain-text-body>export ACTIVEMQ_SSL_OPTS = -Djavax.net.ssl.keyStore=/path/to/broker.ks -Djavax.net.ssl.keyStorePassword=password |
| </plain-text-body></structured-macro><h4>Using Spring to configure SSL for a Broker instance</h4><p>Sometimes the use of javax.net.ssl.* system properties is not appropriate as they effect all SSL users in a JVM. ActiveMQ 5.2.x adds an <sslContext> element to the <amq:broker> that allows a broker specific set of SSL properties to be configured.</p><p>The SslContext <a shape="rect" href="https://svn.apache.org/repos/asf/activemq/trunk/activemq-unit-tests/src/test/java/org/apache/activemq/transport/tcp/SslContextBrokerServiceTest.java">test case</a> validates starting an SSL transport listener using the configuration specified in the broker Xbean. The SslContext element is added to the broker as follows:</p><structured-macro ac:macro-id="e8315105-9b37-4739-a749-b7b7b512f6cc" ac:name="code" ac:schema-version="1"><plain-text-body><beans |
| <amq:broker useJmx="false" persistent="false"> |
| |
| <amq:sslContext> |
| <amq:sslContext |
| keyStore="broker.ks" keyStorePassword="password" |
| trustStore="client.ks" trustStorePassword="password"/> |
| </amq:sslContext> |
| |
| <amq:transportConnectors> |
| <amq:transportConnector uri="ssl://localhost:61616" /> |
| </amq:transportConnectors> |
| |
| </amq:broker> |
| </beans> |
| </plain-text-body></structured-macro><p>The SslContext is used to configure the <a shape="rect" href="https://svn.apache.org/repos/asf/activemq/trunk/activemq-client/src/main/java/org/apache/activemq/transport/tcp/SslTransportFactory.java">SslTransportFactory</a> for that broker. Full details of the configuration options available can be seen in the <a shape="rect" href="http://activemq.apache.org/schema/core/activemq-core-5.2-SNAPSHOT.xsd">schema definition</a> or in the accessors of <a shape="rect" href="https://svn.apache.org/repos/asf/activemq/trunk/activemq-spring/src/main/java/org/apache/activemq/spring/SpringSslContext.java">org.apache.activemq.spring.SpringSslContext</a></p><h3>Starting the Client</h3><p>When starting the client's VM, specify the following system properties:</p><structured-macro ac:macro-id="a25e8ade-909a-4083-8e1d-dc35710cf62d" ac:name="code" ac:schema-version="1"><plain-text-body>javax.net.ssl.keyStore=/path/to/client.ks |
| javax.net.ssl.keyStorePassword=password |
| javax.net.ssl.trustStore=/path/to/client.ts |
| </plain-text-body></structured-macro><structured-macro ac:macro-id="156cab22-46c8-47ee-9d80-84f5f67aaed8" ac:name="warning" ac:schema-version="1"><parameter ac:name="">Be careful on Linux</parameter><rich-text-body><p>In Linux, do not use absolute path to keystore. By default, keytool uses ~/.keystore, but in some setups passing -Djavax.net.ssl.keyStore=/home/account/.keystore to Java VM does not work. This is not ActiveMQ specific but good to keep in mind anyway.</p></rich-text-body></structured-macro><h3>Client certificates</h3><p>If you want to verify client certificates, you need to take a few extra steps:</p><ol><li><p>Export the client's certificate so it can be shared with broker:</p><structured-macro ac:macro-id="fd39bcff-a4ce-402b-871d-d0cf04657d86" ac:name="code" ac:schema-version="1"><plain-text-body>keytool -export -alias client -keystore client.ks -file client_cert |
| </plain-text-body></structured-macro></li><li><p>Create a truststore for the broker, and import the client's certificate. This establishes that the broker "trusts" the client:</p><structured-macro ac:macro-id="86e24c54-d55a-4818-8d02-45f6f0f20e80" ac:name="code" ac:schema-version="1"><plain-text-body>keytool -import -alias client -keystore broker.ts -file client_cert</plain-text-body></structured-macro></li><li><p>Add</p><structured-macro ac:macro-id="6bd663bb-0dd6-4f0d-8a17-3e9f7557b781" ac:name="code" ac:schema-version="1"><plain-text-body>-Djavax.net.ssl.trustStore=/path/to/broker.ts</plain-text-body></structured-macro><p>to ACTIVEMQ_SSL_OPTS</p></li><li><p>Instruct ActiveMQ to require client authentication by setting the following in activemq.xml:</p><structured-macro ac:macro-id="552bbf90-fc3d-4452-adb1-043f39b7a36c" ac:name="code" ac:schema-version="1"><plain-text-body> <transportConnectors> |
| <transportConnector name="ssl" uri="ssl://localhost:61617?needClientAuth=true" /> |
| </transportConnectors></plain-text-body></structured-macro></li></ol><h3>Certificate revocation</h3><p>Starting with version <strong>5.12</strong>, you can define certificate revocation list (CRL) path on ssl context, so that invalid certificates can revoked</p><structured-macro ac:macro-id="4711bfda-6a1d-4233-801a-0294d3b0619e" ac:name="code" ac:schema-version="1"><parameter ac:name="language">xml</parameter><plain-text-body> <sslContext> |
| <sslContext keyStore="org/apache/activemq/security/broker1.ks" |
| keyStorePassword="password" |
| trustStore="org/apache/activemq/security/activemq-revoke.jks" |
| trustStorePassword="password" |
| crlPath="org/apache/activemq/security/activemq-revoke.crl"/> |
| </sslContext></plain-text-body></structured-macro><p>This list is static and loaded on broker startup.</p><p>Starting with version <strong>5.14.0</strong>, you can also enable more advanced Online Certificate Status Protocol (OCSP) protocol. For that you need to configure a location for the<code> java.security</code> configuration extension by setting appropriate system properties (in <code>${ACTIVEMQ_HOME}/bin/env</code>) like</p><structured-macro ac:macro-id="8d57fab2-5a8b-4204-891d-94b910374942" ac:name="code" ac:schema-version="1"><plain-text-body>ACTIVEMQ_SSL_OPTS="-Djava.security.properties=$ACTIVEMQ_CONF/java.security"</plain-text-body></structured-macro><p>Then you need to configure OCSP responder properties in <code>java.security</code> file like</p><structured-macro ac:macro-id="4da0cadd-0e98-4b9e-8001-cb66c53b8c2c" ac:name="code" ac:schema-version="1"><plain-text-body>ocsp.enable=true |
| ocsp.responderURL=http://ocsp.example.net:80</plain-text-body></structured-macro><p>A demo of the broker configuration working with OCSP responder can be found at <a shape="rect" href="https://github.com/dejanb/sslib">https://github.com/dejanb/sslib</a></p><h3>Working Around Java 7 SSL Bugs</h3><p>As noted by issue AMQ-5970, it seems some versions of Java 7 have problems with SSL sessions that need to use the Diffie-Hellman cypher suite. If you run into this issue, just copy the Bouncy Castle bcprov-jdk15on-148.jar to ActiveMQ's lib directory and restart your broker.</p><h3>Useful links</h3><p>These links might also help</p><ul><li><a shape="rect" href="http://java.sun.com/j2se/1.4.2/docs/guide/security/jsse/JSSERefGuide.html#CreateKeystore">Sun's JSSE guide</a></li><li><a shape="rect" href="https://search.thawte.com/support/ssl-digital-certificates/index?page=content&id=SO10061">Thawte SSL Troubleshooting Tips</a></li></ul></div> |
| |
