| # |
| # Licensed to the Apache Software Foundation (ASF) under one |
| # or more contributor license agreements. See the NOTICE file |
| # distributed with this work for additional information |
| # regarding copyright ownership. The ASF licenses this file |
| # to you under the Apache License, Version 2.0 (the |
| # "License"); you may not use this file except in compliance |
| # with the License. You may obtain a copy of the License at |
| # |
| # http://www.apache.org/licenses/LICENSE-2.0 |
| # |
| # Unless required by applicable law or agreed to in writing, |
| # software distributed under the License is distributed on an |
| # "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| # KIND, either express or implied. See the License for the |
| # specific language governing permissions and limitations |
| # under the License. |
| # |
| |
| Using SSL |
| ========= |
| |
| The implementation and use of SSL has some differences on Linux and |
| on Windows. |
| |
| Linux |
| ===== |
| |
| SSL support for Qpid-C++ is based on Mozilla's Network Security Services |
| library. SSL support will be built automatically providing this library |
| and include files are found at build time. |
| |
| Broker side SSL Settings (note you can get these by qpidd --help) |
| |
| SSL Settings: |
| --ssl-use-export-policy Use NSS export policy |
| --ssl-cert-password-file PATH File containing password to use for accessing |
| certificate database |
| --ssl-cert-db PATH Path to directory containing certificate |
| database |
| --ssl-cert-name NAME (hostname) Name of the certificate to use |
| --ssl-port PORT (5671) Port on which to listen for SSL connections |
| --ssl-require-client-authentication Forces clients to authenticate in order |
| to establish an SSL connection |
| --ssl-sasl-no-dict Disables SASL mechanisms that are vulner able to |
| passive dictionary-based password attacks |
| |
| The first four of these are also available as client options (where |
| they must either be in the client config file or set as environment |
| variables e.g. QPID_SSL_CERT_DB). |
| |
| To run either the broker or client you need ssl-cert-db-path to point |
| to the directory where relevant certificate and key databases can be |
| found. |
| |
| Certificate databases are set up using certutil (included in the |
| nss-tools package on fedora). See the NSS site for examples[1] and |
| full details[2]. |
| |
| For a simple testing you can set up a single db with a single self |
| signed certificate. E.g (with myhost and mydomain replaced by the |
| hostname and domainname of the machine in question respectively): |
| |
| mkdir test_cert_db |
| certutil -N -d test_cert_db -f cert.password |
| certutil -S -d test_cert_db -n "myhost.mydomain" \ |
| -s "CN=myhost.mydomain" -t "CT,," -x \ |
| -f cert.password -z /usr/bin/certutil |
| |
| Here cert.password is a file with a password in it that will be needed |
| for accessing the created db. |
| |
| The daemon can then be started with something like the following: |
| |
| ./src/qpidd --auth no \ |
| --ssl-cert-db ./test_cert_db \ |
| --ssl-cert-password-file ./cert.password \ |
| --ssl-cert-name myhost.mydomain |
| |
| then for client set: |
| |
| QPID_SSL_CERT_DB=./test_cert_db |
| |
| and run e.g. |
| |
| ./src/tests/perftest --count 10000 -P ssl --port 5671 \ |
| --broker myhost.mydomain |
| |
| When authentication is enabled, the EXTERNAL mechanism will be |
| available on client authenticated SSL connections. This allows the |
| clients authorisation id to be taken from the validated client |
| certificate (it will be the CN with any DCs present appended as the |
| domain, e.g. CN=bob,DC=acme,DC=com would result in an identity of |
| bob@acme.com). |
| |
| [1] http://www.mozilla.org/projects/security/pki/nss/ref/ssl/gtstd.html |
| [2] http://www.mozilla.org/projects/security/pki/nss/tools/certutil.html |
| |
| |
| Windows |
| ======= |
| |
| SSL support for Qpid-C++ on Windows is implemented using the Microsoft |
| Secure Channel (Schannel) package. Currently, only registry based |
| certificates scoped to the local machine are supported on the broker. |
| The client may specify client certificates in a user scoped store or in |
| a pkcs#12 file. |
| |
| For testing purposes, a self signed certificate can be created as |
| follows (requiring Administrator privilege on more recent versions of |
| Windows): |
| |
| makecert -ss qpidstore -n "CN=myhost.mydomain" -r -sr localmachine myhost.cer |
| |
| where "qpidstore" is an abitrary certificate store name. The |
| resulting output file "myhost.cer" is the public key of the |
| certificate that will be required by any client that wishes to |
| authenticate myhost. |
| |
| To run the server (also as Administrator on recent Windows versions): |
| |
| qpidd --ssl-cert-name myhost.mydomain --ssl-cert-store qpidstore [other-args] |
| |
| On the Windows client side, the SSL support is available without |
| loading a separate support module. For each machine or separate user |
| that will be using qpid, you must import the self signed certificate |
| as a trusted root. This can be done from the MMC certificate snapin |
| or directly using certmgr.exe. From the main window: |
| |
| select "Trusted Root Certification Authorities" |
| select "Action" -> "Import..." |
| then direct the Certificate Import Wizard to the "myhost.cer" file |
| |
| To test the setup: |
| |
| perftest --count 10000 -P ssl --port 5671 --broker myhost.mydomain |
| |
| To export the certificate to non Windows clients, note that |
| "myhost.cer" is the X.509 representation of the public key of the |
| certificate in DER format. Import the certificate into the other |
| clients if they support the DER format. Otherwise the certificate can |
| be converted to PEM format using OpenSSL |
| |
| openssl x509 -in myhost.cer -inform DER -out myhost.pem -outform PEM |
| |
| Client certificates operate much the same as for Linux, except for |
| identifying the certificate storage. Process environment variables |
| are used but the certificate name may be set or overridden by its Qpid |
| Messaging connection option. For Windows registry stores, you specify |
| the store: |
| |
| QPID_SSL_CERT_STORE=teststore |
| |
| If you omit the certificate store name, it defaults to the "Personal" or |
| "MY" store. For a certificate stored in a pkcs#12 format file, you must |
| supply the filename and a file containing the password for the |
| certificate's private key: |
| |
| QPID_SSL_CERT_FILENAME=wg444.pfx |
| QPID_SSL_CERT_PASSWORD_FILE=pw_wg444.txt |
| |
| The certificate is specified by its "friendly name", i.e. |
| |
| QPID_SSL_CERT_NAME=guest123 |
| |
| as an environment variable, or in the case of a Qpid Messaging |
| connection option: |
| |
| {transport:ssl,sasl-mechanism:EXTERNAL,ssl-cert-name:guest789} |